Let's take a look at a working piece of code using the API:
<?php
- function test_page() {
+ function test_form() {
// Access log settings:
$options = array('1' => t('Enabled'), '0' => t('Disabled'));
$form['access'] = array(
@@ -101,19 +101,26 @@
);
$form['hidden'] = array('#type' => 'value', '#value' => 'is_it_here');
$form['submit'] = array('#type' => 'submit', '#value' => t('Save'));
- $output = drupal_get_form('test_page', $form);
- return $output;
+ return $form;
+ }
+
+function test_page() {
+ return drupal_get_form('test_form');
}
-
+
?>
This example demonstrates how form elements can be built in a hierarchical fashion by expanding and layering the form array.
+This example demonstrates how form elements can be built in a hierarchical fashion by expanding and layering the form array. There are two functions involved - the function that builds the form, and another that displays the form using drupal_get_form().
Notice that the first layer is made up of two form groups, 'access', and 'details', and that inside each of these groups, one layer down, are some individual form elements. Order of construction is important here, as the form building code will default to the constructed order of the $form array when it builds the form (this can be overridden, and will be discussed later in the custom theming section).
For form groups, the '#type' parameter is set to 'fieldset', and notice how the 'details' form group is made into a collapsed form group with the addition of a few attributes.
Once all groups/elements have been built into the master $form array, it's passed to drupal_get_form. drupal_get_form takes three args: the first is a string representing the name of the form itself (called the form ID, which is usually just the name of the function), the second is the form array to render, and the third is an optional callback argument (which will be discussed later).
The drupal_get_form function is the "key" function in the Forms API. It does the following:
All groups/elements are been built into the master $form array by the builder function.
The drupal_get_form function is the "key" function in the Forms API. Note that in its basic usage, it takes just one argument, a string which
+is both the form ID and also the name of the function that builds the $form array. drupal_get_form can take optional additional arguments, which will be simply passed on to the $form builder function.
drupal_get_form does the following:
$form from the builder function$form['name'] items into actual form elementsexample:
For our above form, we could create a custom theming function as follows:
<?php
- function theme_test_page($form) {
+ function theme_test_form($form) {
$output = '';
- $output .= form_render($form['name']);
+ $output .= drupal_render($form['name']);
$output .= '<div class="foo">';
- $output .= form_render($form['access']);
+ $output .= drupal_render($form['access']);
$output .= '<div class="bar">';
- $output .= form_render($form['details']);
+ $output .= drupal_render($form['details']);
$output .= '</div></div>';
- $output .= form_render($form);
+ $output .= drupal_render($form);
return $output;
}
?> form_render functionform_render and pass it an array of elements (as in a fieldset), it will render all the elements in the passed array, in the order in which they were built in the form array.form_render for any element in the place where you would like it to be rendered. In the above example, this was done with $form['name'].form_render is called for the entire form array at the very end of the theming function, but it will only render the remaining unrendered element, which in this case is the submit button. calling form_render($form) is a common way to end a theming function, as it will then render any submit buttons and/or hidden fields that have been declared in the form in a single call.drupal_render functiondrupal_render and pass it an array of elements (as in a fieldset), it will render all the elements in the passed array, in the order in which they were built in the form array.drupal_render for any element in the place where you would like it to be rendered. In the above example, this was done with $form['name'].drupal_render is called for the entire form array at the very end of the theming function, but it will only render the remaining unrendered element, which in this case is the submit button. calling drupal_render($form) is a common way to end a theming function, as it will then render any submit buttons and/or hidden fields that have been declared in the form in a single call.The form API has general form validation which it performs on all submitted forms. If there is additional validation you wish to perform on a submitted form, you can create a validation function. the name of the validation function is the form ID with _validate appended to it. the function has two args: $form_id and $form_values. $form_id is the form ID of the passed form, and $form_values are the form values which you may perform validation on.
Here's an example validation function for our example code:
<?php
- function test_page_validate($form_id, $form_values) {
+ function test_form_validate($form_id, $form_values) {
if ($form_values['name'] == '') {
form_set_error('', t('You must select a name for this group of settings.'));
}
@@ -191,7 +198,7 @@
The preferred method of submitting forms with the API is through the use of a form submit function. This has the same naming convention and arguments as the validation function, except _submit is appended instead. Any forms which are submitted from a button of type => 'submit' will be passed to their corresponding submit function if it is available. This method is more secure than grabbing $_POST['edit'] and using a switch statement.
example:
<?php
- function test_page_submit($form_id, $form_values) {
+ function test_form_submit($form_id, $form_values) {
db_query("INSERT INTO {table} (name, log, hidden) VALUES ('%s', %d, '%s')", $form_values['name'], $form_values['access']['log'], $form_values['hidden']);
drupal_set_message(t('Your form has been saved.'));
}
?>
@@ -211,11 +218,8 @@
-Returning Forms
-Generally speaking, you will return a form with the drupal_get_form function.
-In some cases, code may be written in such a way that form elements themselves (and not a fully themed form) need to be returned to a calling function. This is the case with many Drupal core hooks. in this case, simply return the constructed $form array, and let the calling code handle the form rendering.
Understanding the Flow
-A difficult concept with Forms API compared to the previous Drupal method of doing things is that the drupal_get_form() function handles both presenting and responding to the form. What this means is that the $form array you construct in your function will be built first when the form is presented, and again when the form is submitted. In the previous Drupal forms API, the check for 'submit' was done before calling any of the form_* functions, because those directly created the output.
+A difficult concept with Forms API compared to the previous (Drupal 4.6) method of doing things is that the drupal_get_form() function handles both presenting and responding to the form. What this means is that the $form array you construct in your function will be built first when the form is presented, and again when the form is submitted. In the previous Drupal forms API, the check for 'submit' was done before calling any of the form_* functions, because those directly created the output.
The practical upshot to this is that many developers immediately find themselves asking the question of "where does my data get stored?". The answer is simply that it doesn't. You put your $form data together, perhaps loading your object from the database and filling in #default_values, the form builder then checks this against what was posted. What you gain from this, however, is that the FormsAPI can deal with your data securely. Faking a POST is much harder since it won't let values that weren't actually on the form come through to the $form_values in your submit function, and in your 'select' types, it will check to ensure that the value actually existed in the select and reject the form if it was not.