Repeater Views

The repeater view object contains various attributes used to render data within the repeater control. Each view includes a unique name that is selectable via the .repeater-views classed button group. The $.fn.repeater.views object adds the view object upon load using the unique view name as a key. Find more information on creating a repeater view extension below.

Default Options and Methods

Here are examples for adding default options and methods in your repeater view extension: {% highlight js %} //Adding default options to the repeater $.fn.repeater.defaults = $.extend({}, $.fn.repeater.defaults, { myView_additionalOption: false, myView_anotherOption: 'Hello World' }); //Adding methods to the repeater $.fn.repeater.Constructor.prototype.myView_additionalMethod = function () { //Do stuff here }; {% endhighlight %}

View Object

The main view object serves as the base for the repeater view extension. It's definition looks something like this: {% highlight js %} //View extension definition $.fn.repeater.viewTypes.myView = { cleared: function (helpers) { //Do stuff here } //Additional attributes listed as needed }; {% endhighlight %} The view object can contain a variety of attributes. All functions within the repeater view object are called with the repeater instance's context of this. The functions receive a helpers object, and in some cases a callback function. If a callback function is present, it must be called to proceed to the next step. The following attributes can be defined when developing a repeater view extension:

Name type description
cleared function Runs whenever the repeater canvas is cleared. Provided a helpers object containing the current repeater render options.
dataOptions function This function is called prior to calling the dataSource, allowing a view extension to provide additional options to the dataSource. Provided a options object as an argument, which is populated with current dataSource options and is expected to be passed back via the return statement after any manipulation in order to provide the repeater the newly altered dataSource options.
initialize function Runs only once at the beginning of each instantiation of the repeater. Provided a helpers object and callback function, which must be called in order for the repeater to proceed.
resize function Runs whenever the repeater is resized. Provided a helpers object containing width and height of the repeater.
selected function Runs every time this repeater view is selected prior to rendering. Provided a helpers object containing the previous repeater view (prevView)
before function This function is called prior to the renderItems function, if no render function has been defined. Provided a helpers object containing the parent container (the repeater canvas) for items to be inserted and data returned from the dataSource. Expects to be returned an item object, or false if no action is desired.
renderItem function This function is called after the before function, if no render function has been defined. It is iterated over the array specified by the repeat attribute. It is provided a helpers object containing the parent container (which will be whatever element within the repeater canvas has the data-container="true" attribute, or the canvas itself if not found) for items to be inserted, the data returned from the dataSource, the index of the current item within the iteration, and the subset array of data that the renderItem function is being iterated on. Expects to be returned an item object, or false if no action is desired.
repeat string This string value specifies which array the renderItem function iterates over. It represents an attribute of an object using dot notation. The root level value must use 'data' or 'this'. If the root value uses 'data', the root object will be the data object returned from the dataSource. If the root value uses 'this', the root object will be the current repeater instance context of this. You can specify further levels separated by dots. The final level must include an array or iteration will not function correctly. This array will be passed as the subset attribute in the helpers object of the renderItem function. The default value is 'data.items'
after function This function is called after the renderItems function, if no render function has been defined. Provided a helpers object containing the parent container (the repeater canvas) for items to be inserted and data returned from the dataSource. Expects to be returned an item object, or false if no action is desired.
render function If defined, before, renderItem, and after will be ignored, and this function will be called instead. It is provided a helpers object containing the parent container (the repeater canvas) for items to be inserted and data returned from the dataSource, as well as a callback function. The callback function must be called in order for the repeater to complete rendering. With this function, it is up to the view extension developer to append contents to the container as they see fit.

Item Object

The before, renderItem, and after functions can be returned item objects, which specify certain actions to be carried out by the repeater, such as inserting content:

Name type description
item string, jQuery object, or DOM node Specifies the content to be inserted into the container. If not specified, no action will be taken.
action string Optional. Specifies the jQuery mechanism of action to insert item content. If not specified, the default action will be 'append'. Any of the jQuery insertion methods can be used. If set to 'none', no insertion will occur.
container jQuery object, DOM node, or selector Optional. Specifies which element to insert the item content. If not specified, the default will be whatever the container was in the helpers object of the function that returned the items object.

Data Attributes

You can add a few data-attributes to any markup when rendering content to specify different rendering behaviors:

Name Value(s) description
data-container "true" If you add this value to an element within the repeater canvas in the before function, that element will become the container that is passed to the renderItem function.
data-infinite "true" If infinite scrolling is enabled, the element with this attribute becomes the infinite scrolling container.
data-preserve "deep" or "shallow" The repeater will preserve an element containing this attribute upon clearing the repeater of content. This clear occurs during each dataSource call. Set the value to "deep" to preserve the element and all children. Set the value to "shallow" to preserve just the element and remove any child nodes not marked with data-preserve.