project_settings: Converting a hook_settings implementation (Easy)

Overview

The first form to investigate is the project module's settings form. This is a very straight-forward form conversion which only requires taking existing form_* function calls and converting them into arrays.

Project settings form

Original function

The following is the original project_settings function which generates this form:

Note that lines prefixed with ** indicate a line that will cause problems with Drupal 4.7.

Form conversion

Begin by navigating to administer >> settings >> project. You will receive an error:

Fatal error: Call to undefined function: form_textfield() in \modules\project\project.module on line 119

The error tells the name of the file from which the error is originating: project.module. Copy and paste the contents of this file into the Form Updater module, and it will identify six calls to the old forms API (out of seven lines identified as problematic). Here is the first call as an example:

This creates a textfield with:

• a title of Release Directory
• an internal name of project_release_directory
• a default value containing either the contents of the project_release_directory variable in the Drupal variable table, or an empty string if that does not exist
• a size (or length) of 50 characters
• a maximum length of 255 characters
• a description of "Leave this blank if project maintainers are to create their own release packages. This is useful if releases are generated by an external tool."

In the new API, this translates to:

Notice that the element name is now moved to the name of the array index in $form (in this case, project_release_directory). Also note that each array index is labeled specifically what it means. #title => t('Release Directory') is the form element's title (or text displayed above it). #default_value is its default value, and so on. You are no longer required to memorize what order function arguments go in, or to refer to the API reference to determine this. Attributes can be placed in any order (although it is customary to keep them in the same order throughout), or even removed altogether if they are not required.

Replace the form_textfield call with the code generated by Form Updater. Repeat for each element that Form Updater finds.

hook_settings changes in 4.7

Save project.module at this point and reload the settings page.

Project settings page after replacing form values

While there is no longer an error displayed, something is clearly amiss. Where did the form go? Check the very last highlighted line for the answer:

return $output;

In Drupal 4.6, hook_settings returned an HTML string containing the form output. In Drupal 4.7, hook_settings (as well as hook_form) return the actual $form array instead. Change this line to:

return $form;

Upon reloading the page, you should see the full form as expected.

Default values

One last minor thing is that there are a series of default values (determined by the system_elements function) assigned to form elements. These are redundant if declared again in your form. In this case, the only setting that applies is the #return_value => 1 in the checkbox field.

Converted function

The following is the completed code after translating project_settings: