NAME

Contentment::Form::Definition - Persistent form definitions

DESCRIPTION

This class provides persisent storage of forms.

METHODS

Instances of this class should not be constructed directly. Instead, use the define() method of Contentment::Form to return instances of this object.

These instances then provide the following methods:

$array = $form->widgets

This returns the widgets as an array reference. Iterate over this array if you need to iterate over all the widgets int he proper order. For example, if you want to use the default template for each widget type:

  for my $widget (@{ $form->widgets }) {
      print $form->render_widget($widget);
  }

$hash = $form->widgets_by_name

This returns a hash containing the constructed widgets. The keys are the mnemonic names passed to the "widgets" options of the define() method of Contentment::Form.

This may be used during rendering to fetch each widget and call the widget's render() method or begin()/end() methods.

This method may also be used to modify the widget's settings after construction. This is useful when it a widget option may need to be set without making that setting a part of the persistent definition.

For example, if you have a select box with a list of options that is determined from the contents of a database table that changes frequently or which vary depending on the user accessing the form. You might not want to create a new revision to the form definition every single time the options change (or you may not want to make the definition store them at all).

However, you must be careful in these situations that the form doesn't break during validation because the value set here is lost when a new request is created. In general, it's best if widgets take more responsibility for handling these kinds of situations.

$widget = $form->widget($name)

This is a shortcut for:

  my $widget = $form->widgets_by_name->{$name}

$form->render(\%defaults, \%vars)

This method renders the template that was defined in the form definition or renders according to the default template if none was given. You can specify initial default values for the form using the %defaults hash. These have the same form as the results hash that should be generated during form valiation.

The second hash, %vars, is used to pass in variables that should also be passed to the template.

RENDER METHODS

These methods should only be used within the render template.

$form->begin

This renders the start tag for the form.

$form->end

This renders the end tag for the form.

$text = $form->render_widget($name)

$text = $form->render_widget($widget)

This method renders the widget, $widget, or the widget named $name according to the themes template for the widget. Prior to rendering the widget template, the theme master named "form/Pre-Widget" will be rendered. After rendering the widget template, the theme master named "form/Post-Widget" will be rendered.

The theme master chosen for the widget will be "form/Name" where "Name" is the short name of the widget class if the class has the namespace prefix "Contentment::Form::Widget::". Otherwise, it will be the full name of the widget class with each of the colons changed to underscores. Thus, "Contentment::Form::Widget::Text" uses the template "form/Text" while "My::Widget::Foo" would use the template "form/My__Widget__Foo".

AUTHOR

Andrew Sterling Hanenkamp, <hanenkamp@cpan.org>

LICENSE AND COPYRIGHT

Copyright 2005 Andrew Sterling Hanenkamp <hanenkamp@cpan.org>. All Rights Reserved.

This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself. See perlartistic.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.