Drupal Formsby Blake Lucchesi

FormAPI Intro

Forms are defined by a single php array. Each key of the array is a form element.

Drupal builds and generates the html output for the form using this FormAPI.

Why a FormAPI?

Provide a standardized means to create, process, and theme forms.

Provides safe form error handling and validation.

Allow other code (modules) to modify forms.

Building a form

Step 1: Define a new function that builds and returns a form array.

Step 2 (optional): Define a function that validates the form values.

Step 3: Define a function that process the form values on submit.

Step 4: Call the form function using drupal_get_form() to present the form on a page.

Basic Form

WARNING

Be careful to avoid naming your functions with reserved names:

hook_form (Defines form array for custom defined node types add/edit form.)

hook_forms (Maps form_ids to builder functions.)

Validation

Values stored in $form_state[‘values’].

form_set_error(‘element’, ‘Message’);

Submit

Values stored in $form_state[‘values’].

Remember to use check_plain() to clean values before sending emails or printing to screen.

Set $form_state[‘redirect’] = ‘path/to/redirect’; and after the form is submitted the user is redirected to that path.

#validate

Defines a single function or an array of functions to be called during the form validation process.

Can be attached to entire forms or individual elements.

Use form_set_error() to prevent submit execution and present an error message to the user.

#submit

Defines a single function or an array of functions to be called during the form validation process.

Used to process the data that is submitted: Insert into database, send email, etc. etc.

$form_state

Provides persistent data storage throughout form processing.

[‘values’] is the array where form values are pushed after submit button is clicked.

[‘storage’] is the array that should be used to store data that persists throughout the entire form build/validate/process cycle.

In order to exit multi-step loop, it is necessary to unset($form_state[‘storage’]);

Multi-step

Form is rebuilt each time it is displayed. Acts like a state machine.

Use $form_state variable to build each step of the form array, and process the data through each step.

Example...

#ahah

The #ahah element is a utility, for adding Ajax/javascript driven incremental page reloading, without needing to write any Javascript.

Actions can be triggered on click, change, etc.

Actions fire an http request to a url (or drupal path)

Data/output is then presented back on the already loaded page.

Example...

hook_form_alter()

Manipulate other module’s forms.

Example...

Extra Reading...Online: Drupal API Docs (FormAPI Quickstart)

Online: Drupal API Docs (FormAPI Reference)

Online: Multistep Forms (5.x but concept still applies)

Online: Drupal Forms 5 to 6 (Drupal.org handbook)

Online: Drupal Forms 5.x to 6.x (Lullabot article)

Online: Drupal AHAH in Core (Lullabot article)

Online: Theming the Register Form

Presentation: Drupal Form API (5.x)

Book: Pro Drupal Development (Apress)

Book: Learning Drupal 6 Module Development (Packt)

Thank You

Thank you for joining me at DrupalCampLA!