BantamJS Documentation

Installation

The recommended way of adding BantamJS to your project is using the Bantam Coop module manager. Once Coop is installed, the latest version of Bantam can be installed with the following command:

$ python coop.py add bantam +2.1

If you don't want to use Coop, Bantam can be added to your project in two additional ways: downloaded onto your server, or linked directly from ours. We recommend you download the file onto your own server, as it provides more stability in the event that our servers are offline.

Downloading: Download a copy of the latest minified version of the library (linked at the top of this page). Store it on your server. Add it into any required page with the following tag.

Direct Linking: Add BantamJS into any required page with the following tag.

Recent Updates

Library Functions

When BantamJS is added to a page, it creates a new global $bt object. Most functions in the library are available through this object. The get, add, erase, and toggle methods are written into the prototype to allow them to be chained. BantamJS implements the following methods:

$bt.get

Purpose: Returns an HTML DOM element, or array of elements, that match the specified identifier.

Signature: $bt.get(identifier)

Usage: The identifier is a string taking one of four forms. When the identifier begins with a hash sign, as in '#element-id', this method returns the exact HTML DOM element with the given ID. When the identifier begins with a period, as in '.class-name', this method returns a NodeList of all the HTML DOM elements with the given class. When the identifier is enclosed in brackets, as in [href] or [href="#target"], this method returns a NodeList containing all the HTML DOM elements that have the provided attribute (former case), or that have the provided value for that attribute (latter). When the identifier does not begin with any special character, as in 'tag', the method returns a NodeList of all the HTML DOM elements of the given tag in the page.

The protype version of this method can be called on an HTML DOM element, and returns specifically those elements that are descendants of the current element. For example $bt.get('#navbar').get('a') returns all the <a> tags within the element with the id navbar.

Examples:

$bt.map

Purpose: Runs the specified function over a collection of elements, returning the results or modifying them in place.

Signature: $bt.map(list, callback)

Usage: The function takes two arguments. The first, list, is an iterable collection of data to be processed. The second, callback is a callback function that will be called on each element within list. The callback function takes up to two arguments: the item from the data list (passed first), and the index in the iteration (passed second). The index is useful for modifying select list entries (e.g. highlighting every other row in a table). If the callback function returns a value, the map function returns an array of those resulting values.

Examples:

.add

Purpose: Adds the provided CSS class to the given HTML DOM element.

Signature: HTMLElement.prototype.add(className)

Usage: This method can be used to add a CSS class to the given element. It does not affect any other classes currently on the element. A prototype method, it is called on the element directly. For example $bt.get('#identifier').add('hidden').

Examples:

.erase

Purpose: Removes the provided CSS class from the given HTML DOM element.

Signature: HTMLElement.prototype.erase(className)

Usage: This method can be used to remove a CSS class from the given element; if the given class appears multiple times, all occurrences will be removed. This method does not affect any other classes currently on the element.

A prototype method, it is called on the element directly. The syntax is identical to add.

Examples:

.toggle

Purpose: Toggles the provided CSS class on the given HTML DOM element.

Signature: HTMLElement.prototype.toggle(element, className)

Usage: If the given class does not appear on the element, it will be added as in .add. If the class already appears on the element, it will be removed as in .erase. This method does not affect any other classes currently on the element.

A prototype method, it is called on the element directly. The syntax is identical to add.

Examples:

$bt.render

Purpose: Renders an HTML template by populating it with the provided data values.

Signature: $bt.render(template, data)

Usage: This function takes a template parameter, a string containing raw HTML. This HTML may have one or more special template fields, denoted by a name surrounded by single curly braces (without spaces). The data parameter is an object with properties corresponding to these template fields. For example, the template field {firstName} will be replaced with the value in data.firstName.

Note: The performance of the render function scales linearly with the number of properties in the data object, regardless of whether or not they appear in the template. It is inadvisable to pass data parameters with many properties beyond those needed to render the template.

Examples:

$bt.ajax

Purpose: Makes an asynchronous AJAX call back to the server.

Signature: $bt.ajax(endpoint, settings)

Usage: The endpoint parameter is a string containing the URL of the endpoint we are making this call to. The settings parameter is an object containing any settings passed to this AJAX call. These may include the following:

Examples:

$bt.scroll

Purpose: Scrolls the top of the browser window to the given offset (in pixels, from the top of the page).

Signature: $bt.get(offset, duration, callback)

Usage: The offset parameter is a distance from the top of the page, in pixels. This is the point to which the top of the browser window will be scrolled. The duration parameter is the duration of the animation, in milliseconds. The optional callback parameter is a function that will be executed when the scrolling is complete.

Examples: