NAME
HTML::Controls::Base - base class for the controls
SYNOPSIS
This module defines an abstract class, from which all the other controls must inherit. It defines all the basic, shared behaviour.
For an overview on how to use this framework, see HTML::Controls.
PUBLIC METHODS
new
The constructor. Takes the name of the control, which must ba a valid HTML identifier. The returned object has no valid data.
setData
This method takes a scalar value (that can be a reference), and uses it to set the control's current value. It calls "_preprocess_value" to convert the passed value before storing it in $self->{value}. Then it calls "_validate_value".
You should override this method if you need more complex manipulations.
setDataFromPost
This method takes a HTTP request object (like a CGI object, a Apache::Request object, or something similar), and uses it to set the control's current value. It uses the control's name to extract the value from the request, calls "_preprocess_value" to convert it and then stores it in $self->{value}. Then it calls "_validate_value".
You should override this method if your data gets sent as more than one field.
isDataValid
Returns a true value if "getErrors" returns undef or an empty array reference.
You should never need to override this method: override "_validate_value" instead.
getData
Returns the value stored in the control (a scalar).
You should probably override this method if you overrode "setData" or "setDataFromPost".
getErrors
Returns an array reference of errors found during the last call to "_validate_value".
You should never override this method.
getName
Returns the name of this control, as set by the constructor or "setName".
setName
Sets the name of the control. It must ba a valid HTML identifier.
You should not override this method. For a case in which it is necessary, see HTML::Controls::CompositeOf and HTML::Controls::ArrayOf.
form
Returns a string containing (X)HTML code to put inside a form element. It calls "_render".
Don't override this method: see "_body_template_name" and "_body_template_parms".
head
Returns a string containing (X)HTML code to put inside the head element. It calls "_render".
Don't override this method: see "_head_template_name" and "_head_template_parms".
templateDir
Returns the directory in which the template file for this control is stored. It is used by HTML::Controls::templateProvider.
By default it returns a directory called tmpl placed in the same directory where the source file for the module resides.
setTemplateObject
Used to set the Template object used by this control. It can be called by the application, to avoid instatiating a different Template for each control. The passed object should use the provider returned by HTML::Controls::templateProvider, in addition to any other providers that may be needed.
PROTECTED METHODS
These methods are intended to be overridable by subclasses, but not callad by applications.
_preprocess_value
Override this method to preprocess data (one scalar) coming from either "setData" or "setDataFromPost", before storing. Note that this works only if the internal and external representation are very similar or identical. If they differ, you should override one or both of the setData* methods.
By default it returns the value unchanged.
_validate_value
Override this method to check the validity of data already stored in $self->{value} or wherever you put it if you redefined "setData" or "setDataFromPost".
At the end of this method, $self->{errors} should be undef or an empty array ref if there were no errors; otherwise it sholud contain one string for each error, describing it. Localization of these messages is delegated to the templates.
You should probably call the inherited method before doing your checks. By default this method checks that the value is defined.
_render
This method takes a template name and a hash reference, and uses the object returned by "_template" to obtain the output string. It dies if the template engine encounters an error.
You should never need to override this method.
_template
Returns the template processor to use to render the (X)HTML strings. If no template object has been set (because this method has never been called, and nobody used "setTemplateObject"), it creates a new Template object using the provider returned by HTML::Controls::templateProvider, caching it.
You should never need to override this method.
_body_template_name
Returns a string containing the name of the template file to use to render the "form" for this control. It should return a filename relative to the directory returned by "templateDir".
You must override this method: by default it returns undef, causing "_render" to return undef.
_body_template_parms
Returns a hash reference that gets passed to the template engine when rendering the "form" for this control. By default it passes the name, the value (as stored>, and any errors found during validation.
You should override this method if your template requires more data (e.g. you keep part of the value outside $self->{value}). You should remember to call the inherited method, and add your data to the returned hash.
_head_template_name
Returns a string containing the name of the template file to use to render the "head" for this control. It should return a filename relative to the directory returned by "templateDir".
You should override this method if you need special CSS or JavaScript code. By default it returns undef, causing "_render" to return undef.
_head_template_parms
Returns a hash reference that gets passed to the template engine when rendering the "head" for this control. By default it passes the name, the value (as stored>, and any errors found during validation.
You should override this method if your template requires more data (e.g. you keep part of the value outside $self->{value}). You should remember to call the inherited method, and add your data to the returned hash.
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.