Altering & validating forms

Rules Forms Support allows users to manipulate forms when a form is built, during validation, or when a form submitted. Once events are activated for a form, users can define rules to accomplish tasks like validating form element values, setting form errors, redirecting users, or setting form titles. It was originally developed for and shipped with Rules 1 (Drupal 6), but since the release of Rules 2 (Drupal 7), the Rules Forms Support project has been moved to a separate, standalone module.

Rules Forms Support for Drupal 7 began as a direct port of the original module that shipped with Rules 1 (Drupal 6). Since then the module has been updated to provide a more friendly user experience, replacing the element ID system of the original Rules Forms Support with one that allows forms to be manipulated wholly within the Rules 2 interface. Following is a brief tutorial on working with the new Rules Forms interface.

Getting started with Rules Forms Support

Activating events for a form

Rules Forms can allow users to build reaction rules that react to the events of any form built on the Drupal Form API. In order to begin creating rules for a particular form, we must first activate events for the form:

1. Go to the Forms Support page in the Rules administration menu at admin/config/workflow/rules/forms.
2. Select the checkbox Enable event activation messages on forms and click the Save settings button.
3. Go to the form on your site that you would like to customize with Rules, e.g. go to node/add/article to enable events on the "Create Article" form.
4. On the top of the page you will see a message with a link to activate events for the form, click it.
5. Enter a human-readable label for identifying the form.
6. In some cases, form level validate and submit events may not appropriately trigger your rules because forms may implement button level validate or submit handlers or you may just want to target a specific form button for validate or submit events. To activate button level validate and submit events for a form, check the checkbox labeled Enable button level validate/submit events.
   Note: In Rules 2 you can create rules that react on multiple events. Therefore, Rules Forms rules can be invoked on form and button level validate/submit events.
7. Confirm the activation by clicking the Activate button.
8. Events for the form have now been activated. To create a new form rule, navigate to the Rules overview page at admin/config/workflow/rules and click the Add new rule link. Events for your newly activated form will now be available.
9. Note: After activating events for a form, if you are not redirected back to the form you should revisit the form again so that Rules Forms can evaluate and store data about its elements.

Creating form element conditions and actions

Rules Forms allows us to manipulate single form elements. Elements are selected in a drop-down list in condition and action interfaces. This brief guide discusses how to use the new Rules Forms interface to target an individual form element:

1. Create a new reaction rule using the Rules interface.
2. Select the desired event for the target form.
3. On the following screen, you will see displayed a select list of form elements. Select the target form element from the select list and click Continue.
   - Form elements are categorized by type to make them more easily identifiable.
   - In the event that the form element select list is not populated, try rebuilding form element data as described in the Troubleshooting section below.

Deactivating events for a form

To deactivate form events for a form:

1. Navigate to the Forms Support page in the Rules administration menu at admin/config/workflow/rules/forms.
2. Expand the fieldset labeled Active forms.
3. Select the forms you would like to disable from the checkboxes.
4. Click the button labeled Deactivate events.
5. Note: deactivating form events will break existing rules that implement events provided by those forms.

Troubleshooting

Due to the nature of manipulating the Drupal Form API, sometimes your rules may not behave as intended. Rules Forms developers have provided some tools for troubleshooting these types of cases:

Using the form element inspection tool

Rules Forms Support provides a tool for inspecting form elements on forms where Rules Forms events are enabled. This tool can be used to identify and target specific form elements, determine the current attributes of a form element, or inspect element attributes following the execution of a rule:

1. Navigate to the Forms Support page in the Rules administration menu at admin/config/workflow/rules/forms.
2. Select the checkbox labeled Enable form element inspection tool.
3. Click the button labeled Save settings.
4. To use the inspection tool, navigate to the desired form for which Rules Forms events are activated.
5. Mouse over the question mark (?) near any form element to display a list of that element's current attributes and their values.

Rebuilding form element data

In the event that the form element list is not being properly displayed within the element select list in the rules interface, you may need to rebuild Rules Forms' internal storage of form element data:

1. Navigate to the Forms Support page in the Rules administration menu at admin/config/workflow/rules/forms.
2. Expand the fieldset labeled Form elements.
3. Select the form whose elements you want to rebuild from the select list.
4. Click the Rebuild button.
5. Finally, navigate to the form whose elements need to be rebuilt. When the form is displayed for the first time, Rules forms will evaluate it and display a message notifying the user that its internal memory has been updated.