view release on metacpan or  search on metacpan

lib/Alien/GvaScript/Repeat.pod  view on Meta::CPAN

=head2 Terminology

At initialization stage, the DOM is inspected for finding
I<repeat elements> (elements having a C<repeat> attribute).
These elements are removed from the DOM and replaced
by I<placeholders> (empty DOM elements, just marking where
the repetition blocks should be inserted).
Each placeholder stores a I<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
I<repetition blocks> by calling the L</add> method.


=head1 HTML 

=head2 Markup of repeat elements

  <div repeat="foo" repeat-start="3" repeat-min="2" repeat-max="6" 
                    repeat-prefix="">
    <!-- content to be repeated, using #{foo.ix}, #{foo.path}, etc. -->
  </div>

Any element marked with a non-empty C<repeat> attribute is
a I<repeat element>; the value of that attribute defines
the I<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 C<repeat> prefix, as listed below; these attributes are optional. 

=over

=item repeat

marks the element as a repeat element, and defines the repeat name.

=item repeat-start

defines how many repetition blocks should be automatically
created as initialization time. Default is 1.

=item repeat-min

minimum number of repetition blocks. Prevents deletion
of repetition blocks under that number. Default is 0.

=item repeat-max

maximum number of repetition blocks. Prevents addition
of repetition blocks over that number. Default is 99.

=item repeat-prefix

defines the initial fragment of the C<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.

=back


=head2 String substitutions within repeat elements

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

=over

=item count

current number of repetition blocks for that repeat element, starting at 1.

=item ix 

integer index of the current repetition block, starting at 0.

=item path

cumulated list of repetition name and repetition indices, separated
by dots. 

=item min

value of the C<repeat-min> attribute.

=item max

value of the C<repeat-max> attribute.

=back

The C<path> is unique within any nesting of repeat elements,
and therefore is typically used for ids or for
names of input elements :

  <tr repeat="bar">
    <td>Item #{bar.count}</td>
    <td><input name="#{bar.path}.buz"></td>
  </tr>

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


I<Implementation note>: the C<< #{...} >> syntax for
variables is borrowed from C<prototype.js>'s C<Template>
class; however, the implementation of substitutions