Nub API

This document describes the different methods and options made available by the Nub jQuery plugin and its associated frameworks.

See the Nub introduction for an overview of Nub and its capabilities.

Contents

Core Nub

These are the methods available on the core Nub object. The object is available as jQuery.nub or $.nub.

nub.init( [cx], [opts] )

Initialize any views or models within the DOM.

Arguments:
cx An element or jQuery object to use as the initialization context. (i.e. only the context's descendent elements will be initialized). Optional; defaults to document.body.
opts Options for customizing Nub's behaviour, which will only be applied to this initialization. See $.nub.model.options in the source code for a list of the available options.

nub.get( ref, [cx] )

Read a value from the model.

Arguments:
ref The reference path of the value to read.
cx A context path, used to resolve ref to an absolute path when it's a relative reference. (Optional).

Returns the requested value.

nub.set( ref, [value], [cx] )

Set a value in the model. Notifies all observing views that the data item has been updated.

Arguments:
ref The reference path of the value being set.
value The new value.
cx A context path, used to resolve ref to an absolute path when it's a relative reference. (Optional).

nub.del( ref, [value], [cx] )

Delete a value from the model. Notifies all observing views that the data item has been deleted.

Arguments:
ref The reference path of the value being deleted.
value The value to be deleted. The handling of this value is model dependent, but it can be used to control or limit the values removed from the model. (Optional).
cx A context path, used to resolve ref to an absolute path when it's a relative reference. (Optional).

nub.view( ref, view, [cx] )

Register a view with the Nub controller.

Arguments:
ref The reference path of the value the view will observe.
view The view object. Can be any of the following types:
  • DOM element: The element's content will be updated with the data item's value.
  • DOM attribute: The attribute's value will be updated with the data item's value.
  • DOM text node: The node's text value will be updated with the data item's value.
  • Form input: The input's value will be updated with the data item's value.
  • function: The function will be invoked whenever the data item is updated.
cx A context path, used to resolve ref to an absolute path when it's a relative reference. (Optional).

nub.removeView( ref, view, [cx] )

Deregister a view from the Nub controller.

Arguments:
ref The reference path of the value the view to be removed is observing.
view The view object to be removed.
cx A context path, used to resolve ref to an absolute path when it's a relative reference. (Optional).

nub.filter( sourceRef, resultRef, filterFn )

Create a Nub filter. Creates a new data item in the model whose value is calculated from another value in the model using a filter function. The data item will be updated whenever the source data is updated.

It is possible to specify a set of arguments for the filter function. These arguments are placed in the model at the path resultRef / filter:args. Any updates made to the arguments through the Nub controller will cause the filter to be re-evaluated.

Arguments:
sourceRef The location of the filter's source data in the model.
resultRef The location in the model where the filter's result data is stored.
filterFn The filter function. The function will be invoked with two arguments:
  • data: This is the filter's source data, as specified by the sourceRef path.
  • args: Additional filter arguments.

nub.remote( ref, [opts] )

Create a remote model in Nub's global model.

Arguments:
ref The location of the new remote model.
opts Options to pass into the model. See RemoteModel for details.


HTMLFormModel

A HTMLFormModel is used to represent Nub forms within the model. A Nub form is defined by marking a FORM element with the nub-form class. Nub will insert the form model into the global model at the path /nub:forms / name, where name is the form's name as specified with the NAME attribute. (If no NAME attribute is specified then Nub will allocate a unique value). Once instantiated, the form model can be read from the model and the following methods can be used.

serialize( )

Serialize the form's fields. Uses the jQuery serialize function. Returns a string containing the forms URL encoded values as a series of name/value pairs, separated by ampersands.

values( )

Return an object containing all the form's field's values. Values are stored on the object using properties named after the corresponding field.

setData( data )

Set form data.

Arguments:
data An object containing values for the form's fields. The object's property names should correspond to the form's field names.

load( [opts] )

Load data into the form over AJAX. Uses the form's method and action values to specify default values for the AJAX request's type and URI. All of these values can be overriden by the opts argument.

Arguments:
opts Additional options for the Ajax request. This object corresponds to the settings object passed to the standard jQuery $.ajax() function.

submit( [opts] )

Submit the form data over AJAX. Uses the form's method and action values to specify default values for the AJAX request's type and URI. All of these values can be overriden by the opts argument.

Arguments:
opts Additional options for the Ajax request. This object corresponds to the settings object passed to the standard jQuery $.ajax() function.


RemoteModel

A RemoteModel can be used to represent remote data within Nub's model. Remote models should be created using the $.nub.remote method.

Remote models can be initialized with the following options:

meta

This is a property of the remote model and contains information about the model's current status. The meta object has the following properties:

data

This is a property of the remote model and contains the model's data. All data loaded from the remote server will be placed under this property.

whenAvailable( callback, [repeat] )

Provide a function which will only be called once data has been loaded into the model. If data has already been loaded when the method is called then the callback will be invoked immediately; otherwise, it won't be called until (and unless) data is loaded into the remote model.

Arguments:
callback The function to be called once data is available. The remote model object is passed as its only argument.
repeat If true then the function will be called each time data is loaded; otherwise, the function will only be called once after the first data load.

load( [opts] )

Load data into the model.

Arguments:
opts Additional options for the Ajax load request. This object corresponds to the settings object passed to the standard jQuery $.ajax() function, and will be passed to the model's onrequest function before it is passed to the ajax() function.

reload( )

Reload the model's data using the same URI and HTTP method as the previous load request.

reset( )

Reset the model's data to what it was immediately after the last load request.

HTTP methods

The following HTTP methods all accept arguments of the following types, in any order:

httpGet( )

Load data into the model using a HTTP GET request. See above for method arguments.

httpPut( )

Load data into the model using a HTTP PUT request. See above for method arguments.

httpPost( )

Load data into the model using a HTTP POST request. See above for method arguments.


$.nubList( opts )

The nubList function is part of Nub's list framework and is used to initialize list elements and access list objects. The function is invoked as a method on the jQuery object, e.g. $('#my-list-element').nubList(). Note that the function can only be applied to any HTML element, but TABLE, UL and OL elements will give predictable results.

The next two items describe the 'opts' argument.

'list'

When the opts argument is the string 'list' then the function will return the Nub list object associated with the element wrapped by the jQuery object, if any.

options

An options object argument can be passed into the nubList function when initializing a list element. The options object can have any of the following properties:

rowCount

number; The number of visible rows on the list.

hideEmptyRows

boolean; If true then any rows without data will be hidden.

emptyRowCSS

string; The name of a CSS class to apply to empty rows.

pager

boolean; If true then display a list pager. This will allow a user to page through data lists larger than the number of visible rows on the list.

layoutPager

function; Construct the DOM used to display the list's pager. The function is passed the following arguments:

The function should use jQuery's DOM manipulation methods to build and return a DOM representing the pager layout. For an example function, see the Nub list framework's default pager layout function in $.fn.nubList.

oninit

function; Called once the list DOM has been setup, and which can be used to perform additional initialization of the list's elements. The function is passed two arguments: