Forms

From phpDrone

DroneForm class from phpDrone is used to handle form in a web page, and by "handle" i mean building the HTML necessary to display the HTML web form, validate the data that was submitted with the form display the errors and handle of what should happen in case of a valid form submission.

The DroneForm class

To illustrate the use of the phpDrone DroneForm class, we will see how to make a simple login form. In order to use the phpDrone form class you have to make an instance of the DroneForm class.

$loginForm = new DroneForm(do_success);

The argument passed here (do_success) is the name of the function that should be called in case the data that is submitted if the form is valid. You can use functions but NOT object methods. The only methods that you can use are static methods. If you want to use a static method as a success, instead of do_success you put a string to your method like this: "MyClass::myStaticMethod". Now, we can use the instance of the DroneForm class to start defining the inputs that are on he form. To do that, we use the method addInput.

$loginForm->addInput("*User","text","username","/.*/");
$loginForm->addInput("*Pass","password","password");

The first argument that the method received is the label of the input. The "*" that you noticed at the beginning of the label text tells to the DroneForm object that this input is mandatory, and will put an error under the input's label in case the form is submitted and the input was left empty. The second argument indicates what kind of input it is. For a complete list of input types, see Input types bellow. The third argument is the name of the input. This name will be used for the "name" and "id" attributes of the "input" tag.

The fourth argument is optional. This one is used to define the regular expression, or the name of the function (same rules as for the success function) that will be used to validate the data that was submitted in this input.

Now that you have defined the inputs, you must get the HTML code for this form that you will use to display the form. To do that, you must call the getHTML() method on the DroneForm object.

$loginForm->getHTML();

You will be able to use this method alongside with the write method of the DroneTemplate class, for example. For more details about the templates, please read the Templates documentation. One example of using the getHTML() method can be this:

$template->write("myLoginForm",$loginForm->getHTML());

Another thing that you should know about the HTML code generated by the getHTML() method is that it contains the HTML code only for the inputs in the form , not also the <form> tag. So, the HTML code for the example above will be:

<label for='username' id='username_label'>
    <span class='mandatoryMarker'>*</span>
    User:
</label>
<input type='text' value=''  name='username' id='username' class='textInput'/>
 
<label for='password' id='password_label'>
    <span class='mandatoryMarker'>*</span>
    Pass:
</label>
<input type='password' value=''  name='password' id='password' class='textInput'/>
 
<input type='hidden' value='' name='droneSubmitTrigger' id='droneSubmitTrigger' class='textInput'/>

All you need to do now is write the "do_success" method which will be called in case the form was submitted and the data was valid. The function will receive an associative array containing the validated submitted data. An example of a success function might look like this:

function do_success($data)
{
    var_dump($data);
}

Note: your do_success method can have any name.

DroneForm methods

In the next section will be enumerated the methods that can be called on a DroneForm class instance, and what they do.

constructor

The constructor of the DroneForm class receives:

on_success

a string representing the name of the function that should be called in case the form is validated successfully. This functions will receive am argument containing an array with the validated submitted form data.

defaults (optional)

an associative array containing data that will be set as default for the form. The only use for this is when the web form is used to edit existing data. SHOULD NOT be used to put default data in inputs. To do that, please see the setDefault() method of the Input class.

method (optional)

states where phpDrone should look for submitted data. Valid values for this argument are: both(default),post,get.

addInput()

This method you already know from the example above and is used to add an input to the form. It receives a maximum of 5 arguments like listed below:

label

the text that will be used as a label for the input. If the label will start with a "*" that input field will be marked as mandatory in the resulting page but also internally for validation purposes.

type

the type of the input. See see Input types bellow for a complete list of types and their description

name

this is the name attribute of the input. It will be the key in the $data associative array that will be passed to the do_success function in case a valid form is submitted

validator (optional)

you can put here either a regular expression or a function name as a string. If a function name is passed, that function will be called, passing to it the $data associative array (an array containing the submitted data, NOT NECESSARILY VALID).This function should validate if $data[name] (where 'name' is the name of the input) is a valid input data, and should return True or False accordingly.

maxLen (optional)

this argument is used if you want to specify a max length of a input data. Doesn't apply for select,radio,checkbox,file and captcha inputs

getHTML()

This method is returning the HTML code for the form inputs. When this method is called, it is checked if the page was called with submitted data. If so, a validation is started for the data, and in case of a validation success the do_success method is called and the form is html code with empty input fields is returned, or if the form is not valid, the form is returned, containing error messages displayed before each input that was not valid. If no data submission is detected, this method will simply return the form HTML code. Note that this method only returns the code for the inputs in the form, not the <form> DOM element too.

getHTMLInputs()

This function is similar in every way to the getHTML() method, except that it return an array containing the HTML code for each input in the field. This is used if you want more flexibility on the placement of the inputs in the form (maybe you want to place something between two inputs).

Input methods

Will continue now to show you the methods that are available for the Input class. To access an input that was added to the form you must access member inputs[] from an instance of a DroneForm class.

For example, let's pretend that we have an instance to a form class called $form and we want to call method setDefault() on the input named username. To do that, we will write the next code sequence:

$form->inputs['username']->setDefault("User");

OK! So let's start enumerating the methods that are, so far, included in the Input class.

setDefault()

This method is used for two things: first, it sets a default value for the input and second, it's used to build the options in inputs like select,radio and checkbox (for further details, read the details for this input types). It receives one argument that represents the value to be used in the input or an array (for select,radio and checkbox types).

setAttribute()

This method allows you to set additional HTML attributes to the input itself. For example, to set an "onclick" event function, some specific "style" characteristics, etc. It receives two arguments:

attribute

the name of the attribute to be set (ex: onclick, onmouseup, style.). You can even set the id for that specific input. The "name" tag though, you can not change.

value

the value to be set to the specific attribute

removeAttribute()

Use this method to remove an attribute from an input (except the 'name' attribute).

allowHTML()

This tells if this input can submit data that contains HTML tags. By default, all the HTML tags are transformed in HTML safe text (
will be stored as &ltl;br />). If this functions is called without any argument, it will return the inputted text without parsing the HTML tags. You can call this function again passing False as an argument, to re-enable the behavior.

Input types

Now let's talk about the types of inputs that you can define. As seen above, the type of the input is set as the second argument of the addInput method.

Text

This type is used to create ordinary text inputs

Password

This type is used to create password inputs

Textarea

This type is used to create textarea inputs

Select

This type is used to create select inputs. The fourth argument for this type of input is not a regular expression, but an array. The array will be used like following: the key of the array element will be the value of the option from within the select and the value of the array for the text of the option of the select.

So for the following code:

$status = array("0"=>"Suspended","1"=>"Active");
$userForm->addInput("Status","select","status");
$userForm->inputs['status']->setDefault($status);

will have the following output:

<label for='status' id='status_label'>
    Status:
</label>
<select  name='status' id='status' class='selectInput'>
    <option class='option_Suspended' value='Suspended' selected='selected'>Suspended</option>            
    <option class='option_Active' value='Active'>Active</option>
</select>
 
<input type='hidden' value='' name='droneSubmitTrigger' id='droneSubmitTrigger' class='textInput'/>

So the validation of this input will consist in checking if the recieved value is one of the keys defined in the array.

File

This type is used to create file inputs. For this input no validation is applied

Radio

This type is used to create radio buttons

Checkbox

This type is used to create checkboxes

Captcha

This is a special type of input. A captcha input is used to check if the entity who submitted the form is a human not a auto-submit script. The input consists in a image containing a 5 character scrambled text and an input. For the form which contains a captcha input to be valid, the text typed in the input must match the text in the image.

All the validations for this input are managed internally by the phpDrone and doesn't involve any action from the programmer. Also, a widget has been added for the image, so that if the image is not readable, the user can click the image to regenerate it.