MattLowden.com

Download this script

PHP / Form Builder / Documentation

Contents

1. 1. Installation & getting started
   1. 1.1. Basic field
   2. 1.2. Configuring a form
   3. 1.3. Handling forms
2. 2. Examples
   1. 2.1. Simple comment form
3. 3. Basic field types & configuration
   1. 3.1. Text
   2. 3.2. File
   3. 3.3. Select
   4. 3.4. Text box
   5. 3.5. Checkboxes
   6. 3.6. Password
   7. 3.7. Date & time
   8. 3.8. Hidden
   9. 3.8. Radio buttons
4. 4. Validation types & configuration
   1. 4.1. Length
   2. 4.2. Minimum length
   3. 4.3. Maximum length
   4. 4.4. Instance
   5. 4.5. Integer
   6. 4.6. URI
   7. 4.7. Email
   8. 4.8. File
5. 5. Public methods
   1. 5.1. Form::__construct()
   2. 5.2. Form::is_submitted()
   3. 5.3. Form::get_result()
   4. 5.4. Form::get_field_list()
   5. 5.5. Form::get_field_value()
   6. 5.6. Form::get_field()
   7. 5.7. Form::create_form()

1. Installation & getting started

Using the form creator couldn't be easier. The forms you create can be as simple or as complex as you wish and can be customized depending on how comfortable you are with PHP, HTML and CSS. If you want to keep things really simple then you can use one of the pre-built configuration to drop straight into your site.

The form is configured using two arrays. The first array is $form_structure, which defines the fields that will be in the form, and the second is $form_settings, which is responsible for how the form is set up.

1.1. Basic field

$form_structure = array(
  'user_name' => array(
    'label' => 'Username',
    'type' => 'text',
    'data' => 'field data'
    'tooltip' => 'Please choose a username',
    'validation' => array(
      'length' => array(2, 64)
    )
  )
);

In the above example we are defining a single field, for the user to enter a username. The first index of the $form_structure array is 'user_name'. This will be the 'name' and 'id' of the form element. Each form element has it's own array of attributes:

label

This is the 'field name' that the user will see. This field is required.

type

The type of field to be created. See below for a full list. This field is not required.

tooltip

A short paragraph of text to aid the user in completing the field. This field is not required.

data

If you want to define a value for the field, enter it here. This value will always be overwritten by the form value upon submission.

validation

This is an array of validation rules. In the example a string between the length of 2 and 64 characters must be entered. You can have as many of few validation rules as you wish, for each field. The key is the rule and the value (array) contains the parameters, if any. This field is not required.

1.2. Configuring a form

$form_settings = array(
  'upload_path' => 'tpl/uploads/',
  'attributes' => array(
    'enctype' => 'multipart/form-data',
    'method' => 'post',
    'action' => '/path/to/page'
  ),
  'submit' => array(
    'class' => 'input-submit',
    'value' => 'Submit',
    'type' => 'submit'
  )
);

The above array contains the default values for the form. You only need to define this array if you want to change this default setup. The following attributes are allowed:

upload_path

This is the default destination for files uploaded by the form.

attributes

This is an array of HTML attributes to be applied to the form. The following attributes are supported.

submit

This is an array of HTML attributes to be applied to the form's submit button. The following attributes are supported.

1.4. Handling form input

if($form->get_result()){
  $fields = $form->get_field_list();
  print '<h3>You successfully filled in the form</h3><dl>';
  foreach($fields as $field){
    print '<dt>'.$field['label'].'</dt><dd>'.$field['data'].'</dd>';
  }
  print '</dl>';
}

The above block of code checks to see whether the form has been successfully submitted and if so get the list of fields and loops through them, printing their values.

2. Examples

2.1. Simple comment form

The following example shows how to create a basic comment form, that requires a name between 2 and 64, a valid email address and a comment of at least 8 characters. The email field also has a tooltip reminding the user to enter a valid address as a confirmation email will be sent, upon completion. This form can be seen in action on the examples page.

$form_structure = array(
  'user_name' => array(
    'label' => 'Username',
    'validation' => array(
      'length' => array(2, 64)
    )
  ),
  'user_email' => array(
    'label' => 'Email Address',
    'tooltip' => 'Be sure this is a valid email address as you'.
    				' will be sent a confirmation email!',
    'validation' => array(
      'email' => array()
    )
  ),
  'user_comment' => array(
    'label' => 'Comment',
    'type' => 'textarea_small',
    'validation' => array(
      'length_min' => array(8)
    )
  )
);

$form = new Form($form_structure, $form_settings);
print '<h3>Example form</h3>';
print $form->create_form();

if($form->get_result()){
	$fields = $form->get_field_list();
	print '>h3>You successfully filled in the form>/h3>>dl>';
	foreach($fields as $field){
		print '>dt>'.$field['label'].'>/dt>>dd>'.$field['data'].'>/dd>';
	}
	print '>/dl>';
}

if($form->get_result()){
  $fields = $form->get_field_list();
  print '<h3>You successfully filled in the form</h3><dl>';
  foreach($fields as $field){
    print '<dt>'.$field['label'].'</dt><dd>'.$field['data'].'</dd>';
  }
  print '</dl>';
}

3. Basic field types & configuration

The following is a list of all field types supported in the latest version of the Form Builder. All fields can have a validation and tooltip setting, both of which are detailed in other sections of the documentation.

3.1. Text

This is the default field type. A standard input field. The below code is an example of how this type of field would be defined.

$form_structure = array(
  'user_name' => array(
    'label' => 'Username'
  )
);

3.2. File

This field shows an file input box. Only if the form is successfully submitted will the file be uploaded. The following is an example of how a file field would be defined. You can also define an additional field, file_remove_link; this field adds a link to the input field allowing the file to be deleted. Form Builder does not remove the file itself, you must provide a URI to a function that will remove the file.

$form_structure = array(
  'downloads' => array(
    'label' => 'Download',
    'type' => 'file'
    'remove_file_link' => 'remove.php?file=path/to/file.ext'
  )
);

3.3. Text box

This field type displays a textarea element.

$form_structure = array(
  'article' => array(
    'label' => 'Article',
    'type' => 'textarea'
  )
);

3.4. Checkboxes

There are two ways to display checkbox elements. You can either display them in a list, or as an individual box. The below example shows an individual box.

$form_structure = array(
  'published' => array(
    'label' => 'Published',
    'type' => 'checkbox'
  )
);

The below example shows multiple boxes.

$form_structure = array(
  'password' => array(
    'label' => 'Category',
    'type' => 'checkbox_multiple',
    'options' => array(
      'business' => 'Business',
      'social_media' => 'Social Media',
      'mobile' => 'Mobile',
      'web_video' => 'Web Video',
      'entertainment' => 'Entertainment'
    )
  )
);

3.5. Password

The password type displays a field that looks identical to the default text type, however text entered is not displayed.

$form_structure = array(
  'user_name' => array(
    'label' => 'Password',
    'type' => 'password'
  )
);

3.6. Date & time

The Date & time field displays combo boxes for you to define a day, month, year, hours and minutes.

$form_structure = array(
  'user_name' => array(
    'label' => 'Date submitted',
    'type' => 'datetime'
  )
);

3.7. Hidden

The hidden type submits a value that is not displayed in the form. This field must be given a value to be of any use.

$form_structure = array(
  'user_name' => array(
    'type' => 'hidden',
    'value' => 'hidden value'
  )
);

3.8. Radio buttons

Raidio buttons display a list of options, similar to the checkbox list, however, the user can only select one value.

$form_structure = array(
  'password' => array(
    'label' => 'Category',
    'type' => 'radio_multiple',
    'options' => array(
      'business' => 'Business',
      'social_media' => 'Social Media',
      'mobile' => 'Mobile',
      'web_video' => 'Web Video',
      'entertainment' => 'Entertainment'
    )
  )
);

3.9. Combo boxes

Combo boxes have two types. The user can be given the option to select one or multiple options in a combo box. The following example shows a typical single select combo box. The options_default setting is not required and merely acts as a prompt for the user to select a value.

$form_structure = array(
  'password' => array(
    'label' => 'Category',
    'type' => 'select',
    'options_default' => 'Please choose a category...'
    'options' => array(
      'business' => 'Business',
      'social_media' => 'Social Media',
      'mobile' => 'Mobile',
      'web_video' => 'Web Video',
      'entertainment' => 'Entertainment'
    )
  )
);

The following is an example of a multi select combo box. The options_default setting is not used as it is irrelevant.

$form_structure = array(
  'password' => array(
    'label' => 'Categories',
    'type' => 'select_multiple',
    'options' => array(
      'business' => 'Business',
      'social_media' => 'Social Media',
      'mobile' => 'Mobile',
      'web_video' => 'Web Video',
      'entertainment' => 'Entertainment'
    )
  )
);

4. Validation types & configuration

This section covers all validation types supported by the most recent version of Form Builder and how to use them with your form fields.

4.1. Length

The length rule checks to see whether the value length is between two numbers. For instance, the following code would check to see if the field value was between 2 and 64 characters, otherwise a validation error would be returned.

$form_structure = array(
  'name' => array(
    'label' => 'Username',
    'validation' => array(
    	'length' => array(2, 64)
    )
  )
);

4.2. Minimum length

The min length rule checks to see whether the value length is as least the specified number of characters. For instance the following code will check to see if the field value was longer than 8 characters otherwise a validation error would be returned.

$form_structure = array(
  'name' => array(
    'label' => 'Username',
    'validation' => array(
    	'min_length' => array(8)
    )
  )
);

4.3. Maximum length

The max length rule checks to see whether the value length is as not longer than the specified number of characters. For instance the following code will check to see if the field value was shorter than 255 characters otherwise a validation error would be returned.

$form_structure = array(
  'name' => array(
    'label' => 'Username',
    'validation' => array(
    	'max_length' => array(255)
    )
  )
);

4.4. Instance

The instance check ensures that at least some value us entered by the user. No parameters are required.

$form_structure = array(
  'name' => array(
    'label' => 'Username',
    'validation' => array(
    	'instance' => array()
    )
  )
);

4.5. Integer

The integer check to make sure the given value is a number.

$form_structure = array(
  'number' => array(
    'label' => 'Pick a number',
    'validation' => array(
    	'integer' => array()
    )
  )
);

4.6. URI

The url rule checks to see whether the given value is a valid URI.

$form_structure = array(
  'url' => array(
    'label' => 'Link',
    'validation' => array(
    	'url' => array()
    )
  )
);

4.7. Email

The email rule checks to see whether the given value is a valid email address.

$form_structure = array(
  'email' => array(
    'label' => 'Email',
    'validation' => array(
    	'email' => array()
    )
  )
);

4.8. File format

The file format rule checks to see whether the given value is an accepted file type. The below rule would check to see whether file file was of the given formats; jpeg, jpg, gif.

$form_structure = array(
  'file' => array(
    'label' => 'File',
    'validation' => array(
    	'file_format' => array('jpeg', 'jpg', 'gif')
    )
  )
);

5. Public methods

5.1. Form::__construct()

5.2. Form::is_submitted()

The Form::is_submitted() function is used to detect whether the form has been submitted (but not necessarily validated).

5.3. Form::get_result()

The Form::get_result() function is used to detect whether the form has been submitted and all validation rules have been passed.

5.4. Form::get_field_list()

The Form::get_field_list() function returns an array of all field names in the form. This can then be used in conjunction with Form::get_field() and Form::get_field_value() to use data from the form.

5.5. Form::get_field_value()

The Form::get_field_value() function returns the value of the field specified in the $form_structure array.

5.6. Form::get_field()

The Form::get_field() function returns the entire field, with all attributes, defined in the $form_structure array.

5.7. Form::create_form()

The Form::create_form() function creates and outputs the HTML for the form, ready to be printed to the document. It also handles the processing of the form.