One of Fakoli's most powerful features for Rapid Application Development is the AutoForm class. This class provides the ability to automatically generate web forms based on your data model classes. The forms generated in this way are automatically validated at both the client and server side, and can be extended and customised in a number of ways. AutoForm renders each of the data model fields according to its type, validates the data entry, and saves the data back to the database. The example below shows how a web form can be constructed:
$task_id = checkNumeric($_GET['task_id']); $task = new Task($task_id); $form = new AutoForm($task); $script .= $form->writeScript(); $form->drawForm();
This example will display a web form as follows:
Handling the submission of the form is also a simple task for your code. With the AutoForm working in its default mode as shown above, we would simply expand out the code sample above as follows:
$task_id = checkNumeric($_GET['task_id']); $task = new Task($task_id); $form = new AutoForm($task); if ($method == "POST") { if ($form->save()) { redirect("success.php"); } } $script .= $form->writeScript(); $form->drawForm();
The save() method on the AutoForm object handles all the work of persisting the updated object to the database, and returns true if there were no errors. If an error occurred (such as a server-side validation exception on the form data) then this error gets displayed as part of the form output for display to the user. We will discuss the AutoForm's validation features below.
This form gets us 80% of the way to a finished project. For the final 20%, we will employ AutoForm customization options.
Fakoli field renderers provide handling of the data model's data types. Some field renderers, such as the DateFieldRenderer and the PasswordFieldRenderer, are called by default when the data model specifies a field as being of type "Date" or "Password", respectively. A list of these field renderers is shown in the table in Chapter 1. Other field renderers, such as the SelectFieldRenderer, which renders a list in a drop down, can be set in the calling script to override the default. Fakoli provides the following additional field renderers:
Field Renderer | Use for Database Types | AutoForm handles as |
---|---|---|
Checklist | VARCHAR, TEXT | Checklist of options (an array) defined in the script or an include file, such as the data model. The user can select more than one. Data is stored as comma-delimited text. |
Cross Reference Select | VARCHAR, TEXT | Checklist of options retrieved from a specified table. The user can select more than one. Data is stored as comma-delimited text. |
File Upload | VARCHAR, TEXT | Input field with Browse button. The user can input a path or browse for the file. |
Radio Button | INTEGER, TINYINT, VARCHAR | Radio button list of options of which the user can select at most one. |
Rating | INTEGER, TINYINT, VARCHAR | Horizontally-aligned radio buttons with starting and ending labels to indicate low and high. User can select one. |
Related Image Select | VARCHAR, TEXT | Drop-down list of images retrieved from a specified table. |
Related Item Radio Button | INTEGER, TINYINT | Radio-button list of options retrieved from a specified table. |
Related Item Select | INTEGER, TINYINT | Drop-down list of options retrieved from a specified table. |
Select | INTEGER, TINYINT, VARCHAR | Drop-down list of options provided to the renderer; an array declared in the calling script or include file. |
Select View Source | INTEGER, TINYINT, VARCHAR | Drop-down list of options provided to the renderer with a button to the right of the drop-down that enables the user to view the selected item through a popup window. |
Tree Select | INTEGER, TINYINT | Tree control of options provided by the calling script. The tree can be set to single or multiselect. |
In our previous form project_id is rendered as a numeric input field but we would prefer to display a drop down listing the existing project names retrieved from the database. AutoForm enables customization of the form with several alternative field renderers. For the project_id field, we will set the form to render the project_id field using the RelatedItemSelectFieldRenderer as follows:
$projectRenderer = new RelatedItemSelectFieldRenderer($form, "project_id", "Project", Project, "ORDER BY project_name", "project_name", "project_id");
The above statement sets the form to render the field project_id with the project name fields retrieved from the Project data model object, ordered by the name field. The revised form display is shown below:
In addition to these optional Field Renderers, Fakoli's AutoForm class provides a set of variables and methods for customizing a web form. A few of the most commonly used features are described below:
Suppose in our Task example, we wish to make the following changes:
We would add the following lines of code to our call script:
$form->alias("due_date", "Project Due Date"); $form->hide("status"); $form->submitLabel = "Save"; echo $form->writeScript();
The call to writeScript() above outputs any JavaScript needed for the display of the form and its fields. This script could also be output from a template file that also handles including JavaScript and css files and any modules you wish to include on your page (for instance, if you are using the Fakoli CMS, you would append this output to the $script variable).
To render the description field as an HTML editor, we change the fields array in the task data model as follows:
"description" => HTML,
The result is shown below:
The AutoForm class also handles field validation prior to saving. The most common type of validation is whether a field is required, meaning the user enters a value. If in the above example, we wanted to make the fields "project_id" and "title" required, we would specify the following in the calling script:
$form->required("project_id", "title");
The resulting web form is shown below:
If the user clicks Save without entering a value in either required field, a popup message is displayed and the form will not save:
The AutoForm validation engine performs validation both at the client side using JavaScript, and at the server side. This ensures that having JavaScript disabled on the browser does not sidestep the form validation. In addition to the required() method AutoForm provides the following validation methods:
Additionally some data types (such as Date and Time) will automatically register validators with the AutoForm to ensure that they are submitting valid data. If you come across a situation that requires special treatment it is also possible to add your own custom Validator objects to the AutoForm's validation pipeline. We will discuss this in the advanced topics section later in this tutorial.
The code we've written so far displays the form properly but we need to add a few more lines to call AutoForm's save function. The following code specifies that we want to save using "POST" and if save is successful, redirect to the task list page. This code should appear just above the call to writeScript().
if ($method == "POST") { if ($form->save()) { redirect("task_list.php"); } }
Data that we have saved to the database must also be retrievable into the form. The task_list.php page would list all the tasks with a link to the task_form.php page, sending the task_id to the page which might be done with an HTML "a" tag as follows:
{$task->title}
When the user clicks on a link, the task form must retrieve the data from the existing task record. To do this, we add call the DataItem::load() function to load the task_id passed into the script:
$task_id = checkNumeric($_GET['task_id']); $task = new Task(); if($task_id) $task->load($task_id);