Drupal Forms API. Part 1 - for Drupal 6

This article is intended for those who are already familiar with writing the simplest modules, and would like to understand the principles of the FAPI ( Drupal Forms API ) "on the fingers." In it, we will examine the basics of the Drupal programming interface for creating forms, and create a small module that returns the entered name using the Drupal Ajax engine, called AHAH. For this simple form, we need FAPI.



Why an article on this topic? In the network, and on Habré in particular, there are several examples of modules with FAPI. For me in the past it was a certain difficulty to understand how forms are created - and such an explanation “on the fingers” would be very useful to me. I can not go back in time - but I can help those who are experiencing such difficulties.



The article corresponds to the 6.x version of Drupal. I planned to cover in parallel the article and version 7 - but the difference in the API is significant, so I will describe the same function for the API version 7 in part 2 of the article.

')

Why use FAPI forms?

Naturally, you can write the form as HTML and simply print it on the page, or attach it to the module as an include file. But if you use FAPI, the following benefits will appear:

1. The form will be able to use the means of validation, the theme of Drupal, its AHAH system (AJAX, starting with version 7 of Drupal).
2. The form can be translated by running through the translation interface through the t () function.
3. The form can be provided for editing by other modules through a hook.
4. And, not least, the form will be formatted according to the general rules of the Drupal forms, which will make it more “native” for its subsequent themes.

Let's create the simplest module

Let's call our module fastcontact . Create a folder / sites / all / modules / fastcontact - this will be the root folder of our module. In it, we create two files - fastcontact.info and fastcontact.module - that will be enough.



In the .info file, enter:

; ""   name = Fast Contact ;     description = Test module for learning FAPI ;   version = "6.x-1.0" ;     core = "6.x" ; ""   project = "fastcontact" ;     package = "Other" ;    datestamp = "1294001844" 

Now, you can go to the code that describes the form.

Forms and elements of FAPI forms

Each form is described as a function. The function returns an array with form elements. Each element of the array corresponds to a form element, has a name, and contains an array of attributes of this element. The pivot table of elements and their attributes is available for review on the Drupal API website.



Create a simple form with one text field.

 function fc_form() { $form = array(); //   'name' $form['name'] = array( //   '#type' => 'textfield', //    '#description' => t(' '), //   '#size' => '25', ); //    'submit' $form['submit'] = array( //   Submit (  ) '#type' => 'submit', //    '#value' => 'Submit', //  AHAH (   6) '#ahah' => array( //   click (  JQuery) 'event' => 'click', // ,      'path' => 'fastcontact/js', //      'wrapper' => 'fc-form', //    ( JQuery) 'method' => 'append', //  JQuery    'effect' => 'fade', //   'progress' => array('type' => 'throbber'), ), ); return $form; } 

This will create a form with a text field and an Ajax submit button (AHAH).

Processing request

Now, we need to create a functional for processing the ANAN request. To do this, you need to create the path specified in the path attribute of the ahah element (in the form we specified the path 'fastcontact / js' ). This is done via hook_menu () .



Drupal uses the menu module even when nothing enters the “menu” as such. But he keeps the paths of pages. Menu items are also created through an array.

 /** *  hook_menu() */ function fastcontact_menu() { //      $items['fastcontact/js'] = array ( // ,   ""  'page callback' => 'fastcontact_ajax', //      'access arguments' => array('access content'), //        'type' => MENU_CALLBACK, ); return $items; } 

We have specified MENU_CALLBACK as the type of the menu item, since we do not want this link to be followed by a link from the site menu (this is the way to process the request).



Our request processing function is not directly related to the work of the forms, so without sophistication, we simply bring it back through the AHAH to show that the module is working.

 /*   */ function fastcontact_ajax() { //     $_POST //         check_plain() $name=check_plain($_POST['name']); //              (  fc-form) $output = '   <i>'.$name.'</i>.'; //         drupal_json(array('status' => TRUE, 'data' => $output)); } 

Form display

Now we just have to assemble the form and do everything necessary for its rendering. First, create a function that will display our form. For this, drupal_get_form () will be used.

 /*   */ function render_fc_form() { //      $out = drupal_get_form('fc_form'); return $out; } 

We could create a block via hook_block () - but not to complicate things, we can simply create a block with an input filter and display the form via php code:

  echo render_fc_form(); 

The expected result of the module

In case of successful operation of the code, the phrase “You have entered a name ...” will appear under the input form, where instead of the ellipsis you will see the name you entered, without reloading the page.