Tangelo JavaScript Library — Tangelo Web Framework 0.10.0 documentation

# Tangelo JavaScript Library

The Tangelo clientside library (tangelo.js) contains functions to help work with Tangelo, including basic support for creating web applications. These functions represent basic tasks that are widely useful in working with web applications; for advanced functionality and associated JavaScript/Python functions, see Bundled Plugins.

`tangelo.` `version`()

  Return type: | string – the version string

  Returns a string representing Tangelo’s current version number. See A Note on Version Numbers for more information on Tangelo version numbers.

`tangelo.` `ensurePlugin`(pluginName)

  Arguments: | string (pluginName) – The name of the plugin whose existence to ensure

  Creates a Tangelo plugin namespace for pluginName, if it does not yet exist. If it already exists, this function does nothing.

  This is the standard way to ensure that a plugin has been created. For instead, if `foobar.js` introduces the foobar clientside plugin, it may contain code like this:

      tangelo.ensurePlugin("foobar");

      var plugin = tangelo.plugin.foobar;

      plugin.awesomeFunction = function () { ... };
      plugin.greatConstant = ...;

  As demonstrated here, once the existence of plugin foobar is guaranteed by the call to `tangelo.ensurePlugin()`, it can thereafter be referenced by the name `tangelo.plugin.foobar`.

`tangelo.` `getPlugin`(pluginName)

  Deprecated since version 0.10: See `tangelo.ensurePlugin()` for the replacement.

  Arguments: | string (pluginName) – The name of the plugin to retrieve
  Return type: | object – the contents of the requested plugin

  Returns an object containing the plugin contents for pluginName. If pluginName does not yet exist as a plugin, the function first creates it as an empty object.

  This is a standard way to create and work with plugins. For instance, if `foobar.js` introduces the foobar clientside plugin, it may contain code like this:

      var plugin = tangelo.getPlugin("foobar");

      plugin.awesomeFunction = function () { ... };

      plugin.greatConstant = ...

  The contents of this example plugin would hereafter be accessible via `tangelo.plugin.foobar`.

`tangelo.` `pluginUrl`(plugin[, *pathComponents])

  Arguments: | api (string) – The name of the Tangelo plugin to construct a URL for. *pathComponents (string) – Any extra path components to be appended to the constructed URL.
  Return type: | string – the URL corresponding to the requested plugin and path

  Constructs and returns a URL for the named plugin, with optional trailing path components listed in the remaining arguments to the function.

  For example, a call to `tangelo.pluginUrl("stream", "next", "a1b2c3d4e5")` will return the string `"/plugin/stream/next/a1b2c3d4e5"`. This function is useful for calls to, e.g., `$.ajax()` when engaging a Tangelo plugin.

`tangelo.` `queryArguments`()

  Return type: | object – the query arguments as key-value pairs

  Returns an object whose key-value pairs are the query arguments passed to the current web page.

  This function may be useful to customize page content based on query arguments, or for restoring state based on configuration options, etc.

`tangelo.` `absoluteUrl`(webpath)

  Arguments: | webpath (string) – an absolute or relative web path
  Return type: | string – an absolute URL corresponding to the input webpath

  Computes an absolute web path for webpath based on the current location. If webpath is already an absolute path, it is returned unchanged; if relative, the return value has the appropriate prefix computed and prepended.

  For example, if called from a page residing at `/foo/bar/index.html`, `tangelo.absoluteUrl("../baz/qux/blah.html")` would yield `/foo/baz/qux/blah.html`, and `tangelo.absoluteUrl("/one/two/three")` would yield `/one/two/three`.

`tangelo.` `accessor`([spec])

  Arguments: | object (spec) – The accessor specification
  Return type: | function – the accessor function

  Returns an accessor function that behaves according to the accessor specification spec. Accessor functions generally take as input a JavaScript object, and return some value that may or may not be related to that object. For instance, `tangelo.accessor({field: "mass"})` returns a function equivalent to:

      function (d) {
          return d.mass;
      }

  while `tangelo.accessor({value: 47})` return a constant function that returns 47, regardless of its input.

  As a special case, if spec is missing, or equal to the empty object `{}`, then the return value is the `undefined accessor`, which simply raises a fatal error when called.

  For more information of the semantics of the spec argument, see Accessor Specifications.