Class FormContent

Description

This class is used to build and render the form.

It builds a form by creating FormElement objects which have automatic validation. It leaves the layout of the form up to the child class. It has a mechanism in place to automagically show a confirmation 'page' after the data has been submitted and validated. It also provides a hook for any 'back end' validation of data. Finally, it provides a function for handling the action of the form, which only gets call after ALL validation has passed.

Functions:

form_init_elements() - This function is used to build the FormElement objects that will be used by the form. This function is called EVERY time the FormContent class is instantiated. After you create the FormElement, you call the FormContent::add_element() method, to add the FormElement object to the form. You will then call the 2 methods FormContent::element_label() and FormContent::element_form() to get access to the FormElement's label and form field respectively.

form_init_data() - This is called only the first time the form is encountered. It Allows you to populate the FormElements with data from a DB for example. You would use FormContent::set_element_value() or FormContent::set_hidden_element_value() inside here.

form() - This is the method that gets called to build the layout for your form. Typically you use a table and add the label in the first <td> and the form field itself in the 2nd <td>. So there are 2 methods in the FormContent object that allow u to get access to the FormElements label, and form field. FormContent::element_label() and FormContent::element_form().

form_backend_validation() - This method enables you to do any "back end" validation of data. Such as, check for a duplicate in the DB on a create/new form. This is called after the FormElement's validation methods have passed.

form_action() - This method is called after ALL validation was successfull, including each FormElement object's validation methods, as well as the FormContent::form_backend_validation()

Located in Program_Root/form/FormContent.inc (line 77)


	
			
Direct descendents
Class Description
AccountForm This is the Class that handles the building of the Form itself. It creates the Form Elements inside the form_init_elements() method.
StandardFormContent This is a child of the FormContent class to provide a 'standard' look and feel for forms.
Variable Summary
Method Summary
void FormContent ([mixed $width = "100%"], [mixed $cancel_action = NULL])
INPUTtag add_action (string $label, [bool $disabled = false], [string $submit_function = false], [boolean $disable_on_submit = TRUE])
form add_cancel (string 0)
void add_element (FormElement &$element)
void add_error (string $label, string $message)
ContainerWidget add_hidden_action (string $label, string $action, [boolean $disable_on_submit = TRUE])
void add_hidden_element (FormElement $label, [mixed $value = NULL])
Atag add_image_action (string $image_name, string $action, [boolean $disable_on_submit = TRUE])
void build_confirm_table (InfoTable &$table)
Object element_form (string $label)
Object element_label (string $label)
boolean form_action (array 0)
mixed form_confirm ([string $title = "Form Confirmation"], [boolean $show_buttons = TRUE])
void form_init_data ()
mixed form_success ()
string get_action ()
string get_default_css ()
Object &get_element (string $label)
value get_element_value (string $label)
array get_error_array ()
value get_hidden_element_value (string $label)
boolean has_confirm ()
Object hidden_element_label (string $label)
string javascript ()
TRUE pre_confirm ()
void set_action (string $action)
void set_action_message (string $message)
void set_cancel_action (string $action)
void set_confirm ([boolean $flag = TRUE])
void set_default_css (string $css)
void set_element_value (string $label, value $value)
void set_error_css (string $css)
void set_form_errors_title (string $title)
void set_form_errors_width (string $width)
void set_form_name (mixed $name)
void set_form_width (string $width)
void set_hidden_element_value (string $label, value $value)
void set_required_marker (string $marker)
void set_required_text (string $text)
void set_stripslashes ([boolean $flag = TRUE])
void _test_element (string $label, string $method, [boolean $hidden = FALSE])
Variables
mixed $_action_counter = 0 (line 177)

This holds how many actions we have

for this form content

mixed $_action_message = "" (line 150)

The message that is set

during the form_action

mixed $_cancel_action = NULL (line 157)

The action to take opon clicking

the "Cancel" button

mixed $_default_label_css = "formlabel" (line 106)

This holds the default css class for form field label text.

mixed $_elements = array() (line 97)

This holds the array of

non-hidden elements

mixed $_error_label_css = "formlabelerror" (line 113)

This is the css class used

for fields that have an error

mixed $_form_errors_title = "Form Errors" (line 143)

The form errors table title

mixed $_form_errors_width = null (line 137)

Holds the width (if any) of the errors table that will be rendered. If the value is null, the $this->_width value is used instead.

mixed $_form_name (line 83)

This holds the name of the form

for js that needs it

mixed $_has_confirm = FALSE (line 120)

flag to let the FormProcessor

object know this form has a confirmation page that is required

mixed $_hidden_elements = array() (line 91)

This holds the array of

hidden form elements used in this form

mixed $_required_field_marker = "*" (line 171)

marker for the required field

mixed $_required_field_text = " - required field" (line 165)

Text to show denoted required fields for the form.

mixed $_stripslashes = FALSE (line 183)

Automatically strip slashes from

form values?

mixed $_width = "600" (line 129)

Holds the width to be used for the

error table DEFAULT: 95%

Methods
Constructor FormContent (line 187)
void FormContent ([mixed $width = "100%"], [mixed $cancel_action = NULL])
add_action (line 792)

This function adds a form submit button with the appropriate action.

  • return:

    object

INPUTtag add_action (string $label, [bool $disabled = false], [string $submit_function = false], [boolean $disable_on_submit = TRUE])
  • string $label:

    - the labe/action for the submit button.

  • bool $disabled:

    disable the button

  • string $submit_function:

    - the onSubmit function (if any)

  • boolean $disable_on_submit:

    - disable opon submit?

add_cancel (line 915)

build a cancel button with a url to go to

  • return:

    button

form add_cancel (string 0)
  • string 0:

    - the cancel action

add_element (line 461)

This method is used to add a form element

void add_element (FormElement &$element)
add_error (line 589)

This method is used to create a new error element during the call to form_action(). This enables us to do error handling during a transaction into a DB.

void add_error (string $label, string $message)
  • string $label:

    - the label

  • string $message:

    - the error message

add_hidden_action (line 844)

This function adds a submit button that can have any label. It just makes the _form_action a hidden field.

NOTE: you can only do this ONCE per form.

  • return:

    object

ContainerWidget add_hidden_action (string $label, string $action, [boolean $disable_on_submit = TRUE])
  • string $label:

    - the label of the button.

  • string $action:

    - the action value.

  • boolean $disable_on_submit:

    - disable opon submit?

add_hidden_element (line 474)

This method is used to add a hidden form field

void add_hidden_element (FormElement $label, [mixed $value = NULL])
add_image_action (line 881)

This function adds an action as an image to submit the form.

  • return:

    object

Atag add_image_action (string $image_name, string $action, [boolean $disable_on_submit = TRUE])
  • string $image_name:

    - the image name path

  • string $action:

    - the action

  • boolean $disable_on_submit:

    - disable opon submit?

build_confirm_table (line 310)

This method allows the child to ovveride the default confirm data. By default the form_confirm() will show ALL FormElements. This is prolly not good in case of a form where a password exists.

void build_confirm_table (InfoTable &$table)
element_form (line 512)

This method returns the actual form object that renders the form field.

Such as an INPUTtag object.

Object element_form (string $label)
  • string $label:

    - the element's label

element_label (line 487)

This method returns the label object for a visible form element.

Object element_label (string $label)
  • string $label:

    - the element's label

form (line 231)

This method builds the html form.

It is up to the child class to define the layout of the form and return it in a phpHtmllib container.

Container form ()

Redefined in descendants as:
  • AccountForm::form() : This is the method that builds the layout of where the FormElements will live. You can lay it out any way you like.
  • StandardFormContent::form() : this builds the main wrapper for the form fields and ads the Save and Cancel buttons
form_action (line 378)

This method handles the

action (submit button) that was submitted. This method only gets called AFTER all data has been validated. This includes the backend validation. If the form has the confirmation on, then this method will be called after the confirmation has been accepted.

NOTE : return TRUE if the action was succesfully handled. If FALSE is returned, the form will be displayed again with the error message.

  • return:

    TRUE = success FALSE = failed.

boolean form_action (array 0)
  • array 0:

    - array of errors if any


Redefined in descendants as:
form_backend_validation (line 350)

This method is called after the FormElements

have all been validated, and the form_confirm has been confirmed. It enables the form to validate any data against a DB or other backend processing. This will always get called before the form_action method is called to ensure that all form data is valid before form_action() is called.

  • return:

    TRUE if successfull FALSE if errors were detected.

boolean form_backend_validation ()

Redefined in descendants as:
  • AccountForm::form_backend_validation() : This method gets called after the FormElement data has passed the validation. This enables you to validate the data against some backend mechanism, say a DB.
  • Step1::form_backend_validation() : This method gets called after the FormElement data has passed the validation, and has been confirmed. This enables you to validate the data against some backend mechanism, say a DB.
  • StandardAccountForm::form_backend_validation() : This method gets called after the FormElement data has passed the validation, and has been confirmed. This enables you to validate the data against some backend mechanism, say a DB.
form_confirm (line 279)

This function is used to show an intermediary confirmation page. Use this function to show a confirmation of the data that was submitted by the user.

This will get called after all of the form data was successfully validated. All of the form data will automatically be created as hidden form fields. All you have to do is show the data, and a confirm submit button.

  • return:

    - either raw html, or some container HTMLTag object.

mixed form_confirm ([string $title = "Form Confirmation"], [boolean $show_buttons = TRUE])
  • string $title:

    - the title for the table

  • boolean $show_buttons:

    - show the action buttons?


Redefined in descendants as:
  • StandardFormContent::form_confirm() : This function is used to show an intermediary confirmation page. Use this function to show a confirmation of the data that was submitted by the user.
form_errors (line 405)

This function is used to render the error table for the form. The error data comes from the FormProcessor or the FormValidation.

NOTE: You can override this method to show a customized error message(s)

  • return:

    object.

TABLEtag form_errors ()
form_init_data (line 218)

This method is called by the

Form Processor to allow this class to do any fetching of data to prepopulate the form field values. You typically use this to read data from a DB.

This method is only called once when the form is first hit.

NOTE: you should build the data and save it in $this->_init_data

void form_init_data ()

Redefined in descendants as:
form_init_elements (line 198)

This method is what is called to build the list of FormElements that will be used by this form.

void form_init_elements ()

Redefined in descendants as:
form_success (line 392)

This method is called when the form_action() was successfull, and the form wants to render some kind of message

mixed form_success ()
get_action (line 622)

Get the current status of the action.

string get_action ()
get_default_css (line 697)

This function returns the default css class used for NON error text.

  • return:

    - the current default css

string get_default_css ()
get_element (line 524)

This method returns the FormElement based on the label.

Object &get_element (string $label)
  • string $label:

    - the element's label

get_element_value (line 550)

This method is used to get the value for a non hidden element

  • return:

    - the new value

value get_element_value (string $label)
  • string $label:

    - the form label

get_error_array (line 436)

This method returns an array of errors for all the errors.

array get_error_array ()
get_form_errors_width (line 644)

This method returns the width of the form errors table.

By default it is supposed to be the same width as the form itself.

int get_form_errors_width ()
get_hidden_element_value (line 574)

This method is used to get the value for a hidden element

  • return:

    - the new value

value get_hidden_element_value (string $label)
  • string $label:

    - the form label

get_required_fields_text (line 932)

This returns the required field text

if there are any. otherwise it returns NULL

void get_required_fields_text ()
has_confirm (line 737)

This gets the value of the confirmation flag.

which tells the caller that this object has/doesn't have a required confirmation page.

boolean has_confirm ()
hidden_element_label (line 499)

This method returns the label object for a visible form element.

Object hidden_element_label (string $label)
  • string $label:

    - the element's label

javascript (line 244)

This method lets you provide any javascript that is associated with the form content.

The FormProcessor will automatically call this and wrap it in a script tag.

  • return:

    - raw js.

string javascript ()
pre_confirm (line 256)

This method allows this class to do any data munging prior to the form_confirm method being called @ render time.

  • return:

    = success FALSE if u want to trigger an error

TRUE pre_confirm ()
set_action (line 612)

Save the action for the form

void set_action (string $action)
  • string $action:

    - the action from the post.

set_action_message (line 759)

This sets the action message.

This is called from withint the form_action() method

void set_action_message (string $message)
  • string $message:

    - the action message

set_cancel_action (line 773)

This method sets the javasript action

to be taken when the cancel button is clicked. Calling this method w/ a non NULL value automatically enables the Cancel button.

void set_cancel_action (string $action)
  • string $action:

    - the javascript cancel action

set_confirm (line 725)

This sets the $this->_has_confirmation

flag. to let the object know it has a required confirmation page, which should get called after the validation is successfull, and before the action is handled on the back-end.

void set_confirm ([boolean $flag = TRUE])
  • boolean $flag:

    - the flag value TRUE/FALSE

set_default_css (line 686)

This function is used to set the

default CSS class used on form field text when there is no error on that field

void set_default_css (string $css)
  • string $css:

    - the css class to use

set_element_value (line 537)

This method is used to set the value for a non hidden element

void set_element_value (string $label, value $value)
  • string $label:

    - the form label

  • value $value:

    - the new value

set_error_css (line 710)

This function is used to set the css class that is used on text when an error on that field is detected.

void set_error_css (string $css)
  • string $css:

    - the css class to use.

set_form_errors_title (line 671)

This allows us to change the form errors table title

void set_form_errors_title (string $title)
  • string $title:

    - the new title

set_form_errors_width (line 660)

This method allows you to override the width of the form errors table.

By default it uses the width of the form as its size.

void set_form_errors_width (string $width)
  • string $width:

    - the width

set_form_name (line 602)

**************************

void set_form_name (mixed $name)
set_form_width (line 631)

this method sets the form name

void set_form_width (string $width)
  • string $width:

    - the form name

set_hidden_element_value (line 562)

This method is used to set the value for a hidden element

void set_hidden_element_value (string $label, value $value)
  • string $label:

    - the form label

  • value $value:

    - the new value

set_required_marker (line 950)

This function is used to set the required field marker

void set_required_marker (string $marker)
  • string $marker:

    - the marker

set_required_text (line 959)

This sets the required text

void set_required_text (string $text)
  • string $text
set_stripslashes (line 748)

This sets the stripslashes flag for this object.

void set_stripslashes ([boolean $flag = TRUE])
  • boolean $flag
_test_element (line 974)

This method tests to see if we have an element named $label, so we can operate on it.

void _test_element (string $label, string $method, [boolean $hidden = FALSE])
  • string $label:

    - the element's label

  • string $method:

    - the name of the method that called us

  • boolean $hidden:

    - test a hidden element?

Documention generated on Thu, 31 Jul 2003 18:32:42 -0700 by phpDocumentor 1.2.0