Namespace: uijet


The sandbox module.







Caches widget declarations before uijet is initialized, for lazy starting them at the end of its initialization, or if uijet IS initialized, ad-hoc constructs and initializes widget instance(s) from a given widget declaration(s).

Returns a {@see Promise} that is resolved once all declared/started instances finished initializing, or gets rejected if something fails.

It's best to declare widgets in the order of their appearance in the widgets tree (usually maps one-to-one to the DOM tree), so that a widget is always declared before its contained widgets are declared, and so on.

A declaration object usually contains type and config properties. It may also contain a factory property, instead of the type one, if this is an instance that's using a pre-declared widget factory.

  • type: a String that identifies a widget class created using uijet.Widget(type, ...).
  • factory: a String that identifies a widget factory created using uijet.Factory(factory, ...).
  • config: an Object that is used as the widget's options.

note: For valid instance options see related module.

note: If using the {@see Positioned} Mixin it's a must to declare widgets in a specific order ( see {@see uijet._position()} ).


An alias of {@see uijet.declare}.


private,staticuijet.__define(_name, _props, _deps){uijet}

uijet.js, line 1495

Caches a definition of a widget in uijet.

Name Type Description
_name string

identifier for the widget.

_props Object

the widget's prototype.

_deps Object optional

dependencies for this widget (widget and mixins).

private,staticuijet.__generate(type, extra_mixins){function}

uijet.js, line 1515

Generates a widget class on top of {@see BaseWidget}. Assumes all given dependencies (mixins and widget) are already loaded and registered with uijet.

Name Type Description
type string

this widget's type.

extra_mixins Array.<string> optional

extra mixins to mix into the generated widget class.

- missing widget/mixin dependency.
- the generated widget class.


uijet.js, line 1586

Performs all the work for {@see uijet.start()}.

Name Type Description
widget Object

a widget declaration.

Promise object.

private,staticuijet._buildContext(route, args_array){Object}

modules/router/_build-context.js, line 26

Builds a context object from the returned arguments of a route. Named parameters in route are indexed in the context object by name.

Also supports splat params using the prefix '*'.

Name Type Description
route string

The route string to analyze.

args_array * optional

The list of arguments sent to a route's callback.

object generated for the route.


uijet.js, line 1897

Destroys all the contained child widgets of widget with matching id.

Name Type Description
widget Object

the widget instance we want its children to call destroy().


uijet.js, line 1630

Registers a widget into the uijet sandbox. uijet uses the to register the widget. If this instance has a configured container in its options it's used as the identifier of its container widget instance. If not it climbs up the DOM tree looking for a uijet_widget class. The first element's id that has this class is used as the container. If none was found and it reached the body element then this instance will be registered as a top level widget. This, for example, means that, unless configured not to, once uijet starts this widget will be awaken automatically.

Name Type Description
widget Object

a widget's instance to register.


uijet.js, line 1881

Puts to sleep all of the contained child widgets of widget with matching id.

Name Type Description
widget Object

the widget instance we want its children to call sleep().

private,staticuijet._trickle(widget, context){uijet}

uijet.js, line 1927

Sets properties on the contained components of widget. This effect will continue to propagate recursively.

Name Type Description

a widget instance which contained components will be retreived.

context Object optional

a map of properties to send to contained widgets to set on their context. Defaults to the result of widget.getContext().


uijet.js, line 1742

Removes a widget from the uijet sandbox registry. This is usually triggered by a widget when its {@see BaseWidget.destroy()} method is called.

Name Type Description
widget Object

a widget's instance to unregister.

private,staticuijet._wakeContained(widget, context){Array.<Promise>}

uijet.js, line 1860

Wakes all of the contained child widgets of widget with matching id. If context is supplied it is passed to each child widget's wake(). Returns an array of promises, each returned from a child's wake().

Name Type Description
widget Object

the widget instance we want its children to wake.

context Object optional

context provided to the wake() call of this widget.

returned from children's wake() call.

staticuijet.Adapter(name, props){uijet|Object}

uijet.js, line 1273

Gets an adapter by name or defines a new adapter for widgets. If props is omitted and name is a:

  • string: Gets an adapter by this name
  • Object: Defines a new adapter that will be added at the top of every widget and overrides everything else
Name Type Description
name string | Object

a name of an existing or a new adapter or properties for a TopAdapter definition.

props Object optional

properties of the new adapter.

staticuijet.Factory(name, declaration){uijet}

uijet.js, line 1300

Defines a lazy factory of a widget declaration. This declaration can be re-used to prevent repetition of common properties.

It's possible to nest factories by using a factory in the declaration instead of type.

It's also possible to define a dynamic lazy factory as a function which will take the config object as an argument and will return a qualified declaration object.

Name Type Description
name string

identifier for this widget factory.

declaration Object | function

a viable object for {@see uijet.declare()} or a function that returns one.


uijet.js, line 1390

Initializes and starts the uijet sandbox and all the declared widgets. This also triggers the injection of all required modules. Returns a promise for the initialization and waking process of the entire app, unless disabled by the dont_wake/dont_start options.

It's possible to catch any exception thrown from that process by setting a rejection handler on the returned process.

Name Type Description
options Object optional

configuration object for uijet.

  • element: {string|HTMLElement} the container element of the application. Defaults to 'body'.
  • app_events: {Object} a map of names of app events to subscribe to, to their handlers.
  • resources: {Object} a map of names of resources to register, to their classes, or a tuple of the class and initial state.
  • dont_cover: {boolean} whether to instruct the app's container to stretch across the entire viewport. Defaults to false.
  • dont_start: {boolean} whether to call uijet.startup() and kick-start the UI. Defaults to false.
  • dont_wake: {boolean} whether to call wake() on all top level widgets. Defaults to false.
  • pre_startup: {function} optional hook for running logic before uijet starts up.
  • transition: {string} default type of transition to be used across the app. Defaults to 'fade'.
  • widgets: {object[]} optional list of widget declarations.
  • route_prefix: {string} optional prefix for routes to be used when creating those automatically from widget's IDs.
  • route_suffix: {string} As above, only suffix.
Note: The uijet app container element's visibility is initially set to hidden. If you set dont_start to true you'll have eventually invoke uijet.startup() yourself or set uijet.$element[0].style.visibility to visible.

staticuijet.Mixin(name, props){uijet|Object}

uijet.js, line 1252

Gets a mixin by name or defines a new mixin for widgets.

Name Type Description
name string

name of the mixin to get/define

props Object optional

properties defined by this mixin

staticuijet.Resource(name, resource, initial){uijet|Object}

uijet.js, line 1345

Gets a resource instance by name or registers a new resource instance. If initial is a true it registers resource as the resource instance under name. Otherwise, calls @see newResource that should be implemented by the module adapter to generate a new resource instance and registers it.

Optionally you can send any number of arguments to this method and they will be used as arguments for calling @see newResource, e.g: the second optional options argument for instantiating a Backbone.js resource.

Name Type Description
name string

identifier for that resource class.

resource Object optional

this resource's constructor.

initial boolean | Object | Array optional

initial data for the generated instance or true to reset the registry of name to be instance resource.

staticuijet.shall(topic, data){Promise}

uijet.js, line 1840

Publishes an app event with a passed deferred object containing resolve and reject methods, and optionally data, and returns the promise that's affected by resolution of this deferred.

This method is a mix of pub/sub and Promises that allows decoupled transfer of control from one component to another.

Name Type Description
topic string

a topic to publish.

data * optional

optional data to send with the published event.

promise that can be either resolved or rejected by a subscriber to topic.


uijet.js, line 1809

Starts up uijet. Publishes the startup event and wakes all widgets at the root of the widgets tree. If the pre_startup callback is defined it will run in the beginning.

note: If you are using a router module in your application, then you may want to set uijet's dont_wake option to true, so that the initial view is awaken by the router.

staticuijet.use(props, host, context){uijet}

uijet.js, line 1202

Adds functionality to a host object by copying the properties of props to the host object or uijet by default. If context is supplied then uses it to bind all the properties of props to it.

Name Type Description
props Object

the properties to mix-in to the host

host Object optional

host object to add these properties to, can be skipped by passing null

context Object optional

a context object to bind the mixed-in properties to

staticuijet.Widget(type, props, deps){uijet}

uijet.js, line 1227

Defines a new widget class. This class can later be instantiated in the UI or re-used as a dependency.

Name Type Description
type string

this widget's type.

props Object

properties defined by this widget.

deps string | Array | Object optional

dependencies for this widget.