| Property | Type | Description | |
|---|---|---|---|
| $controls | array | @var array | |
| $errors | array | @var array | |
| $file_upload | array | This property, available only if a file upload has occurred, will have the same values as
{@link http://php.net/manual/en/reserved.variables.files.php $_FILES} plus some extra values:
- path - the path where the file was uploaded to
- file_name - the name the file was uploaded with
- imageinfo - available only if the uploaded file is an image! an array of attributes specific to the uploaded image as returned by {@link http://www.php.net/manual/en/function.getimagesize.php getimagesize()} but with meaningful names: bits channels mime width height type ({@link http://php.net/manual/en/function.exif-imagetype.php possible types}) html Note that the file name can be different than the original name of the uploaded file! By design, the script will append a number to the end of a file's name if at the path where the file is uploaded to there is another file with the same name (for example, if at the path where a file named "example.txt" is uploaded to, a file with the same name exists, the file's new name will be "example1.txt"). The file names can also be random-generated. See the {@link Zebra_Form_Control::set_rule() set_rule()} method and the upload rule |
|
| $file_upload_permissions | string |
$form->file_upload_permissions = '0777';
The permissions are set using PHP's {@link http://php.net/manual/en/function.chmod.php chmod} function which may
or may not be available or be disabled on your environment. If so, this action will fail silently (no errors or
notices will be shown by the library).
Better to leave this setting as it is.
If you know what you are doing, here is how you can calculate the permission levels:
- 400 Owner Read
- 200 Owner Write
- 100 Owner Execute
- 40 Group Read
- 20 Group Write
- 10 Group Execute
- 4 Global Read
- 2 Global Write
- 1 Global Execute
Default is '0755' |
|
| $variables | array | @var array |
| Method | Description | |
|---|---|---|
| __construct ( string $name, string $method = 'POST', string $action = '', array $attributes = '' ) : void | Constructor of the class | |
| add ( string $type ) : reference | Adds a control to the form. | |
| add_error ( string $error_block, string $error_message ) : void | Appends a message to an already existing {@link Zebra_Form_Control::set_rule() error block} | |
| assets_path ( string $server_path, string $url ) : void | Set the server path and URL to the "process.php" and "mimes.json" files. | |
| assign ( string $variable_name, mixed $value ) : void | Creates a PHP variable with the given value, available in the template file. | |
| auto_fill ( array $defaults = [], boolean $specifics_only = false ) : void | Call this method anytime *before* calling the {@link validate()} method (preferably, right after instantiating the class) to instruct the library to automatically fill out all of the form's fields with random content while obeying any rules that might be set for each control. | |
| captcha_storage ( string $method ) : void | Sets the storage method for CAPTCHA values. | |
| client_side_validation ( $properties ) | Alias of {@link clientside_validation()} method. | |
| clientside_validation ( mixed $properties ) : void | Sets properties for the client-side validation. | |
| csrf ( string $csrf_storage_method = 'auto', integer $csrf_token_lifetime, array $csrf_cookie_config = ['path' => '/', 'domain' => '', 'secure' => false, 'httponly' => true] ) : void | Enables protection against {@link http://en.wikipedia.org/wiki/Cross-site_request_forgery Cross-site request forgery} (CSRF) attacks. | |
| doctype ( string $doctype = 'html' ) : void | By default, this class generates HTML 4.01 Strict markup. | |
| language ( string $language ) : void | Sets the language to be used by some of the form's controls (the date control, the select control, etc.) | |
| render ( string $template = '', boolean $return = false, array $variables = '' ) : mixed | Renders the form. | |
| reset ( ) : void | Resets the submitted values for all of the form's controls (also resets the POST/GET/FILES superglobals) | |
| show_all_error_messages ( boolean $value = false ) : void | Sets how error messages generated upon server-side validation are displayed in an {@link Zebra_Form_Control::set_rule() error block}. | |
| validate ( ) : boolean | This method performs the server-side validation of all the form's controls, making sure that all the values comply to the rules set for these controls through the {@link Zebra_Form_Control::set_rule() set_rule()} method. | |
| validate_control ( string $control ) : boolean | This method performs the server-side validation of a control, making sure that the value complies to the rules set for the control through the {@link Zebra_Form_Control::set_rule() set_rule()} method. |
| Method | Description | |
|---|---|---|
| _convert ( string $control, string $type, integer $jpeg_quality = 85, integer $preserve_original_file = false, boolean $overwrite = false ) : boolean | Converts an image from one type to another. | |
| _csrf_generate_token ( boolean $force = false ) : void | Generates a CSRF token, unique to the current form. | |
| _csrf_validate ( ) : boolean | Validates CSRF token. | |
| _extract_values ( array $array ) : array | Helper method for validating select boxes. It extract all the values from an infinitely nested array and puts them in an uni-dimensional array so that we can check if the submitted value is allowed. | |
| _load_mime_types ( ) : void | Load MIME types from mimes.json | |
| _resize ( string $control, string $prefix, integer $width, integer $height, boolean $preserve_aspect_ratio = true, integer $method = ZEBRA_IMAGE_BOXED, boolean $background_color = 'FFFFFF', boolean $enlarge_smaller_images = true, $jpeg_quality = 85 ) : boolean | Resize an uploaded image | |
| _upload ( string $control, string $upload_path, boolean $filename = true ) : boolean | Uploads a file | |
| _validate_dependencies ( string $id, array $referer = [] ) : boolean | Checks if all the conditions set by the "dependencies" rule are met or not. |
$form = new Zebra_Form('myform');
| public __construct ( string $name, string $method = 'POST', string $action = '', array $attributes = '' ) : void | ||
| $name | string | Name of the form @param string $method (Optional) Specifies which HTTP method will be used to submit the form data set. Possible (case-insensitive) values are POST an GET Default is POST @param string $action (Optional) An URI to where to submit the form data set. If left empty, the form will submit to itself. You should *always* submit the form to itself, or server-side validation will not take place and you will have a great security risk. Submit the form to itself, let it do the server-side validation, and then redirect accordingly! @param array $attributes (Optional) An array of attributes valid for a |
| $method | string | |
| $action | string | |
| $attributes | array | |
| return | void | |
create a new form
$form = new Zebra_Form('my_form');
add a text control to the form
$obj = $form->add('text', 'my_text');
make the text field required
$obj->set_rule(
'required' => array(
'error', // variable to add the error message to
'Field is required' // error message if value doesn't validate
)
);
don't forget to always call this method before rendering the form
if ($form->validate()) {
put code here
}
output the form using an automatically generated template
$form->render();
| public add ( string $type ) : reference | ||
| $type | string | Type of the control to add. Controls that can be added to a form: - {@link Zebra_Form_Button buttons} - {@link Zebra_Form_Captcha CAPTCHAs} - {@link Zebra_Form_Checkbox checkboxes} - {@link Zebra_Form_Date date pickers} - {@link Zebra_Form_File file upload controls} - {@link Zebra_Form_Hidden hidden controls} - {@link Zebra_Form_Image image button controls} - {@link Zebra_Form_Label labels} - {@link Zebra_Form_Note notes} - {@link Zebra_Form_Password password controls} - {@link Zebra_Form_Radio radio buttons} - {@link Zebra_Form_Reset reset buttons} - {@link Zebra_Form_Select selects} - {@link Zebra_Form_Submit submit buttons} - {@link Zebra_Form_Text text box controls} - {@link Zebra_Form_Textarea textareas} - {@link Zebra_Form_Time time pickers} @param mixed $arguments A list of arguments as required by the control that is added. @return reference Returns a reference to the newly created object |
| return | reference | |
create a new form
$form = new Zebra_Form('my_form');
add a text control to the form
$obj = $form->add('text', 'my_text');
make the text field required
$obj->set_rule(
'required' => array(
'error', // variable to add the error message to
'Field is required' // error message if value doesn't validate
)
);
don't forget to always call this method before rendering the form
if ($form->validate()) {
for the purpose of this example, we will do a custom validation
after calling the "validate" method.
for custom validations, using the "custom" rule is recommended instead
check if value's is between 1 and 10
if ((int)$_POST['my_text']) < 1 || (int)$_POST['my_text']) > 10) {
$form->add_error('error', 'Value must be an integer between 1 and 10!');
} else {
put code here that is to be executed when the form values are ok
}
}
output the form using an automatically generated template
$form->render();
| public add_error ( string $error_block, string $error_message ) : void | ||
| $error_block | string | The name of the error block to append the error message to (also the name of the PHP variable that will be available in the template file). @param string $error_message The error message to append to the error block. @return void |
| $error_message | string | |
| return | void | |
| public assets_path ( string $server_path, string $url ) : void | ||
| $server_path | string | The server path (the one similar to what is in $_SERVER['DOCUMENT_ROOT']) to the folder where the "process.php" and "mimes.json" files can be found. With trailing slash! @param string $url The URL to where the "process.php" and "mimes.json" files can be found. With trailing slash! @return void |
| $url | string | |
| return | void | |
create a new form
$form = new Zebra_Form('my_form');
make available the $my_value variable in the template file
$form->assign('my_value', '100');
don't forget to always call this method before rendering the form
if ($form->validate()) {
put code here
}
output the form
notice that we are using a custom template
my_template.php file is expected to be found
and in this file, you may now use the $my_value variable
$form->render('my_template.php');
| public auto_fill ( array $defaults = [], boolean $specifics_only = false ) : void | ||
| $defaults | array | An associative array in the form of $element => $value used for filling
out specific fields with specific values instead of random ones.
For elements that may have more than one value (checkboxes and selects with
the "multiple" attribute set) you may set the value as an array.
// auto-fill all fields with random values
$form->auto_fill();
// auto-fill all fields with random values
// except the one called "email" which should have a custom value
$form->auto_fill(array(
'email' => '[email protected]',
));
// auto-fill all fields with random values
// except a checkboxes group where we select multiple values
// note that we use "my_checkboxes" insteas of "my_checkboxes[]"
// (the same goes for "selects" with the "multiple" attribute set)
$form->auto_fill(array(
'my_checkboxes' => array('value_1', 'value_2'),
));
@param boolean $specifics_only (Optional) If set to TRUE only the fields given in the $defaults argument
will be filled with the given values and the other fields will be skipped.
Can be used as a handy shortcut for giving default values to elements instead
of putting default values in the constructor or using the {@link set_attributes()}
method.
Default is FALSE.
@since 2.8.9
@return void |
| $specifics_only | boolean | |
| return | void | |
| public captcha_storage ( string $method ) : void | ||
| $method | string | Storage method for CAPTCHA values. Valid values are "cookie" and "session". Default is "cookie". @since 2.8.9 @return void |
| return | void | |
| public client_side_validation ( $properties ) |
create a new form
$form = new Zebra_Form('my_form');
disable client-side validation
$form->clientside_validation(false);
enable client-side validation using default properties
$form->clientside_validation(true);
enable client-side validation using customized properties
$form->clientside_validation(array(
'close_tips' => false, // don't show a "close" button on tips with error messages
'on_ready' => false, // no function to be executed when the form is ready
'disable_upload_validation' => true, // using a custom plugin for managing file uploads
'scroll_to_error' => false, // don't scroll the browser window to the error message
'tips_position' => 'right', // position tips with error messages to the right of the controls
'validate_on_the_fly' => false, // don't validate controls on the fly
'validate_all' => false, // show error messages one by one upon trying to submit an invalid form
));
To access the JavaScript object and use the public methods provided by it, use $('#formname').data('Zebra_Form')
where formname is the form's name with any dashes turned into underscores!
Therefore, if a form's name is "my-form", the JavaScript object would be accessed like $('my_form').data('Zebra_Form').
From JavaScript, these are the methods that can be called on this object:
- attach_tip(element, message) - displays a custom error message, attached to the specified jQuery
element
- clear_errors() - hides all error messages;
- submit() - submits the form;
- validate() - checks if the form is valid; returns TRUE or FALSE;
if called with the "false" boolean argument, error messages will
not be shown in case form does not validate
Here's how you can use these methods, in JavaScript:
let's submit the form when clicking on a random button
get a reference to the Zebra_Form object
var $form = $('#formname').data('Zebra_Form');
handle the onclick event on a random button
$('#somebutton').bind('click', function(e) {
stop default action
e.preventDefault();
validate the form, and if the form validates
if ($form.validate()) {
do your thing here
when you're done, submit the form
$form.submit();
}
if the form is not valid, everything is handled automatically by the library
});
| public clientside_validation ( mixed $properties ) : void | ||
| $properties | mixed | Can have the following values:
- FALSE, disabling the client-side validation;
Note that the {@link Zebra_Form_Control::set_rule() dependencies} rule will
still be checked client-side so that callback functions get called, if it is
the case!
- TRUE, enabling the client-side validation with the default properties;
- an associative array with customized properties for the client-side validation;
In this last case, the available properties are:
- close_tips, boolean, TRUE or FALSE Specifies whether the tips with error messages should have a "close" button or not Default is TRUE. - disable_upload_validation, boolean, TRUE or FALSE Useful for disabling all client-side processing of file upload controls, so that custom plugins may be used for it (like, for instance, {@link http://blueimp.github.io/jQuery-File-Upload/basic.html this one}) Default is FALSE. - on_ready, JavaScript function to be executed when the form is loaded. Useful for getting a reference to the Zebra_Form object after everything is loaded.
$form->clientside_validation(array(
// where $form is a global variable and 'id' is the form's id
'on_ready': 'function() { $form = $("#id").data('Zebra_Form'); }',
));
- scroll_to_error, boolean, TRUE or FALSESpecifies whether the browser window should be scrolled to the error message or not. Default is TRUE. - tips_position, string, left, right or center Specifies where the error message tip should be positioned relative to the control. Default is left. - validate_on_the_fly, boolean, TRUE or FALSE Specifies whether values should be validated as soon as the user leaves a field; if set to TRUE and the validation of the control fails, the error message will be shown right away Default is FALSE. - validate_all, boolean, TRUE or FALSE Specifies whether upon submitting the form, should all error messages be shown at once if there are any errors Default is FALSE. @return void |
| return | void | |
recommended usage is:
call session_start() somewhere in your code but before outputting anything to the browser
session_start();
include the Zebra_Form
require 'path/to/Zebra_Form.php';
instantiate the class
protection against CSRF attack will be automatically enabled
but will be less secure if a session is not started (as it will
rely on cookies)
$form = new Zebra_Form('my_form');
| public csrf ( string $csrf_storage_method = 'auto', integer $csrf_token_lifetime, array $csrf_cookie_config = ['path' => '/', 'domain' => '', 'secure' => false, 'httponly' => true] ) : void | ||
| $csrf_storage_method | string | (Optional) Sets whether the CSRF token should be stored in a cookie, in
a session variable, or let the script to automatically decide and use
sessions if available or a cookie otherwise.
Possible values are "auto", "cookie", "session" or boolean FALSE.
If value is "auto", the script will decide automatically on what to use:
if a session is already started then the CSRF token will be stored in a
session variable, or, if a session is not started, the CSRF token will be
stored in a cookie with the parameters as specified by the
csrf_cookie_config argument (read below).
If value is "cookie" the CSRF token will be stored in a cookie with the
parameters as specified by the csrf_cookie_config argument (read
below).
If value is "session" the CSRF token will be stored in a session variable
and thus a session must be started before instantiating the library.
If value is boolean FALSE (not recommended), protection against CSRF
attack will be disabled.
The stored value will be compared, upon for submission, with the value
stored in the associated hidden field, and if the two values do not match
the form will not validate.
Default is "auto".
@param integer $csrf_token_lifetime (Optional) The number of seconds after which the CSRF token is to be
considered as expired.
If set to "0" the tokens will expire at the end of the session (when the
browser closes or session expires).
Note that if csrf_storage_method is set to "session" this value cannot
be higher than the session's life time as, if idle, the session will time
out regardless of this value!
Default is 0.
@param array $csrf_cookie_config (Optional) An associative array containing the properties to be used when
setting the cookie with the CSRF token (if csrf_storage_method is
set to "cookie").
The properties that can be set are "path", "domain", "secure" and "httponly".
where:
- path - the path on the server in which the cookie will
be available on. If set to "/", the cookie will
be available within the entire domain. If set to
'/foo/', the cookie will only be available within
the /foo/ directory and all subdirectories such
as /foo/bar/ of domain. Default is "/" - domain - The domain that the cookie will be available on. To make the cookie available on all subdomains of example.com, domain should be set to to ".example.com". The . (dot) is not required but makes it compatible with more browsers. Setting it to "www.example.com" will make the cookie available only in the www subdomain. - secure - Indicates whether cookie information should only be transmitted over a HTTPS connection. Default is FALSE. - httponly - When set to TRUE the cookie will be made accessible only through the HTTP protocol. This means that the cookie won't be accessible by scripting languages, such as JavaScript. It has been suggested that this setting can effectively help to reduce identity theft through XSS attacks (although it is not supported by all browsers), but that claim is often disputed. Available only in PHP 5.2.0+ Default is FALSE Available only for PHP 5.2.0+ and will be ignored if not available. Not all properties must be set - for the properties that are not set, the default values will be used instead. @since 2.8.4 @return void |
| $csrf_token_lifetime | integer | |
| $csrf_cookie_config | array | |
| return | void | |
| public render ( string $template = '', boolean $return = false, array $variables = '' ) : mixed | ||
| $template | string | |
| $return | boolean | (Optional) If set to TRUE, the output will be returned instead of being printed to the screen. Default is FALSE. @param array $variables (Optional) An associative array in the form of "variable_name" => "value" representing variable names and their associated values, to be made available in custom template files. This represents a quicker alternative for assigning many variables at once instead of calling the {@link assign()} method for each variable. @return mixed Returns or displays the rendered form. |
| $variables | array | |
| return | mixed | |
create a new form
$form = new Zebra_Form('my_form');
display all error messages of error blocks
$form->show_all_error_messages(true);
| public show_all_error_messages ( boolean $value = false ) : void | ||
| $value | boolean | Setting this argument to TRUE will display all error messages of an error block, while setting it to FALSE will display one error message at a time. Default is FALSE. @return void |
| return | void | |
| public validate_control ( string $control ) : boolean | ||
| $control | string | |
| return | boolean | Returns TRUE if every rule was obeyed, FALSE if not. |
| public array $file_upload | ||
| return | array | |
$form->file_upload_permissions = '0777';
The permissions are set using PHP's {@link http://php.net/manual/en/function.chmod.php chmod} function which may
or may not be available or be disabled on your environment. If so, this action will fail silently (no errors or
notices will be shown by the library).
Better to leave this setting as it is.
If you know what you are doing, here is how you can calculate the permission levels:
- 400 Owner Read
- 200 Owner Write
- 100 Owner Execute
- 40 Group Read
- 20 Group Write
- 10 Group Execute
- 4 Global Read
- 2 Global Write
- 1 Global Execute
Default is '0755' | public string $file_upload_permissions | ||
| return | string | |