view release on metacpan or  search on metacpan

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

C<eventName> (String) - The name of the event, in all lower case, without the "on" prefix — e.g., "click" (not "onclick"). 

A custom B<"init"> event is also supported which is fired on an input that gets its value initialized with the initialization of the form.

C<handler> (Function) - handler to fire.

Signature

  function handler(event[, newValue[, oldValue]]) {
    event.target // element being observed
  }

C<newValue> is set for the C<change> and the C<init> events.

C<oldValue> is set for the C<change>.

B<NOTE:> Form.Element.setValue method is wrapped in GvaScript.ProtoExtensions module to programatically fire the blur event after setting the value on the input, and hence firing the change handler if any.

[I<This method can be called either as an instance method or as a generic method. If calling as a generic, pass the form HTMLElement/id in as the first argument.>]

=head2 unregister

   gvascript_form.unregister(expression[, eventName[, handler]])
   GvaScript.Form.unregister(form, expression[, eventName[, handler]])

removes observers set on given C<expression>.  if C<eventName> is provided, will only stop observing that eventName.
if C<handler> is also provided, will just stop calling this handler.

NOTE that the same handler signature should be used in the register method for it to work in the unregister method.

[I<This method can be called either as an instance method or as a generic method. If calling as a generic, pass the form HTMLElement/id in as the first argument.>]

=head2 init

   gvascript_form.init(initial_tree, prefix)
   GvaScript.Form.init(form, initial_tree, prefix)

C<form> is the id of a form (or directly the DOM element).  Optional
C<initial_tree> is a javascript nested datastructure containing
initial values for fields, that will be passed to the 
L</fill_from_tree> method.

[I<This method can be called either as an instance method or as a generic method. If calling as a generic, pass the form HTMLElement/id in as the first argument.>]

=head2 to_hash

  var flat_hash = GvaScript.Form.to_hash(form);

Inspects the contents of all fields in C<form> and 
returns a flat hash of pairs (key-value).

[I<This method can be called either as an instance method or as a generic method. If calling as a generic, pass the form HTMLElement/id in as the first argument.>]

=head2 to_tree

  var tree = GvaScript.Form.to_tree(form);

Inspects the contents of all fields in C<form> and 
returns a data tree, were dotted names in form names
are expanded into sub-arrays or sub-hashes. So for example 
if the form looks like

  <input name="father.firstname"> <input name="father.lastname"><br>
  <input name="mother.firstname"> <input name="mother.lastname"><br>
  <div repeat="child" repeat-start="1">
    <input name="#{child.path}.firstname"><br>
  </div>

and if that form has been expanded with 3 repetition blocks
for children, the resulting tree would be

  { "father" : {"firstname" : ..., "lastname": ...},
    "mother" : {"firstname" : ..., "lastname": ...},
    "child"  : [ {"firstname": ...},
                 {"firstname": ...},
                 {"firstname": ...} ] }

[I<This method can be called either as an instance method or as a generic method. If calling as a generic, pass the form HTMLElement/id in as the first argument.>]

=head2 fill_from_tree

  GvaScript.Form.fill_from_tree(form, field_prefix, tree);

Fills the form from values found in C<tree> (this is the 
reverse of the L</to_tree> operation).
Optional C<field_prefix> is prepended to key names in C<tree> for
finding the corresponding form fields.

The method walks through nested subtrees in C<tree>: the sequence
of keys leading to a leaf is concatenated into a flat string, with dot 
separators, and if the form has a corresponding input element,
the value of that element is set to the value of the leaf.
Furthermore, if the initial tree contains repeated data sets
(array subtrees), and if the form contains repeat elements
with the same path, then new repetition blocks are 
dynamically created to match the number of items in the array:
so if the form above is filled with the following tree

  { "child"  : [ {"firstname": "Abel"},
                 {"firstname": "Bob"},
                 {"firstname": "Cod"},
                 {"firstname": "Dave"}, ] }

then four repetition blocks will automatically created in the form.

[I<This method can be called either as an instance method or as a generic method. If calling as a generic, pass the form HTMLElement/id in as the first argument.>]

=head2 add

  GvaScript.Form.add(repeat_name, count);

Creates one or several new repetition blocks.  The parameter C<count>
is optional and defaults to 1.  Focus is automatically given to the
first input element in the last repetition block that has an
C<autofocus> attribute (if any).

See L<Alien::GvaScript::Repeat/add> for more explanations on
the C<add> operation.

=head2 remove