Payload.js is a javascript single page application (SPA) driver that allows you to automate and manage REST API requests and render Handlebars templates or raw HTML from the response data. It also allows you to render Handlebars templates with expressions populated by data in memory, and includes a pub/sub, or publish/subscribe, API for managing custom events.

When DOM objects imbued with Payload.js's selectors are activated, a call to Payload.apiRequest() is performed, which involves making an XHR request and/or rendering a template. Payload.js also contains rendered template/response caching and an extensions API as additional means of integration.

• Installation
  • Install from NPM
  • Install from Bower
• Dependencies
• Selectors
• HTML5 API
• Payload.js Initialization Options
• Primary Methods
• Helper Methods
• API Request Handling
  • API Request Flow
  • API Callback Params
  • API Object & HTML Attributes
  • Template Data
• Payload.js Object Properties

Payload.js can be cloned or downloaded directly from GitHub, installed from NPM, or installed from Bower.

$ npm install payloadjs --save

$ bower install payloadjs --save

• jQuery >= v1.7
• Handlebars runtime - version depends entirely on your compiler version

Note: Handlebars is not required if you choose to only work with raw XHR responses, e.g. HTML returned directly from an API request.

Payload.js automatically binds to HTML elements based on the following selectors:

• Links (activated on click)
  • a[data-selector]
  • a[data-url]
  • button[data-selector]
  • button[data-url]
• Forms (activated on submit)
  • form[data-selector]
  • form[data-url]

Payload.js selectors can also contain the data-auto-load attribute to cause them to be automatically invoked on page/template load. Selectors are used to invoke API calls and/or render templates when they receive an appropriate trigger event or they are called directly with Payload.apiRequest().

The most useful feature of Payload.js is its intuitive HTML5 API. It can be used out of the box with little to no configuration and interacted with entirely from HTML. This makes Payload.js accessible to the non-javascript-savvy developer.

<button data-url="/api/endpoint"
        data-template="template-name"
        data-selector=".target-selector">
    Button text
</button>

• deliver(options) - Used to initialize the initial options to Payload.js and start monitoring the Payload.js context for events; see Payload.js Options.
• apiRequest($origin) - Automatically called when a selector is activated. May also be called explicitly by passing in a jQuery object with the proper data attributes. See API Request Handling for more information about this method.
• triggerAutoLoad($element) - Perform an API request on any DOM nodes containing the attribute data-auto-load. If $element is given, perform an API request on the given jQuery object instead of on the Payload.js $context.
• publish(eventName, arguments) - Publish a Payload.js. Any arguments given will pass through to the event handlers subscribed to the event named.
• subscribe(eventName, function) - Subscribe to a Payload.js event. When the specified event is published the function provided will be invoked and passed event-specific arguments.
• unsubscribe(eventName, function) - Stop subscribing to a Payload.js event.
• addSubscribers(subscribers) - Subscribe multiple functions to an array of events: subscribers={events: [], methods: []}.
• clearCache(type, key) - Based on the type, the cached "response" data will be cleared for the given key. If no type is specified all caches are cleared. If a type is specified but no key, then all items within that type of cache are cleared.

• merge(options) - Allows you to merge or extend the current Payload.js options with new options via the given object.
• serializeObject($form) - Serializes form data into an object, automatically creating arrays for form fields containing the same name.
• debug(m) - Allows you to pass in a single method as a string with the subsequent parameters being that method's arguments, OR pass in an object containing keys as method names and values as method arguments (single argument or array of multiple arguments).

Once a selector has been activated, Payload.js performs any API calls requested and renders the template specified. Your app can interact with Payload.js via various callback methods and by "subscribing" to API events. Upon completion of rendering a template, Payload.js will call Payload.triggerAutoLoad($target).

When performing an API request Payload.js will also manage showing and hiding loading indicators. If the "data-loading" attribute is set to "true" (or the "loadingDefault" option is true) the "$target" element will be cleared and have the "loadingHtml" inserted. Otherwise Payload.js will look for an element with the attribute data-role set to loading and call jQuery.show() on it.

Note that DOM objects must either perform an API call by having api.url set (see the API Object and HTML attributes) or specifying a template to load.

1. Subscribe to events with the beforeRender namespace to modify any data before the view is rendered.
2. Invoke apiCallback method set in Payload.js options (see API Callback Params).
3. If no API URL was specified or a cached view was used, publish the API events and trigger auto-load.
4. Show any configured loading indicators.
5. Perform the XHR. 1. Failures will invoke the xhrFail callback option. 1. The xhrAlways callback option always gets called on XHR completion. 1. The xhrDone callback is invoked upon a successful XHR.
6. If a template selector is defined, render the template into the specified location. If api.loading was set, the loading element will quickly fade out first. The xhrDone callback option is invoked, API events are published, and triggerAutoLoad($target) is called.
7. Cache the XHR response if requested.

When invoking events or invoking callbacks for apiCallback, apiBeforeRender, and apiAfterRender, a params argument is passed to the handler. It contains the following properties:

• $origin - The jQuery object the Payload.js API originated on.
• $target - The jQuery object pointed to by $origin's [data-selector] attribute.
• api - The API object described in API Object and HTML Attributes.

If the API call involves making a XHR request the following additional attributes are abilable on the "params" object:

• response - API response
• status - jQuery status result
• jqXHR - jQuery XHR response object
• html - template HTML (undefined until HTML is rendered)
• api - The API object described in API Object and HTML Attributes.

The API object defined below is passed within the API params to the various callback methods. The various options are controlled through HTML data- attributes on the $origin object, which points to a $target object for template rendering.

• href - The href attribute value from $origin; for reference and for use with an external routing component
• url - $origin data-url or action (form) attribute; Used as API URL if set
• method - $origin data-method or method attribute; HTTP method to use in API call (default: 'get')
• cacheRequest - $origin data-cache-request attribute; if true flag XHR request to be cached
• cacheResponse - $origin data-cache-response attribute; if true use cached response from Payload.js
• type - jQuery XHR request type (default: 'json')
• selector - $origin data-selector attribute; jQuery selector for the API $target that a template will be loaded into
• template - $origin "data-template" attribute; name of the Handlebars template to load into the location specified by data-selector(overridesdata-partial` if also set)
• partial - $origin data-partial attribute; name of the Handlebars partial template to load into the location specified by data-selector
• events - $origin data-publish attribute; space-separated list of events to have published to Payload.js subscribers
• requestData - combination of JSON serialized form data and any JSON-encoded values within $origin data-form attribute
• templateData - See Template Data below
• loading - $origin data-loading attribute; if "true" (or the loadingDefault option is true) the $target element will be cleared and have the loadingHtml from Payload.js options inserted during API request handling.

Every Handlebars template always has the following data available:

• app - Any custom application data contained in Payload.appData
• request - href, url, method, and cacheKey for the API call
• view - A dictionary of all data-* attributes from $origin

• options - Current set of options (see Payload.js Options)
• appData - Object for storing arbitrary application data; provided as app within template data
• cache - Object containing response cache; available for external component cache