/ 
HTML-Controls-0.1
/ HTML::Controls::CompositeOf

NAME

HTML::Controls::CompositeOf - base abstract class for a control set

SYNOPSIS

package HTML::Controls::MyComposite;
use base 'HTML::Controls::CompositeOf';

sub new {
  my $self=$_[0]->SUPER::new($_[1]);
  # create sub-controls
  return $self;
}

sub _validate_value {
  my ($self)=@_;
  $self->{errors}=undef;
  $self->SUPER::_validate_value();
  # perform additional validations
}

package MyController;

my $comp = HTML::Controls::MyComposite->new('name',$stuff);

This is an abstract base class for sets of control, i.e. to treat multiple, disomogeneous controls as a single thing. Think "hash of controls". If you want an array of controls (variable numbered, homogeneous controls), see HTML::Controls::ArrayOf.

VALUE FORMAT

The internal representation of the composite value is a hash reference, whose keys are the "short" names of the sub-controls, and whose values are the corresponding controls' values.

METHODS TO REDEFINE

new

As seen in the synopsis, you must redefine the constructor to populate the composite. To that end, you should instantiate each sub-control, and pass it to the "_set_sub" method:

my $sub1=HTML::Controls::Something->new('tmpname');
$self->_set_sub('realname',$sub1);

Note that the name you pass to the constructor is replaced by a new, generated "long" name, based on the name you pass to _set_sub. The name that you pass to _set_sub is the "short" name used to refer to that sub-control in the value hash and template parameters.

_validate_value

If you need to perform cross-validation or something similar, you should override this method. Remember to always call the inherited method, and to add all errors you find to the $self->{errors} array. For example:

sub _validate_value {
  my ($self)=@_;
  $self->{errors}=undef;
  $self->SUPER::_validate_value();
  if ($self->_get_sub('sub1')->getData() >
      $self->_get_sub('sub2')->getData()) {
    push @{$self->{errors}}, 'sub1 must be less than sub2';
  }
}

Template methods

You must redefine _body_template_name and/or _head_template_name, otherwise no output will be generated. You can redefine _body_template_parms and/or _head_template_parms if you need to pass additional data to your templates.

REDEFINED PUBLIC METHODS

setData

This method iterates through the sub-controls, and if the sub-control's "short" name is present as a key in the passed hash reference, the corresponding value is passed to that sub-control's setData.

setDataFromPost

This method iterates through the sub-controls, calling each one's setDataFromPost with the passed request.

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 hash 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_sub" to calculate their "long" names.

setTemplateObject

This method sets the composite'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 composite's error array. See "isDataValid".

_body_template_parms

Calls the inherited method, then "_add_template_parms" to add the sub-controls.

_head_template_parms

Calls the inherited method, then "_add_template_parms" to add the sub-controls.

ADDITIONAL METHODS

_add_template_parms

This is a utility method, called by both "_body_template_parms" and "_head_template_parms". It adds to the passed hash reference all the sub-controls, using their "short" names as keys.

_name_sub

Calculates a sub-control's "long" name from its "short" name. The generated name is:

$composite_name . '_' . $short_name

_set_sub

Takes a "short" name and a control, and adds it as a new sub-control. The sub-control's name is changed to the "long" name calculated by "_name_sub".

_get_sub_names

Returns a list of all sub-controls' "short" names.

_get_sub

Given a sub-control's "short" name, returns the corresponding control, or undef in no such control exists.

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.