DLForm

Provides a framework for management of forms.

Note that this class has now been deprecated. Use of DL Suite: Forms Manager is suggested as the replacement.

Summary

DLForm	Provides a framework for management of forms.
Constants
Fields
Validation
Private Data
$fields	(array) An array containing all of the form fields.
$hasUpload	(boolean) Specifies whether or not there is an upload field.
Class Construction
__construct	Create a new instance of DLForm.
Data Retrieval
GetAttributes	Retrieve a string representation of the attributes for the given field.
GetText	Retrieve the text for the given field.
GetValue	Retrieve the value for the given field.
HTML Retrieval
GetCleanField	Retrieve the HTML for a certain field type using the provided information.
GetField	Retrieve the HTML for the given field name.
GetFooter	Retrieve the HTML for the footer of the form.
GetHeader	Retrieve the HTML for the header of the form.
Miscellaneous
AddField	Add a form field.
Validate	Validate this form.

Constants

Fields

InputButton	(string) Represents an Input Button field.
InputCheckbox	(string) Represents an Input Checkbox field.
InputCheckboxGroup	(string) Represents an Input Checkbox field that is part of a group.
InputFile	(string) Represents an Input File field.
InputHidden	(string) Represents an Input Hidden field.
InputPassword	(string) Represents an Input Password field.
InputRadio	(string) Represents an Input Radio field.
InputRadioGroup	(string) Represents an Input Radio field that is part of a group.
InputReset	(string) Represents an Input Reset field.
InputSubmit	(string) Represents an Input Submit field.
InputText	(string) Represents an Input Text field.
Option	(string) Represents an Option field.
Select	(string) Represents a Select field.
Textarea	(string) Represents a Textarea field.

Validation

ValidateCustom	(int) Using a user defined function.
ValidateEmail	(int) An e-mail address.
ValidateRequired	(int) Non-empty string.

Private Data

$fields

private $fields

(array) An array containing all of the form fields.

$hasUpload

private $hasUpload

(boolean) Specifies whether or not there is an upload field.

Class Construction

__construct

public function __construct()

Create a new instance of DLForm.

Returns

(DLForm) An instance of DLForm.

Data Retrieval

GetAttributes

private function GetAttributes( $field )

Retrieve a string representation of the attributes for the given field.

Note that this will not return the ‘text’ or ‘value’ attribute. Use the method GetText and GetValue for that. The attribute ‘selected’ is also omitted from this and is retrieved via the method GetValue as well.

Parameters

$field

(array) An associative array that contains the field information.

Returns

(string) All of the attributes for the given field.

GetText

private function GetText( $field )

Retrieve the text for the given field.

By default, if the attribute ‘text’ exist for the given field, it is returned, otherwise, the value of the attribute ‘value’ will be used instead. If ‘value’ is also empty, then use the ‘name’ of the field, capitalizing the first letter.

Parameters

$field

(array) The field in which the text should be retrieved for.

Returns

(string) The text for the given field.

GetValue

private function GetValue( $field,
$options = array() )

Retrieve the value for the given field.

Parameters

$field	(array) The field in which the value should be retrieved for.
$options	(array) Optional and defaults an empty array. This specifies configurations for this method.

The structure of the $options parameter, if given, should look like the following:

array(
    value_only => {
        (boolean) If set to TRUE, then only the value will be
        returned, otherwise, the value will be wrapped around by the
        value attribute. Defaults to FALSE.
    }
)

Returns

(array) The returned array will look similar to:

array(
    'is_post' => {whether or not the value is from POST},
    'value' => {the actual value iteself}
)

HTML Retrieval

GetCleanField

public function GetCleanField( $name,
$type,
$options = array() )

Retrieve the HTML for a certain field type using the provided information.

Parameters

$name	(string) The name of the form field.
$type	(string) The type of the field.
$options	(array) An associative array containing various options used by this method. Defaults to an empty array.

The structure for the $options parameter, if it is given, should look like the following:

array(
    'attributes' => {
        (array) An associative array containing any other attributes
        to be set for the field. The structure of this array should
        look like the following:

        array(
            {attribute's name} => {attribute's value},
            ...
        )

        Defaults to an empty array.
    },
    'id' => {
        (string) The identifier for the field. Defaults to an
        randomly generated string.
    },
    'options' => {
        (array) An associative array containing values for all
        options field if the given $type is DLForm::Select. The
        structure of this array should look like the following:

        array(
            {option's value} => {option's text},
            ...
        )
    },
    'value' => {
        (mixed) The value that should be the default value for the
        field. If the given $type is DLForm::Select, this can be
        an array containing all values that should be pre-selected.
        Defaults to an empty string.
    }
)

GetField

public function GetField( $name,
$options = array() )

Retrieve the HTML for the given field name.

Parameters

$name	(string) The name of the form field.
$options	(array) Optional and defaults to an empty array. This specifies configurations for this method.

The structure of the $options parameter, if given, should look like the following:

array(
    label => {
        (boolean) Whether or not a label tag should be included with
        the resulting HTML. Defaults to TRUE.
    }
)

Returns

(string) The HTML for the requested field.

GetFooter

public function GetFooter()

Retrieve the HTML for the footer of the form.

Returns

(string) The HTML for the footer.

GetHeader

public function GetHeader( $action,
$options = array() )

Retrieve the HTML for the header of the form.

Parameters

$action	(string) The action URL for the form.
$options	(array) Optional and defaults to an empty array. This specifies configurations for this method.

The structure of the $options parameter, if given, should look like the following:

array(
    class => {
        (string) The class name for the FORM tag. Defauls to
        "DLForm".
    },
    method => {
        (string) The method to submit the form. Defaults to "POST".
    }
)

Returns

(string) The HTML for the header.

Miscellaneous

AddField

public function AddField( $name,
$type,
$attributes = array(),
$options = array() )

Add a form field.

Parameters

$name	(string) The name of the field.
$type	(string) The type of the form fields. Use the provided constants for this parameters.
$attributes	(array) Optional and defaults to an empty array. Any extra attributes for the field. The key of the array will be the attribute and its value is the attribute’s value. Also note that the value will be surrounded by double quotes so be sure to add slashes appropriately. For all OPTION fields, the attribute of ‘text’ will be the text between the opening and closing option tags if it is given, otherwise ‘value’ will be used. For all TEXTAREA fields, the attribute ‘value’ will be the text between the opening and closing textarea tags and won’t be surrounded by double quotes. It will also be passed through the function htmlentities. All other type of fields, if the attribute ‘text’ isn’t given, then ‘value’ will be used as part of the label. Note that a label will not be included for a OPTION or SELECT field.
$options	(array) Optional and defaults to an empty array. This specifies configurations for this method.

The structure of the $options parameter, if given, should look like the following:

array(
    custom => {
        (callback) This is only used be the option *validate* is set
        to DLForm::ValidateCustom. The function to be used to
        validate the field. Defaults to an empty string.
    },
    use_post => {
        (boolean) When this is set to TRUE, if there is a POST
        variable with the same name as the given "$name", then the
        value of that POST variable will be used as the value.
    },
    validate => {
        (int) Specify whether or not the given field should be
        validated. Defaults to 0.
    }
)

Returns

(boolean) Returns TRUE if successful, FALSE, otherwise.

Validate

public function Validate()

Validate this form.

Returns

(mixed) Returns an array of all the fields that fails validation. If no errors were found, then this will return FALSE.