Changes

Jump to navigation Jump to search
1,178 bytes removed ,  23:56, 19 December 2013
no edit summary
Line 146: Line 146:     
=== PAGES ===
 
=== PAGES ===
      Page sub-elements
+
==== Page sub-elements ====
 +
A page may contain the following sub-elements:
   −
      A page may contain the following sub-elements:
+
* description
   −
      ·  description
+
* field
   −
      ·  field
+
==== Page attributes ====
   −
      Page attributes
+
The following attributes are supported for pages:
 +
* name (required)
   −
      The following attributes are supported for pages:
+
* pre-event=<func>
   −
      ·  name (required)
+
* post-event=<func>
   −
      ·  pre-event=<func>
+
* menu=<func>
   −
      ·  post-event=<func>
+
Example
 
  −
      ·  menu=<func>
  −
 
  −
      Example
      
           <page
 
           <page
Line 181: Line 179:     
=== FIELDS ===
 
=== FIELDS ===
      Fields are the most important part of the form definition.  Several
+
Fields are the most important part of the form definition.  Several types of HTML fields are supported, and each one has various attributes associated with it.
      types of HTML fields are supported, and each one has various attributes
  −
      associated with it.
     −
      Field types
+
==== Field types ====
   −
      You can specify the type of HTML field to be generated using the type
+
You can specify the type of HTML field to be generated using the type attribute:
      attribute:
      
           <field type="...">
 
           <field type="...">
   −
      The following field types are supported:
+
The following field types are supported:
 
+
==== text ====
      text
+
A plain text field.  You may optionally use the size attribute to modify the size of the field displayed.  To restrict the length of data entered by the user, use the maxlength() validation routine.
          A plain text field.  You may optionally use the size attribute to
+
==== select ====
          modify the size of the field displayed.  To restrict the length of
+
A dropdown list.  You must provide the options attribute to specify the contents of the list (see below for the format of this attribute).  If you set the multiple attribute to 1, multiple selections will be enabled.  The optional size attribute sets the number of items displayed at once.
          data entered by the user, use the maxlength() validation routine.
  −
 
  −
      select
  −
          A dropdown list.  You must provide the options attribute to specify
  −
          the contents of the list (see below for the format of this
  −
          attribute).  If you set the multiple attribute to 1, multiple
  −
          selections will be enabled.  The optional size attribute sets the
  −
          number of items displayed at once.
  −
 
  −
      radio
  −
          Radio buttons allow users to choose one item from a group.  This
  −
          field type requires the options attribute (as for select, above).
  −
 
  −
      checkbox
  −
          This field type provides a simple check box for yes/no questions.
  −
          The checked attribute is optional, but if set to 1 will make the
  −
          checkbox checked by default.
  −
 
  −
      password
  −
          The password field type is like a text field, but obscures the data
  −
          typed in by the user.
     −
      file
+
==== radio ====
          This field type allows the upload of a file by the user.
+
Radio buttons allow users to choose one item from a group.  This field type requires the options attribute (as for select, above).
   −
      textarea
+
==== checkbox ====
          A multi-line text field allowing the input of blocks of text.
+
This field type provides a simple check box for yes/no questions. The checked attribute is optional, but if set to 1 will make the checkbox checked by default.
          Defaults to 5 rows and 60 columns, but you can specify "rows" and
  −
          "cols" arguments to change that.
     −
      literal
+
==== password ====
          A field that is just printed literally.  Useful if you want to just
+
The password field type is like a text field, but obscures the data typed in by the user.
          print out a non-editable bit of text in the same sort of layout as
  −
          the other fields in the form.
     −
      You may specify a subroutine to generate the field type. This is par-
+
==== file ====
      ticularly useful in "create or modify" type forms where one or more
+
This field type allows the upload of a file by the user.
      fields will be input fields when creating or literals when modifying.
+
==== textarea ====
      The subroutine can return any of the above type as a string.
+
A multi-line text field allowing the input of blocks of text. Defaults to 5 rows and 60 columns, but you can specify "rows" and "cols" arguments to change that.
 +
==== literal ====
 +
A field that is just printed literally. Useful if you want to just print out a non-editable bit of text in the same sort of layout as the other fields in the form.
   −
      Field sub-elements
+
You may specify a subroutine to generate the field type. This is particularly useful in "create or modify" type forms where one or more fields will be input fields when creating or literals when modifying.The subroutine can return any of the above type as a string.
   −
      The following elements may be nested within a field:
+
==== Field sub-elements ====
   −
      ·  label (a short description; required)
+
The following elements may be nested within a field:
   −
      ·  description (a more verbose description; optional)
+
* label (a short description; required)
   −
      Other field attributes
+
* description (a more verbose description; optional)
   −
      Fields must ALWAYS have a type (described in the previous section) and
+
==== Other field attributes ====
      an id attribute, which is a unique name for the field.  Each type of
  −
      field may have additional required attributes, and may support other
  −
      optional attributes.
     −
      Here is a list of optional attributes for fields:
+
Fields must ALWAYS have a type (described in the previous section) and an id attribute, which is a unique name for the field.  Each type of field may have additional required attributes, and may support other optional attributes.
   −
      value
+
Here is a list of optional attributes for fields:
          A default value to fill in; see below for more information on the
  −
          format of this field.
     −
      validation
+
==== value ====
          a list of validation functions; see CGI::FormMagick::Validator for
+
A default value to fill in; see below for more information on the format of this field.
          more information on this subject.
     −
      options
+
==== validation ====
          A list of options required for a select list or radio buttons; see
+
a list of validation functions; see CGI::FormMagick::Validator for more information on this subject.
          below for more information on the format of this attribute.
     −
      checked
+
==== options ====
          For checkbox fields, used to make the box checked by default.
+
A list of options required for a select list or radio buttons; see below for more information on the format of this attribute.
          Defaults to 0.
+
==== checked ====
 +
For checkbox fields, used to make the box checked by default. Defaults to 0.
   −
      multiple
+
==== multiple ====
          For select fields, used to allow the user to select more than one
+
For select fields, used to allow the user to select more than one value.
          value.
     −
      size
+
==== size ====
          For select fields, height; for text and textarea fields, length.
+
For select fields, height; for text and textarea fields, length.
   −
      display
+
==== display ====
          This attribute is a callback to a function that returns true or
+
This attribute is a callback to a function that returns true or false. If true, the field is displayed, and validated during form submission. If false, it is not.
          false. If true, the field is displayed, and validated during form
  −
          submission. If false, it is not.
     −
      Notes on parsing of value attribute
+
Notes on parsing of value attribute
   −
      If your value attribute ends in parens, it’ll be taken as a subroutine
+
If your value attribute ends in parens, it’ll be taken as a subroutine to run.  Otherwise, it’ll just be taken as a literal.
      to run.  Otherwise, it’ll just be taken as a literal.
     −
      This will be literal:
+
This will be literal:
    
           value="username"
 
           value="username"
   −
      This will run a subroutine:
+
This will run a subroutine:
    
           value="get_username()"
 
           value="get_username()"
   −
      The subroutine will be passed the CGI object as an argument, so you can
+
The subroutine will be passed the CGI object as an argument, so you can use the CGI params to help you generate the value you need.
      use the CGI params to help you generate the value you need.
+
Your subroutine should return a string containing the value you want.
 
+
Notes on parsing of options attribute
      Your subroutine should return a string containing the value you want.
+
The options attribute has automagical Do What I Mean (DWIM) abilities. You can give it a value which looks like a Perl list, a Perl hash, or a subroutine name.  For instance:
 
  −
      Notes on parsing of options attribute
  −
 
  −
      The options attribute has automagical Do What I Mean (DWIM) abilities.
  −
      You can give it a value which looks like a Perl list, a Perl hash, or a
  −
      subroutine name.  For instance:
      
           options="’red’, ’green’, ’blue’"
 
           options="’red’, ’green’, ’blue’"
Line 312: Line 268:  
           options="get_colors()"
 
           options="get_colors()"
   −
      How it works is that FormMagick looks for the => operator, and if it
+
How it works is that FormMagick looks for the => operator, and if it finds it it evals the options string and assigns the result to a hash. If it finds a comma (but no little => arrows) it figures it’s a list, and evals it and assigns the results to an array.  Otherwise, it tries to interpret what’s there as the name of a subroutine in the scope of the script that called FormMagick, expecting to get back a value which is either an arrayref or a hashref, which it will deal with appropriately in either case.
      finds it it evals the options string and assigns the result to a hash.
  −
      If it finds a comma (but no little => arrows) it figures it’s a list,
  −
      and evals it and assigns the results to an array.  Otherwise, it tries
  −
      to interpret what’s there as the name of a subroutine in the scope of
  −
      the script that called FormMagick, expecting to get back a value which
  −
      is either an arrayref or a hashref, which it will deal with appropri-
  −
      ately in either case.
     −
      A few gotchas to look out for:
+
A few gotchas to look out for:
   −
      ·  Make sure you quote strings in lists and hashes.  "red,blue,green"
+
* Make sure you quote strings in lists and hashes.  "red,blue,green" will fail (silently) because of the barewords.
          will fail (silently) because of the barewords.
     −
      ·  Single-element lists ("red") will fail because the DWIM parsing
+
* Single-element lists ("red") will fail because the DWIM parsing doesn’t find a comma there and treats it as the name of a subroutine.  But then, a single-element radio button group or select dropdown is pretty meaningless anyway, so why would you do that?
          doesn’t find a comma there and treats it as the name of a subrou-
  −
          tine.  But then, a single-element radio button group or select
  −
          dropdown is pretty meaningless anyway, so why would you do that?
     −
      ·  Arrays will result in options being sorted in the same order they
+
* Arrays will result in options being sorted in the same order they were listed.  Hashes will be sorted by value using the Perl’s cmp() function (ASCIIbetical sort, in other words).
          were listed.  Hashes will be sorted by value using the Perl’s cmp()
  −
          function (ASCIIbetical sort, in other words).
     −
      ·  An anti-gotcha: subroutine names do not require the parens on them.
+
* An anti-gotcha: subroutine names do not require the parens on them. "get_colors" and "get_colors()" will work the same.
          "get_colors" and "get_colors()" will work the same.
      
=== INTERNAL, DEVELOPER-ONLY ROUTINES ===
 
=== INTERNAL, DEVELOPER-ONLY ROUTINES ===
      The following routines are used internally by FormMagick and are docu-
+
The following routines are used internally by FormMagick and are documented here as a developers’ reference.  If you are using FormMagick to develop web applications, you can skip this section entirely.
      mented here as a developers’ reference.  If you are using FormMagick to
  −
      develop web applications, you can skip this section entirely.
  −
 
  −
      magic_wherenext
     −
      We allow FM users to set the "wherenext" param explicitly in their
+
==== magic_wherenext ====
      code, to do branching of program logic.  This routine checks to see if
  −
      they have a magic "wherenext" param and returns it.  Gives undef if
  −
      it’s not set.
     −
      nopost
+
We allow FM users to set the "wherenext" param explicitly in their code, to do branching of program logic.  This routine checks to see if they have a magic "wherenext" param and returns it.  Gives undef if it’s not set.
   −
      Often, you want to provide the ability to navigate to a new page with-
+
==== nopost ====
      out validating the last page. When that is the case, you should set the
  −
      ’nopost’ CGI param, which is checked with this method, and then deleted
  −
      to prevent is being remembered for the next submission.
     −
      prepare_for_next_page
+
Often, you want to provide the ability to navigate to a new page with out validating the last page. When that is the case, you should set the ’nopost’ CGI param, which is checked with this method, and then deleted to prevent is being remembered for the next submission.
   −
      This does all the things needed before going on to the next page.
+
==== prepare_for_next_page ====
      Specifically, it validates the data from this page, and then if valida-
  −
      tion was successful it puts the current page onto the page stack and
  −
      then sets page_number to whatever page we should be visiting next.
     −
      $fm->cleanup_checkboxes()
+
This does all the things needed before going on to the next page. Specifically, it validates the data from this page, and then if validation was successful it puts the current page onto the page stack and then sets page_number to whatever page we should be visiting next.
   −
      Checkbox params only get passed around if they’re checked.  An
+
==== $fm->cleanup_checkboxes() ====
      unchecked box doesn’t send "checkbox=0" ... no, it just completely
  −
      fails to send anything at all.  This is a PITA, as it’s impossible to
  −
      distinguish an explicity unchecked box from one that never got seen at
  −
      all.
     −
      This subroutine is intended to clean up the mess, by checking the
+
Checkbox params only get passed around if they’re checked.  An unchecked box doesn’t send "checkbox=0" ... no, it just completely fails to send anything at all.  This is a PITA, as it’s impossible to distinguish an explicity unchecked box from one that never got seen at all.
      checkboxes that were expected on the current page against what it actu-
+
This subroutine is intended to clean up the mess, by checking the checkboxes that were expected on the current page against what it actually saw on the CGI parameters, and explicitly setting any missing ones to 0.
      ally saw on the CGI parameters, and explicitly setting any missing ones
+
==== $fm->commit_session() ====
      to 0.
+
Commits a session’s details to disk, in the same way as CGI::Persistent.  Needed by cleanup_checkboxes().
   −
      $fm->commit_session()
+
==== get_option_labels_and_values ($fieldinfo) ====
   −
      Commits a session’s details to disk, in the same way as CGI::Persis-
+
returns labels and values for fields that require them, by running a subroutine or whatever else is needed.  Returns a hashref containing:
      tent.  Needed by cleanup_checkboxes().
  −
 
  −
      get_option_labels_and_values ($fieldinfo)
  −
 
  −
      returns labels and values for fields that require them, by running a
  −
      subroutine or whatever else is needed.  Returns a hashref containing:
      
           { labels => \@options_labels, $vals => \@option_values }
 
           { labels => \@options_labels, $vals => \@option_values }
   −
      parse_options_attribute($options_field)
+
==== parse_options_attribute($options_field) ====
   −
      parses the options attibute from a field element and returns a refer-
+
parses the options attibute from a field element and returns a reference to either a hash or an array containing the relevant data to fill in a select box or a radio group.
      ence to either a hash or an array containing the relevant data to fill
  −
      in a select box or a radio group.
     −
      do_external_routine($self, $routine, @optional_args)
+
==== do_external_routine($self, $routine, @optional_args) ====
 +
Runs an external routine, for whatever purpose (filling in default values of fields, validation, etc).  If anything is in @optional_args, the routine is called using those.  If @optional_args is ommitted, then $self->{cgi} is passed.  Returns the return value of the routine, or undef on failure.  Also emits a warning (to your webserver’s error log, most likely) if it can’t run the routine.
   −
      Runs an external routine, for whatever purpose (filling in default val-
+
The routine is always called in the package which called FormMagick (usually main::, but possibly something else).
      ues of fields, validation, etc).  If anything is in @optional_args, the
  −
      routine is called using those.  If @optional_args is ommitted, then
  −
      $self->{cgi} is passed.  Returns the return value of the routine, or
  −
      undef on failure.  Also emits a warning (to your webserver’s error log,
  −
      most likely) if it can’t run the routine.
     −
      The routine is always called in the package which called FormMagick
+
The CGI object is passed to your routine, so you can do stuff like $cgi->param("foo") to it to find out CGI parameters and so on.
      (usually main::, but possibly something else).
  −
 
  −
      The CGI object is passed to your routine, so you can do stuff like
  −
      $cgi->param("foo") to it to find out CGI parameters and so on.
      
=== SEE ALSO ===
 
=== SEE ALSO ===
Line 424: Line 333:     
=== BUGS ===
 
=== BUGS ===
      The validation attribute must be very carefully formatted, with spaces
+
The validation attribute must be very carefully formatted, with spaces between the names of routines but not between the arguments to a routine.  See description above.
      between the names of routines but not between the arguments to a rou-
  −
      tine.  See description above.
      
=== AUTHOR ===
 
=== AUTHOR ===
      Kirrily "Skud" Robert <skud@infotrope.net>
+
Kirrily "Skud" Robert <skud@infotrope.net>
 
  −
      Contributors:
     −
      Shane R. Landrum <slandrum@turing.csc.smith.edu>
+
Contributors:
   −
      James Ramirez <jamesr@cogs.susx.ac.uk>
+
Shane R. Landrum <slandrum@turing.csc.smith.edu>
 +
James Ramirez <jamesr@cogs.susx.ac.uk>
   −
      More information about FormMagick may be found at http://source-
+
More information about FormMagick may be found at http://sourceforge.net/projects/formmagick/
      forge.net/projects/formmagick/
   
[[Category:Howto]]
 
[[Category:Howto]]
 
[[Category:SME Server Development Framework]]
 
[[Category:SME Server Development Framework]]
 
[[Category:Development Tools]]
 
[[Category:Development Tools]]
 
[[Category:SME9-Development]]
 
[[Category:SME9-Development]]

Navigation menu