/ 
HTML-FormFu-ExtJS-0.077
River stage one • 1 direct dependent • 3 total dependents
/ HTML::FormFu::ExtJS

NAME

HTML::FormFu::ExtJS

VERSION

version 0.077

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.

NAME

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

EXAMPLES

Check out the examples in examples/html

or online at [ Examples ]

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;
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;
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

AUTHOR

Moritz Onken <onken@netcubed.de>

COPYRIGHT AND LICENSE

This software is Copyright (c) 2010 by Moritz Onken.

This is free software, licensed under:

The (three-clause) BSD License