view release on metacpan or  search on metacpan

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

=encoding ISO8859-1

=head1 NAME

Alien::GvaScript::Repeat - Support for repeated sections

=head1 SYNOPSIS

  <div repeat="foo">
    <h2>Foo #{foo.count}</h2>
    This is the repeated foo section
    <table>
      <tr repeat="bar">
        <td>Item #{bar.count}</td>
        <td><input name="#{bar.path}.buz"></td>
        <td><button onclick="GvaScript.Repeat.remove('#{bar.path}')">
              Remove this row
            </button></td>
      </tr>
    </table>
     <button onclick="GvaScript.Repeat.add('#{foo.path}.bar')">
        Add a bar
     </button>
  </div>  
  <button onclick="GvaScript.Repeat.add('foo')">Add a foo</button>

  <script>
    GvaScript.Repeat.init(document.body);
  </script


=head1 DESCRIPTION

This module of L<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 L<Alien::GvaScript::Form> API instead of calling the
present module directly. However, the repeat mechanism will work for
any kind of HTML element.

The design is partially inspired by the C<Web Forms 2.0> proposal
(L<http://www.whatwg.org/specs/web-forms/current-work/>), but is 
not an attempt to implement the proposed specification: there are
some differences both in syntax and in semantics.


=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