lib/CXGN/Page/Form.pm

   1
   2 use Module::Find;
   3 useall CXGN::Page::Form;
   4
   5 package CXGN::Page::Form;
   6
   7
   8 =head1 NAME
   9
  10 CXGN::Form.pm -- classes to deal with user-modifiable web forms
  11
  12 =head1 DESCRIPTION
  13
  14 The form classes can be used to generate forms that can be either static (non-editable) or editable and know how to save the data. They can also be used to validate form entry (see below).
  15
  16 =head2 Form generation and rendering
  17
  18 There are two form classes: CXGN::Page::Form::Static and CXGN::Page::Form::Editable. Editable inherits from static and so shared all the functions, some of which are overridden so that an editable form is generated instead of a static one.
  19
  20 All form elements are defined by classes that also occur in two versions: a static class and an editable class. For a form field, for example, the static class is CXGN::Page::Form::Field and the editable class is CXGN::Page::Form::EditableField, which inherits from the former. All field elements inherit from the abstract class CXGN::Page::Form::ElementI, which essentially defines and interface for form elements.
  21
  22 The form classes have functions to add different form elements to the form. The functions in the Static form class will call the constructor for the static field element, and the Editable form class will call the constructor for the editable field element. It is therefore easy to change a static form to an editable one by just changing the call to the form constructor.
  23
  24 There are several ways in which forms can be rendered:
  25
  26 =over 5
  27
  28 =item (1)
  29
  30 Call the function as_table() on the form object. This will generate a simple table with field names and field values in the order they were added to the form object.
  31
  32 =item (2)
  33
  34 The function get_field_hash() on the form object will return a hash with the field names as hash keys and the representation of the field as the value. In the case of an editable field, the value will be html for input boxes, for example. In the case of a static form, it will usually just be a text representation of the contents of the field.
  35
  36 =back
  37
  38 =head2 Form validation
  39
  40 When creating a form element, a "validate" parameter can be supplied, such as:
  41
  42     $form->add_field(
  43                      display_name=>"Name: ",
  44                      field_name=>"name",
  45                      length=>20,
  46                      object=>$myobject,
  47                      getter=>"get_name", setter=>"set_name",
  48                      validate=>"string"
  49                     );
  50
  51 This will make sure that a string type has been entered and will $form->validate() will return the field name as a hash key with an appropriate hash value if there is no input. Other input types are "integer", "number" (any number, including floats etc), and "token", which is a string without spaces or special characters.
  52
  53 Field lengths are not yet enforced but will be in the future. The error codes that are returned from the validate function are defined as globals in CXGN::Insitu::ElementI.
  54
  55 Note that the function as_table() handles error conditions gracefully. It will print an error message next to the field when an error occurs.
  56
  57 =head1 EXAMPLES
  58
  59 A simple form with an entry field for first and last name could be created as follows:
  60
  61
  62     if ($show_editable) {
  63        $form = CXGN::Page::Form::Editable->new();
  64     }
  65     else {
  66        $form=CXGN::Page::Form::Static->new();
  67     }
  68     $form->add_field(  display_name=>"First name:", field_name=>"first_name",
  69                        contents=>"Joe", length=>20, $object=>$person,
  70                        getter=>"get_first_name", $setter=>"set_first_name" );
  71
  72     $form->add_field(  display_name=>"Last name:", field_name=>"last_name",
  73                        contents=>"Sixpack", length=>20, $object=>$person,
  74                        getter=>"get_last_name", $setter=>"set_last_name" );
  75
  76     $page->header();
  77
  78     $form->as_table();
  79
  80     $page->footer();
  81
  82 To store the request from the form above, one could do the following:
  83
  84 %args = the apache get/post parameters as a hash
  85
  86 if ($action eq "store") {
  87     $form->store(%args)
  88 }
  89
  90 =head1 DB OBJECTS PROPERTIES
  91
  92 There are special requirements for the DB objects for some of the above functionality to work. Each DB object has to be represented by a Perl object (although it can map to several tables), and needs accessors for all the properties that can be specified in the add_field call. The DB function needs to implement a function called store() to store the object to the backstore.
  93
  94 An alternate way to represent the html would be to use the get_field_hash() function:
  95
  96    my %fields = $form->get_field_hash();
  97
  98    print $fields{FORM_START};
  99    print "Name: ".$fields{last_name}."<br />\n";
 100    print "First: ".$fields{first_name}."<br />\n";
 101    print $fields{FORM_END};
 102
 103
 104 =head1 MORE INFORMATION, SEE ALSO
 105
 106 For more information, see CXGN::Page::Form::Static and CXGN::Page::Form::Editable
 107 For field definitions see the CXGN::Page::Form::ElementI interface.
 108 Note that L<CXGN::Page::Form::SimpleFormPage> provides a framework for working with simple updatable forms. It knows how to handle input validation, editing, viewing, adding, and deleting database entries with the appropriate user access privilege checking. See L<CXGN::Page::Form::SimpleFormPage> for more information.
 109
 110 =head1 AUTHOR(S)
 111
 112 Lukas Mueller (lam87@cornell.edu)
 113
 114 =cut
 115
 116
 117 return 1;