Obviel API¶

Obviel core¶

obviel.iface(name[, *bases])¶

Declare an iface.

Arguments:	name (string) – A unique string identifying the iface. *bases – Optional extra iface strings that are interpreted as base ifaces that this iface extends.

Register an iface with the name name. Note that declaring an iface is not required in order to use it; you can just refer to any iface, declared or not, by name.

A registered iface always automatically extends a special iface base.

obviel.provides(obj, base)¶

Check whether an object provides an iface.

Arguments:	obj – Any JavaScript object. base (string) – A string identifying an iface.
Returns:	true if obj provides iface base (or an iface that extends base.

obviel.extendsIface(name, base)¶

Register a new base iface for an iface.

Arguments:	name (string) – Identifies the iface to extend. base (string) – Identifies the base iface that this iface extends.

obviel.ifaces(obj)¶

Obtain all ifaces that this object provides, going recursively through base interfaces, breadth first.

If no ifaces attribute is available, the JS type of the object is returned instead.

Arguments:	obj – Any JavaScript object
Returns:	a list of ifaces that the obj provides.

obviel.clearTemplateCache()¶

Clear the template cache from any cached templates. Useful to do as cleanup between unit test.

class obviel.View(settings)¶

Arguments:	settings – an object of which the properties will become properties of the view itself.

You can create a View by instantiating one and then registering it with obviel.view(), but that function also allows creation of a new view directly from a settings object.

If you want to create your own view types that provide more features particular to specific use cases, you should derive your view from the View class. One example of this is Widget() from the Obviel forms library.

obviel.view(view)¶

Register a view with Obviel. This allows Obviel to look up the view for the iface with which the view was registered.

Arguments:	view – a view object to register with Obviel. As a convenience, you can also provide a bare JavaScript object, which will be converted to a View() object with the object’s properties.

obviel.unregisterView(iface, name)¶

Unregister view with Obviel. Obviel will forget about the view again. This is particularly useful during test cleanup, not during normal application running-time.

Arguments:	iface (string) – the iface of the view you want to unregister. name (string) – the name of the view you want to unregister. Optional; the default name is default.

obviel.transformer(transformer)¶

Arguments:	transformer – a function with the function(obj, url, name) signature, or function(obj, url), or function(obj).

Register a transformer function with Obviel. Obviel will pass any object retrieved from the server using URL access (i.e. a hyperlink reference in an object) through this transformer function.

The transformer function has three arguments:

obj

The object retrieved from the server that can be transformed.

url

The URL used to access the object on the server. Could be used to determine what transformation to apply. Optional.

name

The name used to render the view. Optional.

The transformer function must return the transformed object.

By default Obviel does no transformation, and objects are passed from the server to Obviel unchanged.

You can disable the transformer function by passing in null.

obviel.eventHook(hook)¶

Arguments:	hook – a function with the signature function().

Register an event hook function with Obviel. Obviel will call this hook whenever an event is handled by Obviel Template. By default the event hook does nothing. This can be used in combination with Obviel Sync to automatically commit the session in event handlers.

You can disable the event hook by passing in null.

obviel.httpErrorHook(hook)¶

Arguments:	hook – a function with the signature function(xhr) where xhr is a jqXHR object as in use with jQuery $.ajax.

Register a hook function that gets called whenever an jQuery $.ajax call fails during rendering (though not during template load). This is the case when calling render on a URL, in subviews which call render on a URL, using the form validation URL, and the autocomplete form widget which uses a URL to receive autocomplete data.

element.render(obj[, name])¶

Render a view for an object on a jQuery element. This instantiates a view by cloning it from the registered view and then calls its obviel.View.render() method.

Arguments:	obj – The JavaScript object to render. Alternatively this can be a string, which will then be interpreted as a URL. The URL will be fetched and the resulting JSON object will be the object to render. name – The name of the view to render for the object. If not supplied the name default will be used.
Returns:	A promise. You can hook in a function to be called when rendering has completed, such as $(el).render(obj).done(function(view) { });

All methods of the View() object will have access to the following properties on this during rendering:

• el: the jQuery element that the view is being rendered on.

• obj: the object being rendered.

• registry: the Registry() in which the view was

  looked up.

element.rerender()¶

Re-render (non-ephemeral) view on element.

Returns:	A promise. You can hook in a function to be called when rendering has completed, such as $(el).render(obj).done(function(view) { });. view will be null in case there was no view on this element to rerender.

If there is a previous view on the element, and the view was rendered from an object, the object is re-rendered on the element.

If there is a previous view on the element and the view was rendered from a URL, the object for the URL is re-fetched and then rendered.

If there is no previous view on the element, nothing will happen.

element.view()¶

Get the (non-epheremal) view previously rendered on element.

Returns:	The non-ephemeral view previously rendered on the element. If no non-ephemeral view was rendered on the element, undefined is returned.

element.parentView()¶

Get nearest view registered on element or parent.

Returns:	The non-ephemeral view rendered on element, or if missing, walk up the ancestor chain until a view is found. If no view can be found return null.

element.unview()¶

Remove non-ephemeral view from element, executing any view cleanup. If no view exists on this element, nothing happens.

Obviel Template¶

Everything is in the obviel.template namespace.

class obviel.template.CompilationError()¶

Exception. Something went wrong during compilation of a template.

el¶

The JavaScript DOM node, typically an element node, on which compilation failed.

message¶

Message describing what went wrong during compilation.

class obviel.template.RenderError()¶

Exception. Something went wrong during compilation of a template.

el

The JavaScript DOM node, typically an element node, on which rendering failed.

message

Message describing what went wrong during rendering.

obviel.template.registerFormatter(name, func)¶

Register a global formatter. Is done when the UI starts up (per page), before any templates are compiled. Note that with Obviel you can also use view methods as formatters.

Arguments:	name (string) – the name of the formatter. This is how it is addressed in the template language (using {foo|formatterName}). func (function) – the formatting function. It gets the text (string) to format as its argument and should return the formatted text.

obviel.template.getFormatter(name)¶

Return a global formatter. If no formatter can be found, undefined is returned.

Arguments:	name (string) – the name of the formatter to look up.
Returns:	the formatter function or undefined.

obviel.template.clearFormatters()¶

Clear all previously registered formatters. Typically used during unit test teardown.

obviel.template.registerFunc(name, func)¶

Register a global element adjustment function. Is done when the UI starts up (per page), before any templates are compiled. Note that with Obviel you can use view methods as funcs

Arguments:

name (string) – the name of the function. This is how it is addressed in the template language (using data-call="funcName"). func (function) – the function that manipulates the element. This function takes 1 to 3 arguments: the jQuery element el to manipulate, a variable resolver function (optional) and a context object (optional). Should manipulate the element, for instance by using el.addClass. The variable resolver function can be used by the function to look up variables; get the value of variables in the current scope by calling it with a variable name as a string (variable(variableName)).

obviel.template.getFunc(name)¶

Return a global element adjustment function. If no func can be found, undefined is returned.

Arguments:	name (string) – the name of the func to look up.
Returns:	the func or undefined.

obviel.template.clearFuncs()¶

Clear all previously registered funcs. Typically used during unit test teardown.

class obviel.template.Template()¶

A template. To instantiate and compile, create a new Template object with a text argument. The text argument should be a HTML fragment that will be compiled, or alternatively a jQuery selector indicating an element to be compiled (everything in it will be compiled).

Can throw CompilationError() if the text could not be compiled.

render(el, obj, context)

Render template on jQuery element el, using obj to resolve variables, and using context as the rendering context.

Arguments:

el (object) – jQuery element to render the template on. obj (object) – Object to render. Variables in the templates will be resolved from obj. context (object) – This is an object that may have these properties: getTranslation A function that takes a single string argument and returns the translation for that string. If no translation is available the string itself should be returned. If not supplied no translations are looked up. Used by data-trans. getHandler A function that gets a single name argument and returns the event handler that matches that name. If no handler can be found by that name, null should be returned. Used by data-on. getFormatter A function that gets a single name argument and returns the formatter function that matches that name. This function will get a single value argument and should return the formatted value. If no formatter can be found by that name, null or undefined should be returned. Used by {variable|formatter}. If no getFormatter is supplied, the template engine will use globally registered formatters (using obviel.template.registerFormatter). See also obviel.template.registerFormatter(). getFunc A function that gets a single name argument and returns the element manipulation function that matches that name. This function will get three arguments: the element to manipulate, a variable lookup function and a context. If no func can be found by that name, null or undefined should be returned. Used by data-call to look up the func. If no getFunc is supplied, the template engine will use globally registred funcs (using obviel.template.registerFunc). See also obviel.template.registerFunc().

Returns:

A promise, so you can hook in .done(function()) { } that will be called when the template is done rendering.

obviel.template.variables(translation, variables)¶

A simple way to interpolate variables into a text, in particular for the purposes of i18n.

Given a text with variables (marked with { and }) and an object (hash) of variables, interpolate variables into text. This can be used from JavaScript to interpolate Obviel Template-like translation variables, instead of jsgettext’s strargs, which only works with positional values.

Arguments:	text (string) – The text (with variables). arguments (object) – A key-value mapping where the key is the variable name.
Returns:	The text with variables interpolated.

obviel.template.tokenize(text)¶

Tokenize text using Obviel Template rules. Name tokens are marked by { and }, the rest are text tokens.

Arguments:	text (string) – Text to tokenize.
Returns:	an array of token objects. Each token object has a type property that indicates the token type (NAME_TOKEN or TEXT_TOKEN, and a value property. In case of NAME_TOKEN this is the name between { and }, in case of TEXT_TOKEN this is the text.

Obviel Forms¶

A form structure is could be returned from the server-side but an also be defined on the client. It should have the iface viewform.

obviel.iface('customField', 'inputField')

// constructor
module.CustomWidget = function(settings) {
   settings = settings || {};
   var d = {
       iface: 'customField' // set up iface
   };
   $.extend(d, settings);
   module.InputWidget.call(this, d); // call superclass
};

// set up inheritance
module.CustomWidget.prototype = new module.InputWidget();

module.CustomWidget.prototype.validate = function(value) {
  // use inherited validate function first
  var error = module.InputWidget.prototype.validate.call(this, value);
  // if we have an error in inherited validation, we are done, return
  // that error
  if (error !== undefined) {
      return error;
  }
  // custom validation goes here, either do: return undefined (or
  // plain bare return) or return error message
  return undefined;
}

// convert function is necessary if we convert to non-String JavaScript
// value. Can also be used for strings even if we don't convert
// away from it, for instance to check whether a date string is really
// parseable at all, and to format it to a common format if so.
// in addition convert and its pair convertBack can be used to update
// the browser DOM in more complex ways than the default implementation
// allows.
module.CustomWidget.prototype.convert = function(value) {
  // convert the empty input to null, so that validation for
  // required can do its work
  if (value === '') {
      // return an object with a ``value`` property with the converted value.
      return {value: null};
  }
  // try to interpret the input as the value type we want
  var asint = parseInt(value, 10);
  // if the interpretation did not succeed, return an object
  // with an ``error`` property with the error message.
  if (isNan(asint)) {
      return {error: 'not a number'};
  }
  // return an object with a ``value`` property with the converted value.
  return {value: asint};
}

// convert a JavaScript representation back into the widget representation
// (typically a string)
module.CustomWidget.prototype.convertBack = function(value) {
  // super call
  value = module.InputWidget.prototype.convertBack.call(this, value);
  return value.toString();
}

// finally register the widget as a view with Obviel
obviel.view(new module.CustomWidget());

Traject¶

Everything is in the obviel.traject namespace.

class obviel.traject.ParseError()¶

A parse error when parsing a path.

message

The error message.

class obviel.traject.ResolutionError()¶

Error resolving a path to an object: object cannot be found.

message

The error message.

class obviel.traject.LocationError()¶

Error constructing a location (or path) for an object.

message

The error message.

class obviel.traject.RegistrationError()¶

Error during registration.

message

The error message.

class obviel.traject.Patterns()¶

registerConverter(converterName, converterFunc)¶

Register a variable converter.

Arguments:	converterName (string) – The name of the converter as it will appear in the variable declaration ($foo:<converterName>). converterFunc (function) – A function that takes the variable to convert and returns the converted variable.

register(patternStr, lookup)¶

Register a lookup function for a path pattern.

Arguments:

patternStr (string) – A path pattern. These are zero or more steps separated by /, where each steps is either a string, or a $variable (or $variable:converter). lookup (function) – A function that should return the object matching the path variables. It will receive a single variables object as an argument, and its properties are the concrete values used in the path in place of the variables. It can also return null or undefined, indicating thatd the object cannot be found.

Can throw ParseError() if the path cannot be parsed.

Can throw RegistrationError`() if the path cannot be registered due to unknown converters or conflicts in registration.

registerInverse(iface, patternStr, inverse)¶

Register an inverse function (from object to variables) for objects of an iface and a pattern.

Arguments:

iface (string) – The iface that this inverse is registered for. When an object is located, the iface of the object is used to look up the inverse function. patternStr (string) – A path pattern as for register(). This is used to reconstruct the path for the objects. inverse (function) – A function that takes an object as an argument and returns a variables object for it that can be used to reconstruct its path, so should have a property for each of the variables in the path.

pattern(iface, patternStr, lookup, inverse)¶

Register both a path lookup as well as the inverse at the same time.

Arguments:

iface (string) – The iface that this inverse is registered for. When an object is located, the iface of the object is used to look up the inverse function. patternStr (string) – A path pattern as for register(). This is used to reconstruct the path for the objects. lookup (function) – A function that should return the object matching the path variables. It will receive a single variables object as an argument, and its properties are the concrete values used in the path in place of the variables. inverse (function) – A function that takes an object as an argument and returns a variables object for it that can be used to reconstruct its path, so should have a property for each of the variables in the path.

Can throw ParseError() if the path cannot be parsed.

Can throw RegistrationError() if the path cannot be registered due to unknown converters or conflicts in registration.

setDefaultLookup(f)¶

Register a function that looks up a default object for those paths that don’t have a more specific lookup registered for them.

Param :	function f: A function that returns a default object.

resolve(root, path)¶

Resolve a path to an object according to registered patterns, starting at root.

Arguments:	root (object) – An object that is the root to the virtual hierarchy created by traject. When following trajectParent back you will end up at the root object. path (string) – A concrete path. It will be matched with the registered paths to find the lookup function.
Returns:	The object found.

Can throw ResolutionError() in case the path cannot be resolved to an object.

resolveStack(root, stack)¶

Resolve a stack to an object according to registered patterns, starting at root. A stack is a stack of steps in a path, in reverse order.

Arguments:	root (object) – An object that is the root to the virtual hierarchy created by traject. When following trajectParent back you will end up at the root object. stack (array) – A stack of steps, in reverse order from the path. It will be matched with the registered paths to find the lookup function.
Returns:	The object found.

Can throw ResolutionError() in case the stack cannot be resolved to an object.

consume(root, path)¶

Resolve a path as far as it can be resolved according to registered patterns, then stop resolving the path. Does not throw a ResolutionError(), instead simply stops.

Arguments:	root (object) – An object that is the root to the virtual hierarchy created by traject. When following trajectParent back you will end up at the root object. path (string) – A concrete path. It will be matched with the registered paths to find the lookup function.
Returns:	An object with three properties, unconsumed, an array of steps that could not be resolved (in stack form, reverse order), consumed, those steps that have been successfully consumed when resolving the path, and obj, the object found at the end of path consumption (if no path could be consumed at all, this object will be root).

consumeStack(root, stack)¶

Resolve a stack of steps as far as it can be resolved according to registered patterns, then stop resolving the stack. Does not throw a ResolutionError(), instead simply stops.

Arguments:	root (object) – An object that is the root to the virtual hierarchy created by traject. When following trajectParent back you will end up at the root object. stack (array) – A stack of steps, in reverse order from the path. It will be matched with the registered paths to find the lookup function.
Returns:	An object with three properties, unconsumed, an array of steps that could not be resolved (in stack form, reverse order), consumed, those steps that have been successfully consumed when resolving the path, and obj, the object found at the end of path consumption (if no stack could be consumed at all, this object will be root).

locate(root, obj)¶

Locate obj, giving it trajectName and trajectParent properties and placing it in a virtual hierarchy, such that following trajectParent will eventually result in the root object.

Arguments:	root (object) – An object that is the root to the virtual hierarchy created by traject. When following trajectParent back you will end up at the root object. obj (object) – The object to locate.

Can throw LocationError() in case the object can not be located.

path(root, obj)¶

Locate obj, and return its path. This also gives the obj trajectName and trajectParent properties and places it in a virtual hierarchy, such that following trajectParent will eventually result in the root object.

Arguments:	root (object) – An object that is the root to the virtual hierarchy created by traject. When following trajectParent back you will end up at the root object. obj (object) – The object to get the path for.
Returns:	The path for obj according to the patterns.

Can throw LocationError() in case the object can not be located.

Obviel i18n¶

Everything is in the obviel.i18n namespace.

class obviel.i18n.I18nError()¶

Exception. Something went wrong during translation; in particular a locale or domain cannot be found.

message

Message describing what went wrong.

obviel.i18n.translationSource(data)¶

Create a source of translations from mapping.

Arguments:	data (object) – A mapping from the language used in the source code to the language being translated to. Alternatively can use a more complicated jsgettext array structure as values.
Returns:	The translation source.

obviel.i18n.translationSourceFromJsonUrl(url)¶

Create a source of translations from a URL.

Arguments:	url (string) – A URL to a JSON object that contains a jsgettext-based translation.
Returns:	The translation source.

obviel.i18n.emptyTranslationSource()¶

Create an empty source of translations. This means no translation will take place. This can be useful to register the translations for the locale that the UI is written in.

Returns:	The translation source.

obviel.i18n.registerTranslation(locale, translationSource[, domain])¶

Register a translation source for a locale and a domain.

Arguments:	locale (string) – A locale identifier, such as en_US. translation_source – A translation source. domain – The i18n domain for the translations. If domain is not specified, the default domain is used.

obviel.i18n.clearTranslations()¶

Clear the translations. Useful during test teardown.

obviel.i18n.setLocale(locale)¶

Changes the locale that the application is working in to a new one. This loads the locale information according to previously specified information, for instance using obviel.i18n.load().

Arguments:	locale (string) – A locale identifier, such as en_US.
Returns:	A promise that is done when the locale has been loaded.

obviel.i18n.clearLocale()¶

Clears the locale that the application is working in to an empty one. Useful during test teardown.

obviel.i18n.getLocale()¶

Returns the current locale. This is null if no locale has been set.

obviel.i18n.getTranslation(msgid, domain)¶

Gives back the translation for a msgid in a particular domain, given the current locale.

Arguments:	msgid (string) – The message id or text to translate. domain (string) – The translation domain.
Returns:	The translation for msgid in the domain.

obviel.i18n.getTranslationFunc(domain)¶

Gives back a function that takes the msgid and returns the translation in the domain.

Arguments:	domain (string) – The translation domain.
Returns:	A function that can be given a msgid to return the translation in the specified domain.

obviel.i18n.translate(domain)¶

Set up translations for a module. Intended to be called at the top of your module, like this:

var _ = obviel.i18n.translate('foo');

This changes the template domain to foo, and also returns a function that when called with a message id, will return the translation in the domain foo. The convention is to assign this to _ so that extraction tools can extract occurrences from .js source code.

Arguments:	domain (string) – The translation domain.
Returns:	A function that can be given a msgid to return the translation in the specified domain and current locale.

obviel.i18n.pluralize(domain)¶

Set up plural translations for a module. Intended to be called at the top of your module, like this:

var ngettext = obviel.i18n.translate('foo');

The ngettext function can be called with three parameters:

• singular text (“1 elephant”)
• plural text (“three elephants”)
• count

Based on the value of count either the singular text or plural text will be used, and translated to the current locale and the specified domain (foo, in this case).

Arguments:	domain (string) – The translation domain.
Returns:	A function that can be given a singular msgid, a plural msgid and a count and will return the right text for the locale, domain and count.

obviel.i18n.getTemplateDomain()¶

Gives back the default domain in use by Obviel templates.

obviel.i18n.variables(translation, variables)¶

An alias for obviel.template.variables(). Only available if Obviel Template is available when Obviel i18n is being loaded.

obviel.i18n.load()¶

Load i18n information as indicated by link elements in document. This should be called when the document is ready.

The link tags should look like this:

<link href="something.i18n" ref="i18n" type="application/json" />

The .i18n file indicated is a JSON file that describes what translations are available for which domains. You can link in multiple .i18n files in one page. The .i18n file should look like this:

{
   "<domain>": [
       {
         "locale": "<locale>",
         "url": "<localeUrl>"
       }
   ]
}

A domain may have information about more than one locale. The .i18n file may have entries for more than one domain. The url entry may be a relative URL, relative to the URL of the .i18n file itself. url may also be null, in which case the locale will not have any translations available and thus will be in the source language.

Returns:	A promise that is done when the i18n information has been loaded. Recommended is you do the obviel.i18n.setLocale() in the done handler.