Docs For Class FormContent

## 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 /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.
SampleForm | This is the Class that handles the building of the Form itself. It creates the Form Elements inside the form_init_elements() method.
MasterSlaveForm | 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
mixed $_action_counter
mixed $_action_message
mixed $_cancel_action
mixed $_default_label_css
mixed $_elements
mixed $_error_label_css
mixed $_file_elements
mixed $_FormValidation
mixed $_form_action_elements_on_submit
mixed $_form_errors_title
mixed $_form_errors_width
mixed $_form_name
mixed $_form_on_submit
mixed $_has_confirm
mixed $_has_file_element
mixed $_hidden_elements
mixed $_is_readonly
mixed $_label_colon_flag
mixed $_required_field_marker
mixed $_required_field_text
mixed $_stripslashes
mixed $_width
Method Summary
FormContent 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])
INPUTtag add_action_element (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)
bool element_exists (string $label)
Object element_form (string $label)
Object element_label (string $label)
Container form ()
boolean form_action (array 0)
boolean form_backend_validation ()
mixed form_confirm ([string $title = "Form Confirmation"], [boolean $show_buttons = TRUE])
TABLEtag form_errors ()
void form_init_data ()
void form_init_elements ()
mixed form_success ()
string get_action ()
object get_action_element (string $label)
array get_all_element_values ()
string get_default_css ()
Object &get_element (string $label)
value get_element_value (string $label)
array get_error_array ()
int get_form_errors_width ()
void get_form_name ()
the get_form_tabindex (string $label, int $index)
value get_hidden_element_value (string $label)
string get_required_marker ()
boolean has_confirm ()
Object hidden_element_label (string $label)
bool is_readonly ()
string javascript ()
TRUE pre_confirm ()
void set_action (string $action)
void set_action_message (string $message)
void set_cancel_action (string $action)
void set_colon_flag ([mixed $flag = TRUE])
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)
none set_form_tabindex (string $label, int $index)
void set_form_width (string $width)
void set_hidden_element_value (string $label, value $value)
void set_readonly ([bool $flag = TRUE])
void set_required_marker (string $marker)
void set_required_text (string $text)
void set_stripslashes ([boolean $flag = TRUE])
void _pre_confirm ()
void _set_validation_object (FormValidation &$FormValidation)
void _test_element (string $label, string $method, [boolean $hidden = FALSE])
Variables
mixed $_action_counter = 0 (line 183)

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 $_file_elements = array() (line 201)

index names of all of the file form elements (if any).

mixed $_FormValidation = NULL (line 224)

This is the FormValidation object

used to validate the form elements

mixed $_form_action_elements_on_submit = '' (line 218)

The onsubmit value for the form

tag. This is used by form action elements to add disable on submit

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 $_form_on_submit = '' (line 211)

The onsubmit value for the form

tag. FormElement childs can automatically add to this by implementing the form_tag_onsubmit() method

mixed $_has_confirm = FALSE (line 120)

flag to let the FormProcessor

object know this form has a confirmation page that is required

mixed $_has_file_element = FALSE (line 195)

Flag to mark this as having a

File Form Element (child of FEFile)

mixed $_hidden_elements = array() (line 91)

This holds the array of

hidden form elements used in this form

mixed $_is_readonly = FALSE (line 234)

Indicates this entire FormContent is in readonly mode. This forces all of the FormElement to be in readonly mode.

mixed $_label_colon_flag = FALSE (line 177)

The form Element's flag to add the : character at the end of the label.

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 189)

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 237)
FormContent FormContent ([mixed $width = "100%"], [mixed $cancel_action = NULL])
add_action (line 976)

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_action_element (line 558)

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

- return: object

INPUTtag add_action_element (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 1102)

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 513)

This method is used to add a form element

void add_element (FormElement &$element)

- FormElement &$element: object

add_error (line 740)

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 1031)

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 540)

This method is used to add a hidden form field

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

- FormElement $label: object

add_image_action (line 1068)

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 376)

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)

- InfoTable &$table: object

element_exists (line 727)

This method is used to test if the element exists in a form

bool element_exists (string $label)

- string $label: - the form label

element_form (line 627)

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 602)

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

Object element_label (string $label)

- string $label: - the element's label

form (line 281)

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.
- SampleForm::form() : This is the method that builds the layout of where the FormElements will live. You can lay it out any way you like.
- MasterSlaveForm::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 428)

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:

- AccountForm::form_action() : This method is called ONLY after ALL validation has passed. This is the method that allows you to do something with the data, say insert/update records in the DB.
- SampleForm::form_action() : This method is called ONLY after ALL validation has passed. This is the method that allows you to do something with the data, say insert/update records in the DB.
- MasterSlaveForm::form_action() : This method is called ONLY after ALL validation has passed. This is the method that allows you to do something with the data, say insert/update records in the DB.
- StandardFormContent::form_action() : This method handles the form action.

form_backend_validation (line 400)

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.
- SampleForm::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 345)

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 459)

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 268)

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:

- AccountForm::form_init_data() : This method is called only the first time the form page is hit. This enables u to query a DB and pre populate the FormElement objects with data.
- SampleForm::form_init_data() : This method is called only the first time the form page is hit. This enables u to query a DB and pre populate the FormElement objects with data.
- MasterSlaveForm::form_init_data() : This method is called only the first time the form page is hit. This enables u to query a DB and pre populate the FormElement objects with data.
- Step1::form_init_data() : This method is called only the first time the form page is hit.
- Step2::form_init_data() : This method is called only the first time the form page is hit.
- Step3::form_init_data() : This method is called only the first time the form page is hit.
- StandardAccountForm::form_init_data() : This method is called only the first time the form page is hit.

form_init_elements (line 248)

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:

- AccountForm::form_init_elements() : This method gets called EVERY time the object is created. It is used to build all of the FormElement objects used in this Form.
- SampleForm::form_init_elements() : This method gets called EVERY time the object is created. It is used to build all of the FormElement objects used in this Form.
- MasterSlaveForm::form_init_elements() : This method gets called EVERY time the object is created. It is used to build all of the FormElement objects used in this Form.
- Step1::form_init_elements() : This method gets called EVERY time the object is
- Step2::form_init_elements() : This method gets called EVERY time the object is
- Step3::form_init_elements() : This method gets called EVERY time the object is
- StandardAccountForm::form_init_elements() : This method gets called EVERY time the object is

form_success (line 442)

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 798)

Get the current status of the action.

string get_action ()
get_action_element (line 591)

This function returns a submit action by label

object get_action_element (string $label)

- string $label: label

get_all_element_values (line 1174)

return the values of all visible form elements as an array

- access: public

array get_all_element_values ()
get_default_css (line 873)

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

- return: - the current default css

string get_default_css ()
get_element (line 639)

This method returns the FormElement based on the label.

Object &get_element (string $label)

- string $label: - the element's label

get_element_value (line 665)

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 488)

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

array get_error_array ()
get_form_errors_width (line 820)

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_form_name (line 778)
void get_form_name ()
get_form_tabindex (line 715)

This method is a helper method to get the FormElement's tabindex.

- return: FormElement's current tabindex

the get_form_tabindex (string $label, int $index)

- string $label: - the form label
- int $index: - the FormElement's tabindex

get_hidden_element_value (line 689)

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_marker (line 1127)

This function is used to get the required field marker

- return: - the marker

string get_required_marker ()
has_confirm (line 913)

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 614)

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

Object hidden_element_label (string $label)

- string $label: - the element's label

is_readonly (line 765)

Is this element in read only mode?

bool is_readonly ()
javascript (line 294)

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 306)

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 788)

Save the action for the form

void set_action (string $action)

- string $action: - the action from the post.

set_action_message (line 935)

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 949)

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_colon_flag (line 959)

This method sets the flag to have ALL of the FormElement's labels be appended with a : character. Some folks like this for some completely unexplained reason.

void set_colon_flag ([mixed $flag = TRUE])
set_confirm (line 901)

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 862)

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 652)

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 886)

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 847)

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 836)

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 774)

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

void set_form_name (mixed $name)
set_form_tabindex (line 702)

This method is a helper method to set the FormElement's tabindex.

none set_form_tabindex (string $label, int $index)

- string $label: - the form label
- int $index: - the FormElement's tabindex

set_form_width (line 807)

this method sets the form name

void set_form_width (string $width)

- string $width: - the form name

set_hidden_element_value (line 677)

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_readonly (line 756)

This sets the readonly flag.

When this flag is set, all of the FormElements will be set to readonly.

void set_readonly ([bool $flag = TRUE])

- bool $flag: TRUE = readonly

set_required_marker (line 1118)

This function is used to set the required field marker

void set_required_marker (string $marker)

- string $marker: - the marker

set_required_text (line 1140)

This sets the required text

void set_required_text (string $text)

- string $text

set_stripslashes (line 924)

This sets the stripslashes flag for this object.

void set_stripslashes ([boolean $flag = TRUE])

- boolean $flag

_pre_confirm (line 321)

This is a 'hidden' version of pre_confirm to allow calling the form elements pre_confirm methods. This is needed for forms that have a confirmation requirement and has file inputs.

If the file input FormElement doesn't save off the uploaded file, then the confirmation page will not get the file. apache may nuke the temp file in /tmp.

void _pre_confirm ()
_set_validation_object (line 1191)

This method is used to keep a local reference of the FormProcessor's FormValidation object

void _set_validation_object (FormValidation &$FormValidation)

- FormValidation &$FormValidation: object

_test_element (line 1155)

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?

Documentation generated on Thu, 1 Sep 2005 17:05:58 -0700 by phpDocumentor 1.3.0RC3