Introduction
PHP class used to setup plugin fields, validatios and create forms.
Is mostly based on Simple Form Validation, another class implemented in PrivateContent.
Located in classes folder.
PrivateContent
API Documentation
Form Framework Class
Properties
| (array) $fields | associative array containing registered fields. Filled on class instantiation. To know more, check this filter |
|---|---|
| (bool) $mail_is_required | flag to know if e-mail field is required. Filled on class instantiation |
| (string) $errors | static resource containing HTML code with validation errors |
| (array) $form_data | associative array containing form's data (field_name => value). Filled o forms handling |
__construct()
Instantiating the class $fields and $mail_is_required properties are filled.
Normally don't require any additional parameter, but as utility, there's an array that can be used to manipulate fields.
Parameters
(array) associative array that may contain two keys
| key | description |
|---|---|
| (bool) use_custom_cat_name | whether to use custom category name |
| (bool) strip_no_reg_cats | whether to remove categories not allowed on registration |
Example
<?php
// initialize the class using custom category field name
inlude_once(PC_DIR .'/classes/pc_form_framework.php');
$f_fw = new pc_form(array('use_custom_cat_name' => true));
?>
get_field()
Method used to get field's data. New fields can be added using the pc_form_fields_filter hook.
Usage
get_field($field_name)
Parameters
| (string) | field key to get |
|---|
Return Values
| (array) $field_name | associative array (field_data => value) |
|---|
Example
<?php
// get 'username' field data
$f_fw = new pc_form();
$data = $f_fw->get_field('surname');
?>
get_field_name()
Method used to get field's label
Usage
get_field_name($field_name)
Parameters
| (string) $field_name | field key to get |
|---|
Return Values
| (string) | field label |
|---|
Example
<?php
// get 'categories' field label
$f_fw = new pc_form();
$data = $f_fw->get_field_name('categories');
?>
form_code()
Method used to create forms structure. Returns fields split in an UL list.
Doesn't add FORM tag nor buttons.
Usage
form_code($fields, $custom_fields = false, $user_id = false)
Parameters
| (array) $fields | associative array containing included and required fields. Structure is array('included' => array(field_keys), 'required' => array(field_keys)) |
|---|---|
| (string) $custom_fields | custom HTML code to add custom fields to the form. Should be LI elements |
| (int) $user_id | PrivateContent user ID. If specified, populates fields with its data |
Return Values
| (string) | form fields UL list |
|---|
Example
<?php
// print form with username and e-mail fields and populate with data from user #5
$f_fw = new pc_form();
$fields = array(
'included' => array('username', 'email'),
'required' => array('username')
);
$code = $f_fw->form_code($fields, false, 5);
echo '
';
?>
get_field_options()
Method used to get options array from a select or checkbox field
Usage
get_field_options($opts)
Parameters
| (string) $opts | string containing options, comma split |
|---|
Return Values
| (array) | field options |
|---|
Example
<?php
// get options for a 'test' field registered in plugin
$f_fw = new pc_form();
$field_data = $f_fw->get_field('test');
$options = $f_fw->get_field_options($field_data['opt']);
?>
get_fields_data()
Method used to aggregate field values submitted via form or through url parameter.
Given an indexes array, scan $_GET and $_POST globals to store data. If an index isn't found, store (bool) false.
Usage
get_fields_data($fields, $stripslashes = true)
Parameters
| (array) $fields | field indexes to fetch |
|---|---|
| (bool) $stripslashes | whether to use stripslash() function on fetched data (by default wordpress uses addslashes() on submitted data) |
Return Values
| (array) | associative array containing fetched data (index => val). If field contains an array, VAL will be an array. |
|---|
Example
<?php
// get options for a 'test' field registered in plugin
$f_fw = new pc_form();
$fields = array('f1', 'f2', 'f3', 'f4', 'f5');
$data = $f_fw->get_fields_data($fields);
?>
generate_validator()
Method used to automatically setup validation indexes for Simple Form Validator
Usage
generate_validator($form_structure, $custom_valid = array())
Parameters
| (array) $form_structure | multidimensional array containing included and required fields array('include' => array, 'require' => array) |
|---|---|
| (array) $stripslashes | multidimensional array containing additional validation indexes in case of extra fields. Must comply Simple Form Validator structure |
Return Values
| (array) | validator indexes to be used in Simple Form Validator |
|---|
validate_form()
Method used to validate submitted data, using Simple Form Validator
Usage
validate_form($indexes, $custom_errors = array(), $user_id = false, $specific_checks = true)
Parameters
| (array) $indexes | validation structure, previously built with generate_validator() method |
|---|---|
| (array) $custom_errors | array containing html strings with custom errors |
| (int) $user_id | utility value to perform database checks - requires a PrivateContent user ID |
| (bool) $specific_checks | whether to perform categories and username unicity checks. Useful to avoid double checks on frontend insert/update |
Return Values
| (bool) | true if form is valid, false otherwise. Errors and data must be retrieved in related object properties. |
|---|
Example
<?php
// validate submitted form containing username and e-mail fields
$f_fw = new pc_form();
$form_structure = array(
'include' => array('username', 'email'),
'require' => array('email') // username is required by default
);
$validation_indexes = $f_fw->generate_validator($form_structure);
if($f_fw->validate_form($validation_indexes)) {
// form ok - get data
$data = $f_fw->form_data;
}
else {
// errors - print them
echo $f_fw->errors;
}
?>
check_psw_strength()
Method used to chek password strength
Usage
check_psw_strength($psw)
Parameters
| (string) $psw | password to match |
|---|
Return Values
| (bool/string) | true if password is ok - otherwise string containing errors |
|---|
honeypot_generator()
Method used to get honeypot, hidden anti-spam system, code. To be used in forms.
Usage
honeypot_generator()
Parameters
no parameters
Return Values
| (string) | code, ready to be used |
|---|
honeypot_validaton()
Method used to validate honeypot, hidden anti-spam system, code.
Usage
honeypot_validaton()
Parameters
no parameters
Return Values
| (bool) | true if is valid, otherwise false |
|---|
