This module of Alien::GvaScript implements a mechanism for repeated elements within an HTML page. The main use is within forms, for dynamic expansion of subforms, so it is quite likely that you will want to use the Alien::GvaScript::Form API instead of calling the present module directly. However, the repeat mechanism will work for any kind of HTML element.

At initialization stage, the DOM is inspected for finding repeat elements (elements having a repeat attribute). These elements are removed from the DOM and replaced by placeholders (empty DOM elements, just marking where the repetition blocks should be inserted). Each placeholder stores a template, which is a plain string representation of the repeat element, with special markup for template instanciation. The template may then be dynamically instanciated into repetition blocks by calling the "add" method.

Any element marked with a non-empty repeat attribute is a repeat element; the value of that attribute defines the repeat name. Repeat elements can be nested, and their repeat names are used to distinguish at which level a repetition block should be instanciated.

Other attributes of the repetion model all start with the repeat prefix, as listed below; these attributes are optional.

defines the initial fragment of the repeat path (see explanation below). Only valid for top-level repetition elements, because nested repetition elements are automatically prefixed by their parent repetition element. Default is the empty string.

The content of a repeat element may contain special markup for repetition variables, which will be replaced by values when the element is instanciated into a repetition block.

Variables are written #{<repetition name>.<variable>}, like for example #{foo.ix}, #{foo.count} or #{bar.path}. The repetition name is the value of the repeat attribute of the repeat element, as explained above; in this namespace, the following variables are defined

Within the 3rd repetition block of bar, nested within the 2nd repetition block of foo, the value of #{bar.path} will be foo.2.bar.3 and therefore in this example the input name would be foo.2.bar.3.buz.

Implementation note: the #{...} syntax for variables is borrowed from prototype.js's Template class; however, the implementation of substitutions is done in plain javascript, without calling Template.evaluate() method.

Creates one or several new repetition blocks in the DOM, after the current blocks, by instanciating the repeat element repeat_name (including prefix). The count argument is optional and states how many blocks should be added; default is 1. Returns the final number of repetition blocks for that repeat element.

If the repeat structure looks like

<div repeat="foo" repeat-prefix="top">
<div repeat="bar">

then a new foo repetition block is instanciated through add('top.foo'), and a new bar repetition block is instanciated through add('#{foo.path}.bar').

Removes a repetition block from the DOM. The argument is either a DOM element or a string containing the element id.

param Boolean live_update: flag to indicate whether the 'remaining' repeatable sections are to be also removed from DOM, recreated by re-merging the data with repeat template, then finally re-appended to the DOM. Default true.

All repetition blocks below the removed block are renumbered, leaving no hole in the index sequence. To do so, these blocks are also removed from the DOM, and then added again through the "add" method.

If the repetition block is within a form, you probably want to call "remove" in Alien::GvaScript::Form instead of the present method, in order to properly preserve current form data.

This event is triggered whenever a repetition block is removed through the "remove" method. Since this method also removes all repetition blocks above the requested block, the event will be triggered once for each block.