view release on metacpan or  search on metacpan

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

Similarly, when a repetition block is added into 
the form through the L</add> method, the first
element within that repetition block that possesses
an C<autofocus> attribute automatically receives focus.

=head1 METHODS

=head2 destroy

  gvascript_form.destroy()

instance destructor -  will unregister the GvaScript.Form instance from the GvaScript.Forms namespace and will remove all of its observers.

=head2 getId

  gvascript_form.getId()

returns the id of the form element that the gvascript_form instance is wrapped around.

=head2 fire

  gvascript_form.fire(eventName[, arg])

used to fire event on the for instance and thus called corresponding responders and instance callback.

C<eventName>: eventName to fire without the 'on' prefix.


C<arg> argument to send over to the corresponding responder(s) and callback.

this method will 

=over

=item 1. 

execute the early responders set the on[eventName]

=item 2. 

execute instance on[eventName] callback

=item 3. 

execute the responders set the on[eventName]

=back

execution sequence will stop whenever one of the responders or callback returns C<false>

NOTE that the B<onBeforeSubmit, onSubmit> events cannot be notified programatically. 
You actually need to call form.submit() for these events to be fired.

=head2 register

   gvascript_form.register(expression, eventName, handler)
   GvaScript.Form.register(form, expression, eventName, handler)

tells the form to watch the I<eventName> on elements that match the I<expression> and to fire the corresponding I<handler>.

C<expression> (String) - A css selector

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