NAME
HTML::Controls::ArrayOf - base abstract class for a control array
SYNOPSIS
package HTML::Controls::MyArray;
use base 'HTML::Controls::ArrayOf';
sub new {
my $self=$_[0]->SUPER::new($_[1]);
# do some initialization
$self->_populate($_[2]);
return $self;
}
sub _create_item {
return HTML::Controls::Something->new($_[1],$stuff);
}
package MyController;
my $arr = HTML::Controls::MyArray->new('name',$howMany);This is an abstract base class for arrays of control, i.e. to treat a variable number of homogeneous controls as a single thing. Think "array of controls". If you want a hash of controls (fixed number, disomogeneous controls), see HTML::Controls::CompositeOf.
VALUE FORMAT
The internal representation of the array value is an array reference, containings the sub-controls' values.
METHODS TO REDEFINE
_create_item
You must redefine this method to return a new sub-control. The name you give it is irrelevant, since it will be overwritten by one calculated by "_name_item".
REDEFINED PUBLIC METHODS
new
The constructor takes the array's name and a specification for the sub-controls. It calls "_populate" with this specification to create them.
setData
This method takes an array reference as specified in "VALUE FORMAT". All exisisting sub-controls are deleted, and new one are created (calling "_create_item") and assigned the passed data. Note that, because of this, a call to setData can change the size of the array.
setDataFromPost
This is the method where most of the complexity resides: it sets each sub-control to the value extracted from the passed request, removing and adding sub-controls if required.
It assumes that a request parameter of the form "${arrayname}_del_\d+" requests the removal of the sub-control at the position indicated by the number, and that a parameter of the form "${arrayname}_add_\d+" requests a new sub-control to be added after the position indicated.
At the end, oll sub-controls get renamed, to insure the proper ordering and the correspondance between positions and sub-controls' names.
Calls "_validate_value" after removing sub-controls and setting values, but before adding new sub-controls. Tis is because, usually, newly created controls have no valid value.
isDataValid
This method returns false if $self->getErrors() or any sub-control's getErrors() returns a non-empty array reference.
getData
This method iterates through the sub-controls, populating the return array with the values obtained from each one's getData.
setName
This method sets the composite's name, and propagates the change to each sub-control, using "_name_item" to calculate their new names.
setTemplateObject
This method sets the array's template engine, and propagates the change to each sub-control.
REDEFINED PROTECTED METHODS
_validate_value
This method iterates through the sub-controls, calling each one's _validate_value. Note that this deos not populate the array's error array. See "isDataValid".
_body_template_name
Returns 'array_of.wt'. This template outputs a ordered list with one sub-control per item, and provides buttons to add and remove controls. If you wish to provide your own template, remember to include this one, or provide equivalent functionality.
_body_template_parms
Calls the inherited method, then sets the value of the item key to the array of sub-controls.
ADDITIONAL METHODS
_populate
This method takes either a number (indicating how many sub-controls to create) or an arry reference (containing initial data for the sub-controls), and populates the sub-controls' array.
_name_item
Calculates a sub-control's name from its position. The generated name is:
$array_name . '_' . ($position+1)_add_item
Adds the given sub-control to the end of the sub-controls' array.
_get_items
Returns the whole sub-controls' array.
_clear_items
Deletes all the sub-controls.
_insert_item
Given a position and a control, inserts it after that position.
_delete_item
Deletes the sub-control at the given position.
COPYRIGHT
Copyright 2005 Gianni Ceccarelli, All Rights Reserved.
This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.