Package names must be in JAAS::Widget.  

TEXT WIDGET

my $widget=JAAS::Widget::Text->new(name=>'foo', title=>'What is your foo?',
                  source=>'object-name/foo',
                  class=>'miffle',
                  validation=>['required']);

name is used for the label (I18N) if 'title' is missing.  Source is an
opaque value used to get/set fields during the capture and populate stages
via the $accessor_object (see below).  Class is used for hints to the
"renderer".  HTML is generated in HTML::Mason.

<p class="miffle">
What is your foo?<br />
<input type=text name="foo" value="yadda" class="miffle"><p>

When the form is sent back, a validation routine will get value "foo" from
the request, via an "input object", see if it's present and valid.

If validation fails, output ('missing'=>'foo'), or ('invalid'=>'foo')

Note that 'title' and the error message must run through I18N.  TODO.

MULTIPLE OPTION WIDGET

my $widget=JAAS::Widget::List->new(name=>'bar',
                    title=>'field.something.bar", 
                    source=>'object-name/bar',
                    validation=>['required'],
                    type=>'single',
                    items=>{.......});

Note that 'title' and 'items' must run through I18N.  TODO.

'type' is either 'single' for single-select lists (like radio buttons) or
'multi' for multiple-select lists or check boxes. Select limits are set via
the 'required' validator (see JAAS::Widget::List doco).

Attributes like CHECKED, SELECTED will be set from the data source via the
$accessor_object.

WIDGET GROUP
(aka dialog box)

JAAS::Widget::Group->new(
    JAAS::Widget::Text->new(name=>"name"....),
    JAAS::Widget::Text->new(name=>"address"....),
    JAAS::Widget::Text->new(name=>"telephone"....),
);

Shorter :

JAAS::Widget::Group->new('user',
			'name', {widget=>'Text', validation=>['required']},
			'address', {widget=>'Text'},
			'telephone', {widget=>'Text', validation=>['regex:^[-\d .]+$']});

This would be equiv to:

my $group=JAAS::Widget::Group->new(
  JAAS::Widget::Text->new(name=>"name", source=>"user/name", 
                        title=>"field.user.name", validation=>"required"),
  JAAS::Widget::Text->new(name=>"address",source=>"user/address", 
                        title=>"field.user.address"),
  JAAS::Widget::Text->new(name=>"telephone", source=>"user/address", 
                        title=>"field.user.address",
                        validation=>'regex:^[-\d .]+$'),
);

Where field.user.name is a tag that is looked up in the I18N "textbase".




POPLUATING

Each widget class or group has a method C<populate>:

    $widget->populate($accessor_object);
    $group->populate($accessor_object);

Where $something is an object that has one method:

    sub populate {
        ...
        $value=$accessor_object->get_field($field_source);
        ...
    }

Returned $value could be a scalar OR an arrayref (for multiple selections).



VALIDATION

The 'validation' field can have the following types:

'regex:....'
        Input must match the .... regex.  
'phone'
        Input must be a valid phone number + extntion:
        123-123-1234 432
        01-123-01-12345 415
        Equiv to regex:[-\d. ]+

'cc'
        Input must contain a valid CC number
        Use some credit card module to validate.
'expiry'
        Input must contain a valid CC expiry date (mm/yy)

'integer'
        Input must be a integer value 
        Equiv: regex:-?[0-9]+
'float' or something
        Input must be a floating point number
        Equiv: regex:-?[0-9]+(\.[0-9]+)
'amount'
        Input must be a floating point number with max .01 precision. 
However, when the input is captured, it is multiplied by 100 to convert to
cents so that it is stored as an integer in the source object.
'quantity'
        Positive integer, 0 or empty.

The following can be combined with other types:
'required'
       Input must contain a non-white character for Text widgets. With List
widgets, a specific number or range of selected items can be set.

'strip'
        Remove leading and trailing whitespace from the input. 
        (This could almost be default...)



Each widget class or group class has a C<validation> method, which returns
an array of errors, or empty if none.  Errors are of the form: 'type'=>'name'

    my @errs;
    push @errs, $widget->validation($input);
    push @errs, $group->validation($input);
    
    if(@errs) {
        # respond to the user with @errs
    }

Where $input is an object that has one method : 

    my $scalar = $input->param($name);      # gets the input for name
    my @array  = $input->param($name);      # gets the inputs for name

It will save the new value from $input, to be used for INTEGRATION later.



CAPTURING

To put the new value back into the application objects, each widget class or
group has a C<capture> method that takes the value saved during validation 
and sends it to the "source";

    $widget->capture($accessor_object);
    $group->capture($accessor_object);

Where $accessor_object is an object that has one method:

    $accessor_object->set_field($field_source, $new_value);

Param $new_value could be a scalar OR an arrayref (for multiple selections).


$ACCESSOR_OBJECT

Is created by JAAS::Entrypoint, that will deal with getting or setting 
data members in the appropriate application objects.  It will use the widget's
'source' member to "route" the call to the right object.


