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
  • nub.init
  • nub.get
  • nub.set
  • nub.del
  • nub.view
  • nub.removeView
  • nub.filter
  • nub.remote
  • HTMLFormModel
    • serialize
    • values
    • setData
    • load
    • submit
  • RemoteModel
    • meta
    • data
    • whenAvailable
    • load
    • reload
    • reset
    • httpGet
    • httpPut
    • httpPost
• $.nubList
  • 'list'
  • options
  • rowCount
  • hideEmptyRows
  • emptyRowCSS
  • pager
  • layoutPager
  • oninit

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:

• serialize: A function to use to serialize the model's data. By default, serializes to JSON.
• onrequest: A function to be called before the model submits a HTTP request. The function is passed an object with the following properties as the sole argument, and should return the same or similar object with any required modifications:
  • url
  • type
  • dataType
  • success
  • error
• onload: A function to be called before the model is updated after loading data. The function is passed the complete remote model object. The function can make modifications directly to this object, and the value it returns is the value written into Nub's global object.

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:

• uri: The URI of the last AJAX request (i.e. the URI of any data loaded into the model).
• timestamp: The time the current data was loaded at.
• status: The current status of the remote model's data. One of the following values:
  • preload: No data has been loaded yet.
  • loading: Data has been requested (using a GET request) but is not yet loaded.
  • submitting: A PUT or POST request has been submitted but is not yet completed.
  • loaded: Data has been loaded into the model.
• error: The error (if any) associated with the last AJAX request.
• ajax-status: The status of the last AJAX request.
• initData: The data loaded by the last request

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:

• string: Specify the request URI.
• function: Specify a callback function for successful requests.
• object: An options object. This object corresponds to the settings object passed to the standard jQuery $.ajax() function.

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:

• first: A function setting the list to the first page. Use e.g. as a 'first page' icon click handler.
• prev: A function setting the list to the previous page. Use e.g. as a 'previous page' icon click handler.
• $page: A jQuery object wrapping HTML for displaying the current page number.
• next: A function setting the list to the next page. Use e.g. as a 'next page' icon click handler.
• last: A function setting the list to the last page. Use e.g. as a 'last page' icon click handler.

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:

• listElement: The list element.
• pagerContainer: The element containing the list pager.

© InnerFunction Ltd., 2009-2011. All rights reserved.