This is a very useful tool which aids in the creation, and saving, of form information. It is recommended that you use this when creating, well, any type of form to allow plugins the ability to modify how a form operates.
Originally the Form class was just one single component, but after SnowCMS 2.0 alpha, the Form was overhauled and split up into two separate components, the other being the Input class which handles each input individually and separately from the entire form itself.
Now input’s can be created and then added to a form, or they can be created here.
While this class can be used to display the Form in its entirety, it may also be used to generate bits and pieces of the form as well. More information on that later!
| Form | This is a very useful tool which aids in the creation, and saving, of form information. |
| Variables | |
| forms | An array containing all the registered forms and their options. |
| current | A string containing the name of the current form being used. |
| Functions | |
| __construct | Not much done here except initializing the attributes. |
| current | Sets or returns the current form to be used with any form operation if no form is specifically identified. |
| add | Adds a new form which can then be used to create forms, of course! |
| edit | Allows the forms options to be edited. |
| exists | Determines whether or not the specified form exists. |
| remove | Removes the specified form. |
| return_form | Returns the specified form and all of its information. |
| add_input | Adds an input to the specified form. |
| input_exists | Checks to see if the specified input exists within the form. |
| remove_input | Removes the specified input from the form. |
| input | Returns the specified input, which can then be used to manipulate it. |
| inputs | Returns an array containing all the inputs that exist within the specified form. |
| open | Returns the opening of the form, which would be the <form action=”... |
| close | Returns the closing of the form, which would be the ...</form> part. |
| generate | Generates the HTML for the input specified in the form. |
| render | Renders the entire form, from beginning to end, in a table-like format, just as was done with the previous Form class (in SnowCMS 2.0 alpha). |
| process | By calling this method, the entire form will be processed, which involves determining any errors caused by user input. |
| errors | Returns an array containing any errors generated when processing the specified form. |
| clear_data | Clears data from the specified forms input. |
| hooked | Determines whether or not the form has already had hooks ran. |
private $current
A string containing the name of the current form being used. This allows a form name to be set which will be used when doing any form operations such as adding another input. For more information on that, see Form::current.
| __construct | Not much done here except initializing the attributes. |
| current | Sets or returns the current form to be used with any form operation if no form is specifically identified. |
| add | Adds a new form which can then be used to create forms, of course! |
| edit | Allows the forms options to be edited. |
| exists | Determines whether or not the specified form exists. |
| remove | Removes the specified form. |
| return_form | Returns the specified form and all of its information. |
| add_input | Adds an input to the specified form. |
| input_exists | Checks to see if the specified input exists within the form. |
| remove_input | Removes the specified input from the form. |
| input | Returns the specified input, which can then be used to manipulate it. |
| inputs | Returns an array containing all the inputs that exist within the specified form. |
| open | Returns the opening of the form, which would be the <form action=”... |
| close | Returns the closing of the form, which would be the ...</form> part. |
| generate | Generates the HTML for the input specified in the form. |
| render | Renders the entire form, from beginning to end, in a table-like format, just as was done with the previous Form class (in SnowCMS 2.0 alpha). |
| process | By calling this method, the entire form will be processed, which involves determining any errors caused by user input. |
| errors | Returns an array containing any errors generated when processing the specified form. |
| clear_data | Clears data from the specified forms input. |
| hooked | Determines whether or not the form has already had hooks ran. |
public function current( $name = null )
Sets or returns the current form to be used with any form operation if no form is specifically identified.
| string $name | The name of the form to use by default when no other is specified. |
| mixed | Returns the name of the form that will be used if no other is specified if $name is left empty, but true if the default form was changed successfully and false if not (e.g. the form does not exist). |
This affects such operations as Form::add_input, Form::remove_input, Form::generate, and any other which asks for a form identifier (other than methods directly correlating to forms themselves, such as Form::add, Form::remove, Form::exists, etc.) which makes things a bit simpler.
public function add( $name, $options )
Adds a new form which can then be used to create forms, of course!
| string $name | The name of the form to create, which will be used as the identifier when adding or any other form specific related operation later on. Please note form names are case insensitive. |
| array $options | An array containing options about the form itself. See the notes for more information. |
| bool | Returns true if the form was added successfully, false on failure. |
The following is a list of indices which are supported by $options:
| string accept-charset | Specifies the supported character sets for the data contained within the form. |
| string action | The URL where the form should submit the data to. |
| callback callback | A callback which will be passed all the form information if the form data is valid. |
| bool csrf-token | Whether or not a CSRF protection token to the form, see below for more information. Defaults to true. |
| mixed enctype | Specifies how the form data will be encoded when sent. If a file field is added, the enctype will automatically be changed to multipart/form-data. |
| string id | The unique HTML id for the form tag. This will be used to assign all added input’s id’s as well. Defaults to the form’s name. |
| string method | The way the form will be submitted, which is either post or get. Defaults to post. Also, all input’s will be changed to the specified submission method. |
| string submit | The text of the submit button. This may be irrelevant if the form is not rendered via the Form::render method. |
The only option required is to have a valid callback, which can be any callback supported by <www.php.net/call_user_func>.
The callback is expected to accept two parameters. The first being an array which will contain the data from all the input’s that exist within the form (formatted as such: array({input name} => mixed value)). The second parameter is a reference parameter which contains an array, which is to be used if any more errors occurred with the data received. This is useful if there is any extra validation that needs to be done. The callback also needs to return false if there were any more errors generated, but can return whatever it wants if the form was successfully processed. Excluding false, of course.
PLEASE NOTE: The Form class automatically adds an input of its own, which is called {form name}_token, which is used for CSRF (Cross Site Request Forgery) protection. If Form::open and Form::close are called when displaying the form manually (e.g. without the use of Form::render) then this input will automatically be displayed on the web page as well. However, if they are not used, then the input must be displayed manually by using the Form::generate method with the input name of {form name}_token, otherwise the form will always be invalid and will show an error indicating that the form token was invalid. This automatic protection feature may be disabled by setting the csrf-token option to false.
public function edit( $name, $options )
Allows the forms options to be edited.
| string $name | The name of the form to be edited. |
| array $options | An array containing the new options to be applied to the specified form. |
| bool | Returns true if the forms options were successfully edited, false on failure (e.g. the form doesn’t exist). |
public function return_form( $name = null )
Returns the specified form and all of its information.
| string $name | The name of the form to return. If this parameter is left empty then all forms will be returned. |
| array | Returns an array containing the forms information, however if the specified form does not exist, false will be returned. |
public function add_input( $input, $form_name = null, $position = null )
Adds an input to the specified form.
| mixed $input | This can either be an instance of an Input class, or an array containing all the information required to set up an instance of Input, as described by Input::set. |
| string $form_name | The name of the form to add this input to. |
| int $position | The position of where the input should be inserted, starting at 0 (0 means the input will be placed before all others). If this is left empty, the input will, unsurprisingly, be added to the end. |
| bool | Returns true if the input was added successfully, false if not (which could mean that the form does not exist, or that the instance of input was not valid, or that the information supplied to create an instance of the input class was not valid, or an input with the same name already exists). |
If the instance of Input (whether it was directly supplied as an Input or created with the supplied options) is not valid according to the Input::validate method, then the input will not be added.
Keep in mind, you do not have to specify the $form_name parameter if one was set with <Input::current>.
public function input_exists( $name, $form_name = null )
Checks to see if the specified input exists within the form.
| string $name | The name of the input to check for. |
| string $form_name | The name of the form to check. |
| bool | Returns true if the input exists within the specified form, false if not. |
The $form_name parameter does not need to be supplied if one was set with the Form::current method.
public function remove_input( $name, $form_name = null )
Removes the specified input from the form.
| string $name | The name of the input to remove. |
| string $form_name | The name of the form which contains the input. |
| bool | Returns true if the input was removed successfully, false if not. |
The $form_name parameter does not need to be supplied if one was set with the Form::current method.
public function input( $name, $form_name = null )
Returns the specified input, which can then be used to manipulate it.
| string $name | The name of the input to return. |
| string $form_name | The form which contains the input. |
| object | Returns the Input object specified with $name. |
The $form_name parameter does not need to be supplied if one was set with the Form::current method.
public function inputs( $form_name = null )
Returns an array containing all the inputs that exist within the specified form.
| string $form_name | The name of the form to retrieve the inputs from. |
| array | Returns an array containing all the inputs which exist within the form, but false if the form does not exist. |
The $form_name parameter does not need to be supplied if one was set with the Form::current method.
public function open( $form_name = null )
Returns the opening of the form, which would be the <form action=”... tag. All options set for the form will be used to determine the action, method, etc. attributes of the tag.
| string $form_name | The name of the form. |
| string | A string containing the opening form tag. |
The $form_name parameter does not need to be supplied if one was set with the Form::current method.
This method is only to be used if you do not want to have the form rendered automatically in a table-like format with <Input::render>.
If you do use this method, you should also use Form::close as well.
Please note that before anything is generated a hook called form_{form name} is ran. This hook may also be called in Form::process if it is called before Form::open, in which case the hook will not be ran again in this method.
public function close( $form_name = null )
Returns the closing of the form, which would be the ...</form> part. If there is a CSRF protection token ({form name}_token would be the input’s name) it will be contained within the string returned as well.
| string $form_name | The name of the form. |
| string | A string containing the opening form tag. |
The $form_name parameter does not need to be supplied if one was set with the Form::current method.
public function generate( $name, $element_id = null, $css_class = null, $form_name = null )
Generates the HTML for the input specified in the form.
| string $name | The name of the input to generate. |
| string $element_id | A string containing the HTML element’s id. If none is supplied, it will default to the input’s name. |
| string $css_class | A string (or array) containing CSS classes to assign to the HTML element. |
| string $form_name | The name of the form which contains the input. |
| string | Returns a string containing the generated input, however, if if Input::validate determines that the current options for the Input are invalid, false will be returned. |
The $form_name parameter does not need to be supplied if one was set with the Form::current method.
public function render( $form_name = null )
Renders the entire form, from beginning to end, in a table-like format, just as was done with the previous Form class (in SnowCMS 2.0 alpha). This is only recommended for such things as settings forms.
| string $form_name | The name of the form to render. |
| void | Nothing is returned by this method. |
The $form_name parameter does not need to be supplied if one was set with the Form::current method.
public function process( $form_name = null )
By calling this method, the entire form will be processed, which involves determining any errors caused by user input. If the form is processed successfully (which means there were no errors) then the callback assigned in Form::add will be called upon and passed all the data submitted by the user.
| string $form_name | The name of the form to process. |
| mixed | Returns false if the form was not processed successfully (which means the form has errors which need correcting by the user), however on success the value returned will be anything the callback returns when the form was processed without any issues. |
The $form_name parameter does not need to be supplied if one was set with the Form::current method.
public function errors( $form_name = null )
Returns an array containing any errors generated when processing the specified form.
| string $form_name | The name of the form to obtain the errors from. |
| array | Returns the array containing any generated errors. |
The $form_name parameter does not need to be supplied if one was set with the Form::current method.
public function clear_data( $form_name = null )
Clears data from the specified forms input.
| string $form_name | The name of the form to clear the data from. |
| bool | Returns true if the data was successfully cleared, false if not. |
The $form_name parameter does not need to be supplied if one was set with the Form::current method.
private function hooked( $form_name, $hooks_ran = false )
Determines whether or not the form has already had hooks ran.
| string $form_name | The name of the form. |
| bool $hooks_ran | Set to true if the hooks have just been run. |
| bool | Returns true if the form has already had the hooks run, false if not. |
This is a private method which cannot be used outside of the Form class.
An array containing all the registered forms and their options.
private $forms
A string containing the name of the current form being used.
private $current
Not much done here except initializing the attributes.
public function __construct()
Adds a new form which can then be used to create forms, of course!
public function add( $name, $options )
Allows the forms options to be edited.
public function edit( $name, $options )
Determines whether or not the specified form exists.
public function exists( $name )
Removes the specified form.
public function remove( $name )
Returns the specified form and all of its information.
public function return_form( $name = null )
Adds an input to the specified form.
public function add_input( $input, $form_name = null, $position = null )
Checks to see if the specified input exists within the form.
public function input_exists( $name, $form_name = null )
Removes the specified input from the form.
public function remove_input( $name, $form_name = null )
Returns the specified input, which can then be used to manipulate it.
public function input( $name, $form_name = null )
Returns an array containing all the inputs that exist within the specified form.
public function inputs( $form_name = null )
Returns the opening of the form, which would be the <form action=”...
public function open( $form_name = null )
Returns the closing of the form, which would be the ...</form> part.
public function close( $form_name = null )
Generates the HTML for the input specified in the form.
public function generate( $name, $element_id = null, $css_class = null, $form_name = null )
Renders the entire form, from beginning to end, in a table-like format, just as was done with the previous Form class (in SnowCMS 2.0 alpha).
public function render( $form_name = null )
By calling this method, the entire form will be processed, which involves determining any errors caused by user input.
public function process( $form_name = null )
Returns an array containing any errors generated when processing the specified form.
public function errors( $form_name = null )
Clears data from the specified forms input.
public function clear_data( $form_name = null )
Determines whether or not the form has already had hooks ran.
private function hooked( $form_name, $hooks_ran = false )
This method can be used to set all options for the input field with just one call.
public function set( $name, $label = null, $subtext = null, $type = null, $request_type = null, $length = null, $truncate = null, $options = null, $callback = null, $default_value = null, $disabled = null, $readonly = null, $rows = null, $columns = null, $required = true )
This method will validate all the currently set options for the input field, to make sure that there are no conflicting options or missing options that are only required under certain circumstances.
public function validate()