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.
These are the methods available on the core Nub object. The object is available as jQuery.nub or $.nub.
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. |
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.
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). |
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). |
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:
|
cx | A context path, used to resolve ref to an absolute path when it's a relative reference. (Optional). |
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). |
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:
|
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. |
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 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.
Return an object containing all the form's field's values. Values are stored on the object using properties named after the corresponding field.
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 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 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. |
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:
This is a property of the remote model and contains information about the model's current status. The meta object has the following properties:
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.
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 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 the model's data using the same URI and HTTP method as the previous load request.
Reset the model's data to what it was immediately after the last load request.
The following HTTP methods all accept arguments of the following types, in any order:
Load data into the model using a HTTP GET request. See above for method arguments.
Load data into the model using a HTTP PUT request. See above for method arguments.
Load data into the model using a HTTP POST request. See above for method arguments.
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.
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.
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:
number; The number of visible rows on the list.
boolean; If true then any rows without data will be hidden.
string; The name of a CSS class to apply to empty rows.
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.
function; Construct the DOM used to display the list's pager. The function is passed the following arguments:
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: