NAME
    HTML::FormFu::ExtJS - Render and validate ExtJS forms using HTML::FormFu

VERSION
    version 0.074

DESCRIPTION
    This module allows you to render ExtJS forms without changing your
    HTML::FormFu config file.

      use HTML::FormFu::ExtJS;
      my $form = new HTML::FormFu::ExtJS;
      $form->load_config_file('forms/config.yml');

      print $form->render;

    HTML::FormFu::ExtJS subclasses HTML::FormFu therefore you can access all
    of its methods via $form.

    If you want to generate grid data and data records for ExtJS have a look
    at HTML::FormFu::ExtJS::Grid.

    This module requires ExtJS 2.2 or greater. Most of the elements work
    with ExtJS 2.0 or greater too.

    This module is fully compatible with ExtJS 3.0.

EXAMPLES
    Check out the examples in "examples/html"

METHODS
    A HTML::FormFu::ExtJS object inherits all methods of a HTML::FormFu
    object. There are some additional methods avaiable:

  render
    Returns a full ExtJS form panel. Usually you'll use it like this (TT
    example):

      var form = [% form.render %];

    You can pass custom attributes to this method which are added to the
    form config.

      var form = [% form.render(renderTo = 'main') %];

    This will add a "renderTo" attribute to the form config.

    "form" is now a JavaScript object of type "Ext.FormPanel". You might
    want to put a handler on the button so they will trigger a function when
    clicked.

      Ext.getCmp("id-of-your-button").setHandler(function() { alert('clicked') } );

    Or you can add the handler directly to your element:

      - type: Button
        value: Handler
        attrs:
          handler: function() { alert("click") }

  grid_data (experimental)
    This methods returns data in a format which is expected by ExtJS as perl
    object. You will want to serialize it with JSON and send it to the
    client.

      $form->grid_data($data);

    $data can be a DBIx::Class::ResultSet object, an arrayref of
    DBIx::Class::Row objects or a simple perl object which should look like
    this:

      $data = [{fieldname1 => 'value1', fieldname2 => 'value2'}];

    The returned perl object looks something like this:

      {
              'metaData' => {
                            'fields' => [
                                        {
                                          'name' => 'artistid',
                                          'type' => 'string'
                                        },
                                        {
                                          'name' => 'name',
                                          'type' => 'string'
                                        }
                                      ],
                            'totalProperty' => 'results',
                            'root' => 'rows'
                          },
              'rows' => [
                        {
                          'artistid' => '1',
                          'name' => 'Caterwauler McCrae'
                        },
                        {
                          'artistid' => '2',
                          'name' => 'Random Boy Band'
                        },
                        {
                          'artistid' => '3',
                          'name' => 'We Are Goth'
                        }
                      ],
              'results' => 3
            }

    The "metaData" property does some kind of magic on the client side. Read
    <http://extjs.com/deploy/dev/docs/?class=Ext.data.JsonReader> for more
    information.

    Sometimes you need to send a different number of results back to the
    client than there are rows (e. g. paged grid view). Therefore you can
    override every item of the perl object by passing a hashref.

      $form->grid_data($data, {results => 99});

    This will set the number of results to 99.

    Notice:

    This method is considered *experimental*. This is due to the fact that
    is pretty slow at the moment because of all the de- and inflation and
    accessing DBIC accessors. Future plans include that this module will be
    ORM independant and accepts Hashrefs only. This implies that you use
    DBIx::Class::ResultClass::HashRefInflator or anything similar if you
    want to use this method.

    "grid_data" will call all deflators specified in the form config file.
    Select elements will not display the acutal value but the label of the
    option it refers to.

  record
    "record" returns a JavaScript string which creates a "Ext.data.Record"
    object from the $form object. This is useful if you want to create
    "Ext.data.Record" objects dynamically using JavaScript.

    You can add more fields by passing them to the method.

      $form->record();
      # Ext.data.Record.create( [ {'name' => 'artistid', 'type' => 'string'},
      #                           {'name' => 'name', 'type' => 'string'} ] );
  
      $form->record( 'address', {'name' => 'age', type => 'date'} );
      # Ext.data.Record.create( [ {'name' => 'artistid', 'type' => 'string'},
      #                           {'name' => 'name', 'type' => 'string'},
      #                           {'name' => 'age', 'type' => 'date'},
      #                           'address' ] );

    To get the inner arrayref as perl object, call "$form->_record()".

  render_items
    This method returns all form elements in the JavaScript Object Notation
    (JSON). You can put this string right into the "items" attribute of your
    ExtJS form panel.

    Fields with the "omit_rendering" attribute set to a true value are not
    rendered, they are ignored. This feature is usefull if you have fields
    that are autogenerated on the client side.

  _render_items
    Acts like "render_items" but returns a perl object instead.

  _render_item
    Renders a single element.

  render_buttons
    "render_buttons" returns all buttons specified in $form as a JSON
    string. Put it right into the "buttons" attribute of your ExtJS form
    panel.

  _render_buttons
    Acts like "render_buttons" but returns a perl object instead.

  validation_response
    Returns the validation response ExtJS expects as a perl Object. If the
    submitted values have errors the error strings are formatted returned as
    well. Send this object as JSON string back to the user if you want ExtJS
    to mark the invalid fields or to report a success.

    If the submission was successful the response contains a "data" property
    which contains all submitted values.

    Examples (JSON encoded):

      { "success" : false,
        "errors"  : [
          { "msg" : "This field is required",
            "id"  : "field" }
        ]
      }


      { "success" : true,
        "data"    : { field : "value" }
      }

  column_model
    A column model is required to render a grid. It contains all columns
    which should be rendered inside the grid. Those can be hidden or
    visible. A hidden form element will also result in a hidden column.

    A field which has options (like HTML::FormFu::Element::Select) will
    create two columns.

    Example:

      ---
        default_model: HashRef
        elements:
            - type: Radiogroup
              label: Sex
              name: sex
              options:
                  - [0, 'male']
                  - [1, 'female']

    This will create the following columns:

            {
              'dataIndex' : 'sexValue',
              'hidden'    : true,
              'id'        : 'sex-value',
              'header'    : 'Sex'
            },
            {
              'dataIndex' : 'sex',
              'id'        : 'sex',
              'header'    : 'Sex'
            }

    The first column is hidden and contains the value of the select box (e.
    g. 0 or 1). The second column contains the label of the value (e. g.
    "male" or "female") and is visible.

    This way you can access both the value and the label of such a field.
    Notice the values of "dataIndex" and "id" on those columns. Those
    correspond with the output of "grid_data".

EXAMPLES
    These examples imply that you use Catalyst as web framework and Template
    Toolkit as the templating engine.

  simple form submission and validation
    Create a config file for the form (form.yml):

      ---
      action: /contacts/create
  
      elements:

      - type: Text
        name: name
        label: Name
        constraints:
          - Required

      - type: Text
        name: address
        label: Address
        constraints:
          - Required

      - type: Button
        name: submit
        default: Submit
        attrs:
          handler: submitForm

    In the last line there is a handler specified which is called when you
    press the submit button. This handler needs to be implemented using
    JavaScript.

    Usually you have a JavaScript file which contains all the code you need
    for your page. To render the form you need to put the form definition in
    this file. Pass the form object to the stash so that you can access it
    from the template.

      sub js : Local {
          my ($self, $c) = @_;
          my $form = new HTML::FormFu::ExtJS;
          $form->load_config_file('root/forms/form.yml');
          $c->stash->{form} = $form;
          $c->stash->{template} = 'javascript.tt2';
      }
  
      sub create : Path('/contacts/create') {
          my ($self, $c) = @_;
          my $form = new HTML::FormFu::ExtJS;
          $form->load_config_file('root/forms/form.yml');
          $form->process($c->req->params);
          if($form->submitted_and_valid) {
              # insert into database
          }
      
          $c->stash($form->validation_response);
          # Make sure a JSON view is called so the stash is serialized
      }

    javascript.tt2:

      var submitForm = function() {
        form.getForm().submit({
              success: function(rst, req) {
            // submission was successful and valid
            // you might want to close the form or something
          },
          failure: function() {
            // form validation returned errors
            // invalid fields are masked automatically  
          }
      }
      var form = [% form.render %];

FAQ
  How do I do server side validation?
    See "simple form submission and validation" and "validation_response".

  And how do I add client side validation?
    The FormFu constraints are not yet translated to ExtJS constraints. You
    can however add them manually in your form config:

      - type: Text
        name: text
        constraint:
          - Required
        attrs:
          allowBlank: 0

  How do I create custom FormFu::ExtJS elements?
    If you wish to write your own ExtJS element you have to do the
    following:

    First create an element which is a HTML::FormFu::Element.

      package HTML::FormFu::Element::MyApp::MyField;
    our $VERSION = '0.074';


      use base qw(HTML::FormFu::Element::Text);
      1;

    This is a very basic example for a field which is a text field. The
    ExtJS logic belongs to a different module:

      package HTML::FormFu::ExtJS::Element::MyApp::MyField;
    our $VERSION = '0.074';


      use base qw(HTML::FormFu::ExtJS::Element::Text);
  
      sub render {
          # you probably want to overwrite this!
      }
  
      1;

    Configure the form as follows:

      $form->populate( { elements => { type => 'MyApp::MyField', ... } } );

    If you don't want to put the element in the HTML::FormFu namespace then
    you have to prepend the class name with a "+". In this case the name of
    the ExtJS class changes as well:

      $form->populate( { elements => { type => '+MyApp::Element::MyField', ... } } );

    This requires the classes "MyApp::Element::MyField" and
    "MyApp::ExtJS::Element::MyField". The class must be in an "Element"
    namespace.

CAVEATS
  Multi
    The Multi element is rendered using the ExtJS column layout. It seems
    like this layout doesn't allow a label next to it. This module adds a
    new column as first element which has a field label specified and a
    hidden text box. I couldn't find a setup where this hack failed. But
    there might be some cases where it does.

  Select
    Optgroups are partially supported. They render as a normal element of
    the select box and are therefore selectable.

  Buttons
    Buttons cannot be placed in-line as ExtJS expects them to be in a
    different attribute. A button next to a text box is therefore (not yet)
    possible. Buttons are always rendered at the bottom of a form panel.

  Comments
    There is no support for comments yet. A work-around is to create a Multi
    element, add the element you want to comment in the first column and the
    comment as a Src element in the second column.

  Block
    Each element in a "Block" element is rendered normally. The "tag" config
    option has no influence. If the "Block" element contains a "content" it
    is rendered like a Src element.

TODO
    Write a Catalyst example application with validation, data grids and
    DBIC (sqlite).

SEE ALSO
    HTML::FormFu, JavaScript::Dumper

COPYRIGHT & LICENSE
    Copyright 2008-2009 Moritz Onken, all rights reserved.

    This program is free software; you can redistribute it and/or modify it
    under the same terms as Perl itself.