 |
PhpToolCase
Api Documentation Version 0.9.2
|
|
PhpToolCase
Api Documentation Version 0.9.2
|
The dynamic html forms generator is an excellent tool that will help you build all kinds of html forms in just a few minutes. The component can also be used with the PtcEvent class, to add event listeners to process validation and output generation. This tool will make you forget about all the problems involved with fields alignment, layouts, and server-side validation. For client-side validation the wonderfull jquery validator plugin can be used. This class is especially adviced to webdesigners and webmasters that are having troubles with html forms.
Main Features:
To use this component, you just need to require and initialize the class:
This is the full list of options available on intialization, stored in the PtcForm::$_defaultOptions property:
The following paragraphs will explain in details these options and the usage.
Use this option to set form method(post / get).
Default value: # (string)
This option can be used to set form action attribute. Ex: process-form.php
Default value: 500px (string)
Use this option to set the width of the form.
Default value: 500px (string)
This option adds the respective css classes to fields to validate client side with jquery and the ptcforms-validator.js plugin.
See Adding & Validating Fields With The Validator Engine for details and usage.
Default value: false (bool)
This option can be used for the form layout, it will attempt to align the labels with the fields. Options are "left", "right", "top" or "none" for no labels.
Default value: left (string)
Use "labels_width" to set the width for the labels. Always make sure that the form has the currect width, otherwise the layout migt not be as expected. You can refer to form_width for the form width option.
Default value: 40% (string)
This option can be used to stop adding styles to the input fields automatically, quite usefull if you want to use your own css. The default styles for the inputs are stored in the PtcForm::$_inputStyles property, and can be manipulated with the PtcForm::setInputStyle() method.
See Changing default styles for fields for a detailed usage.
Default value: true (bool)
This option can be used to stop adding styles to the label containers automatically, quite usefull if you want to use your own css. The default styles for the labels are stored in the PtcForm::$_labelStyles property, and can be manipulated with the PtcForm::setLabelStyle( ) method.
See Changing Default Styles For Label Containers for a detailed usage.
Default value: true (bool)
This option can be used to stop adding width to the tables automatically, quite usefull if you want to use your own css.
Default value: true (bool)
The "spacer_height" option can be used to change the height between fields.
Default value: 3px (string)
This options is used to reload already inserted values in the fields if form was submitted. It could be usefull set to false, for a login form as inserted values will not be reproposed upon submission, as shown in the pctforms-ex1.php example file.
Default value: true (bool)
Prints the form or returns the output generated by the PtcForm::render( ) method as a string if set to "false".
Default value: true (bool)
This option controls the start tab for the html output. If you would lneed to increase the offset add more tabs, ex: \t\t\t
Default value: \t (string)
The "err_msg_level" is used to set the severity of the error for execution errors within the class itself. Use "E_USER_NOTICE" for a lower severity and "E_USER_ERROR" for a higher severity
Default value: E_USER_WARNING (const)
The "default_category" is used for the PtcDebug class to set a category for the messages panel. Change it to customize the debug output.
Default value: PtcForm (string)
The "event_class" option can be used to change the event class that will work with observers. Change this option if the PtcEvent component is under a namespace or it has been extended.
See Using Observers to understand how events work.
Default value: \PtcEvent (string)
The following paragraph will cover all possible parameters that can be passed to the PtcForm::addElement( ) method, and their usage.
Here is a list of all possibile parameters that can be passed to the PtcForm::addElement( ) method as array keys for the "$params" parameter:
Some of these parameters can be added to field values like select and radio / checkbox groups, with "[brackets]" (Ex.: attributes[ ]).
See Using [brackets] To Add Parameters To Field Values for detailed usage.
The following sections, will explain in details the usage of these parameters:
This parameter defines the field name and is mandatory, the class will throw a warning if not set, and the field will not be processed by the compiler.
Type: string
This parameter defines the field type. If not set, "text" will be used.
Possible field types:
text (default) password radio checkbox checkboxgroup radiogroup textarea select fieldset composite (for complex field layouts) custom (any html code can be passed as value) submit Type string
Use this parameter to set the the text for the label of the field.
Type string
Adds html attributes to the field, all attributes are stored in PtcForm::$_elAttributes property. New attributes can be added with the PtcForm::addElAttribute() and PtcForm::addElAttributes() methods, see Extending The Compiler With Custom Attributes.
See Adding Attributes To Fields for examples and detailed usage.
Type array
Adds html attributes to the label container, all attributes are stored in PtcForm::$_elAttributes property. New attributes can be added with the PtcForm::addElAttribute() and PtcForm::addElAttributes() methods, see Extending The Compiler With Custom Attributes.
See Adding Attributes To Label Containers for examples and detailed usage.
Type array
Adds html attributes to the parent container of the field, all attributes are stored in PtcForm::$_elAttributes property. New attributes can be added with the PtcForm::addElAttribute( ) and PtcForm::addElAttributes( ) methods, see Extending The Compiler With Custom Attributes.
See Adding Attributes To Field Containers for examples and detailed usage.
Type array
The events parameter can be used to add javascipt events to the fields.
the following field types are supported:
text password textarea submit select radio checkbox checkboxgroup (will be added to all values) radiogroup (will be added to all values) See Adding JavScript Events for detailed usage.
Type array
Use this parameter to add the field to the validator engine.
These are the possible validator options:
The following field types are supported:
text password textarea submit select radio checkbox checkboxgroup (will be added to all values) radiogroup (will be added to all values) See Adding Fields To The Validator for example usage.
Type string|array
The parameter "values" is used to add values for the following fields:
select checkboxgroup radiogroup composite fieldset See Adding Values As Array (select, radiogroup, checkboxgroup) for examples on how to add values for select,radiogroup and checkboxgroup.
See Adding Fields As Array Of Values (composite, fieldset) for examples on how to add values for composite and fieldset.
Type array
The parameter "value" can be used to add the value as a string for the following field
text password textarea submit radio checkbox custom (any html code can be passed as value) See Adding Values As A String for example usage.
Type string
The PtcForm::addElement() method is used to add form fields. Works with all input types, but some extra parameters can be passed aswell to create custom html. The "$params" paramater is used to pass the configuration for the field to the method as an array. See Field Parameters paragraph, for all possibile parameters.
The following sections will try to demonstrate how we can add some of these fields.
Here's a quick example on how to add text fields:
The following fields can be created like shown in the example above as they do not require a "value":
text radio checkbox textarea password submit The following fields require a "value", or the class will throw a warning:
select radiogroup checkboxgroup composite fieldset custom Here's an example on how to add select elements:
To make an option selected you can use "[brackets]", see Using [brackets] To Add Parameters To Field Values.
The following example shows how to add checkboxgroups, adding radiogroups is just the same:
To make a checkbox checked you can use "[brackets]", see Using [brackets] To Add Parameters To Field Values. note the "cols" attribute controls how many columns the group will have. The default value is 1.
Composite fields are used for complex layouts, as the can be nested inside each other. This allows to have many fields inline for example, or a form with fields in 2 columns.
The following fields can be added like shown in the example above: fieldset, composite.
"cols" attribute controls how many columns the group will have. The default value is "inline".This is how we can add a custom field, in this case we will use the PtcForm::addSpacer( ) method, but keep in mind that any html can be passed as "value" for this field type.
The custom field type will only accept the following parameters:
name type value Any other parameter will be dropped silently.
This section will try to cover how to add attributes to fields, labels and containers. All Attributes are stored in PtcForm::$_elAttributes property. New attributes can be added with the PtcForm::addElAttribute() and PtcForm::addElAttributes() methods, see Extending The Compiler With Custom Attributes.
The parameter "attributes" is used to add html attributes to form fields:
To add attributes to values for select and radio/checkbox groups we can use "[brackets]" like shown in the next example:
See Using [brackets] To Add Parameters To Field Values for more details.
The parameter labelOptions is used to add html attributes to the label container:
To add attributes to label containers of the field values for radio/checkbox groups we can use "[brackets]" like shown in the next example:
See Using [brackets] To Add Parameters To Field Values for more details.
The parameter parentEl is used to add html attributes to the field container:
To add attributes to the parent containers of the field values for radio/checkbox groups we can use "[brackets]" like shown in the next example:
See Using [brackets] To Add Parameters To Field Values for more details.
The PtcForm::addElAttribute( ) and PtcForm::addElAttributes( ) methods are used to add more attributes to be compiled with the fields and containers. The default attributes are stored in the PtcForm::$_elAttributes property:
The methods PtcForm::setInputStyle( ) and PtcForm::setLabelStyle( ) can be used to manipulate the default styles for fields and label containers. The following chapters will try to cover these methods with practical examples.
The PtcForm::setInputStyle( ) method is used to change the default styles for the fields:
The default styles are stored in the PtcForm::$_inputStyles property.
The PtcForm::setLabelStyle( ) method is used to change the default styles for the label containers. The "$type" parameter is to control the alignment of the fields, if left empty, the default labels_align option will be used.
The default styles are stored in the PtcForm::$_labelStyles property:
The PtcForm class accepts closures as field parameters with the PtcForm::addElement( ) method. The following example shows how we can take advantage of this feature:
The PtcForm::customTpl() and PtcForm::customTpls() methods can be used to manipulate the default html templates stored in the PtcForm::$_htmlTpls property. The following examples show how we can add an id to the main container holding the form, and replacing the spacer template to add "hr":
The html templates are stored in the PtcForm::$_htmlTpls property:
The parameters values and value are used to add values to form fields. An array is passed for select, checkboxgroup, radiogroup, fieldset and composite fields. The rest of the fields use a string as value.
The parameter value can be used to add a value as a string for the following fields:
text radio checkbox textarea password submit custom (any html code can be passed as value) This is how we can add a value to a field as a string:
The same result can be achieved with the attributes parameter:
The parameter values can be used to add an array of values for the following fields:
select radiogroup checkboxgroup The following examples demonstrate how values can be added as an array, with values as array keys and labels as array values:
To add parameters to values "[brackets]" can be used, see Using [brackets] To Add Parameters To Field Values for more details.
The parameter"values can be used to add an array with previously created field names as values for the following fields:
fieldset composite The following examples demostrate how values can be added as an array with the names of the previously created fields as values:
Composite fields can be nested to achieve complex layouts, but rememeber to always add the fields in the proper order or the class will not find them.
The following fields allow the use of "[brackets]" to add parameters to the values:
select radiogroup checkboxgroup the select input only accepts "[brackets]" for the attributes parameter:
Radio/checkbox groups accept the following parameters with "[brackets]":
To interact with all values just use []. To interact with only 1 value use the array key of the respective value like shown in the next example:
The only 2 exceptions are events and validate which will be added to all values also without "[brackets]", as no validation or events can be attached to the main field.
The events parameter is used to attach javascript events to form fields:
To add js events to 1 value for radio/checkboxgroup use "[brackets]", as shown in the next example:
See Using [brackets] To Add Parameters To Field Values for more details over this option.
The PtcForm::render( ) method is used to build and output the form. The method accepts 2 argumets, "$attributes" and "$events" for the form:
To only build the form and store the html inside a variable, we can set the print_form option to "false":
The following section will try to cover the validation process (server-side) of a form, by using the class built-in engine. For validating client-side, you can use the ptcforms-validator.js ui-plugin. At the bottom of the page you will find intructions on how to set up the client-side validation with jquery.
The validate parameter adds the form fields to the validator engine.
If add_class_validator option is set to true, validator will add the above options as a class attribute to the fields for jquery validator plugin ptcforms-validator.js. "pattern" and "equalTo" will be added as attributes, as they are in the PtcForm::$_elAttributes property.
These are the possible validator options:
required - checks if field has a value email - checks if email is a valid format equalTo - checks if value is equal to another field specified in the value parameter number - checks if the value is numeric pattern - checks if the value matches a given regex pattern Here's an example on how to use these parameters:
Any other value will be interpreted as a custom function:
Radio/checkbox groups will add validation to all field values, to add validation to 1 value for radio/checkboxgroup use "[brackets]":
See Using [brackets] To Add Parameters To Field Values for more details.
The PtcForm::validate( ) method validates the form fields defined with the validate parameter, and returns an array with isValid(bool) and errors(array) as array keys.
For the validator to work, remember to always call the PtcForm::validate() method after building the fields, otherwise the validator will not be aware of the form fields. To get around this problem, you can try to run the following methods against the $_POST or $_GET arrays:
The PtcForm component can be used with the PtcEvent class, to add event observers to process validation and output generation.
Here follows a list with all event observers and possible arguments, when they are fired:
&$object->_validate , &$object->_errMsg , $object ), called on form validation failure &$object->_validate , &$object->_errMsg , $object ), called on form validation success $button_name , $object ) called on form submission $field_name , $field_type , &$params , $object ), called every time an element is about to be added $field_name , &$object->_fields[ $field_name ] , $object ), called after each element is added &$container , $this ), called before form is rendered &$container , $object ), called after the form is rendered $k , &$object->_fields[ $k ] , $this ), called before each field html container is created $k , &$fields , $this ), called after each field html container is created $key , &$k , &$method ), called before each field is about to be validated $k , $method , &$errs ), called after each field has been validated To use these observer events, add them as static methods to your extended class:
On form submission, the "submit" event will be triggered, which will validate the form. If the form is not valid, the "error" event will be triggered. The "valid" event will fire instead, if form was valid.
Observers can be registered with the method PtcForm::observe( ):
To add options on initialization, add the method boot( ) to your extended class:
"boot( )" method will be called by the contructor.Fields can be added directly inside an extended class, which is convenient if you want to use the form multiple times.
Add the method formFields( ) to your class , and configure your form fields inside:
1.8.5