view release on metacpan or  search on metacpan

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

=encoding ISO8859-1

=head1 NAME

Alien::GvaScript::Form - Wrapper around HTML Forms

=head1 SYNOPSIS

  <form id="my_form" onsubmit="return false;">
    <div repeat="foo">
      <h2>Foo #{foo.count}</h2>
      <input type="text" name="person.name"/>
      <input type="text" name="person.bdate"/>
      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.Form.remove('#{bar.path}')">
                Remove this row
              </button></td>
        </tr>
      </table>
       <button onclick="GvaScript.Form.add('#{foo.path}.bar')">
          Add a bar
       </button>
    </div>  
    <button onclick="GvaScript.Form.add('foo')">Add a foo</button>
  </form>

  <script>
    var gvascript_form = new GvaScript.Form('my_form', {
      datatree: {name:'kitty', bdate:'01.01.1990'},
      dataprefix: 'person',
      // 'active' form elements 
      registry: [
        ['input', 'mouseover', function(event) {}],
        ['input', 'mouseout',  function(event) {}],
        ['input', 'change',    function(event, newv ,oldv) {}],
        ['input', 'init',      function(event, newv) {}]
      ],
      // handlers to form's custom events
      onInit: function(gva_form) {},
      onRepeatBlockRemove: function(gva_form, arg) {
        arg[0] // removed repeat name
        arg[1] // removed repeat path
      },
      onRepeatBlockAdd: function(gva_form, arg) {
        arg[0] // added repeat name
        arg[1] // added repeat path
      },
      onChange: function(gva_form, event) {
        // event.target -> element changed
        // event.memo.oldvalue -> changed element's old value
        // event.memo.newvalue -> changed element's new value
      },
      onSubmit: function(gva_form) {
        // ....
        // do form submission
        // ....
        if(success)               {gva_form.fire('AfterSubmit', arg)}
        else 
        if(data_validation_error) {gva_form.fire('DataValidationError', arg)}
        else                      {gva_form.fire('SubmitFailure', arg)} 
      },
      onAfterSubmit: function(gva_form, arg) {},
      onDataValidationError: function(gva_form, arg) {},
      onSubmitFailure: function(gva_form, arg) {},
      onBeforeDestroy: function(gva_form, arg) {}
    }
  </script>


=head1 DESCRIPTION

This module of L<Alien::GvaScript> manages forms with
hierarchical fields and dynamically repeated sections.
It works in close collaboration with  L<Alien::GvaScript::Repeat>.

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.

=head1 Constructor

  new GvaScript.Form(form_id[, options])

=over 12

=item form_id

id of the HTML form to extend

=item options

hash of optional properties that would define the behavior of the form

=over 

=item datatree

tree represention of the initial form data. 

Ex: 

  { 
    name: 'barbie', 
    age: '49', 
    friends: [
      { name: 'ken', age: '35' }, 
      { name: 'jen', age: '55' }
    ] 
  }

=item dataprefix

sometimes it's helpful to prefix the html input names to give them 'context'.

Ex: C<doll.name> C<doll.friends.0.name>.

in this example, the dataprefix should be set to 'doll'

=item registry

a list of arrays C<[expression, eventName, handler]>.

each item in the array would be passed over to the L</notify> method.

=item onInit

function to be called after the successful initialization of the GvaScript.Form instance.

=item onRepeatBlockRemove

function to be called after a block in a repeated section is removed

Signature

  function onRepeatBlockRemove(gva_form, arg) {
    // gva_form : GvaScript.Form instance