Form element layout

Update february, 2019: I (kaare) have drifted out of Drupal development and will no longer support or develop this module. Feel free to take over maintainership.

About

Form API and field setting for manipulating the layout of primitive form elements. Main features:

• Form attribute for placing the form #description before the input element (#description_display).
• Field configuration for moving the help text before or after the input element. This is useful for multi value fields or fields with a large input space where the help text falls far away from the field title.
• Form attribute for adding additional classes to form #title and #descriptions (#title_classes and #description_classes).
• Field labels and help texts have their own CSS classes (fel-field-label and fel-field-help-text) to separate them from additional #titles and #descriptions added by some field types. This is handy for themers and other modules that need to separate the configured texts from the rest.

API

The main module, Form element layout (fel.module) provides the primitive rendering and behavior around the following form attributes:

• #description_display: Where the #description should be rendered relative to its #children. Can be before or after. Default is before for fieldsets and after for the rest.
• #description_classes: Array of additional classes to add to the #description when rendered. The default 'description' class is always added. It can be further customized by overriding the theme fel_description.
• #title_classes: Array of additional classes to add to the #title when rendered.

Example usage for developers/themers:

$form['example'] = array(
  '#type' => 'textfield',
  '#title' => t("Example input"),
  '#description' => t("Example description of what this element does."),

  // Attributes honored by fel.module
  '#title_classes' => array('example'),
  '#description_classes' => array('important'),
  '#description_display' => 'before',
);

Supported field types

All element and field types core provide is supported by Form element layout fields (fel_fields.module). In addition some popular contrib field modules are supported:

• Address Field
• Date
• Email field
• Entity reference
• Field Collection Table
• Geofield
• Link
• Matrix
• Media
• Meta tags quick
• Multiupload filefield widget
• Multiupload imagefield widget

Otherwise it has a fall-back mechanism that recursively will attach the appropriate Form API attributes for elements likely to be rendered. If it doesn't and your favorite module doesn't respond to the configuration, please issue a feature request for it!

Field modules may also provide support for fel_fields.module by adding a plugin for it. This is documented in the Advanced help section of this module.

How it works: theme replacements

In order to alter the order of field elements and inject classes a few themes need to be altered. Instead of hijacking existing themes through hook_theme_registry_alter(), this module will as far as possible use replacement themes. That is, replace $element['#theme'] or $element['#theme_wrapper'][] with our own version.

This makes it still possible for themers to replace or further alter the themes by overriding the themes while keeping the functionality provided by this module. The replacement functions are:

Core replacements

Contrib replacements

Related projects and issues

• D8 issue: #314385: Make position of #description configurable via the API
• D8 issue: #2318757: Make position of #description configurable via the API for form field widgets
• D7 sandbox module: Top Description. This module moves all element descriptions above the input element. For all forms all over. No settings to modify its behavior. Minimally maintained. Maintenance fixes only.
• D7 module: Label Help. This module adds an additional text element that are displayed before the input element. It doesn't touch or move the existing field $instance['description'].
• D7 module: Extra Field Description. Behaves exactly like Label Help.
• D7 module: Better field description. Like the two above it adds an additional text for fields, not touching the original help text ($instance['description']). The twist here is that it extracts the editing of the text to a different page with different permission, allowing non-admins (like, say, editors) to edit it without messing up other field settings.
• D6 sandbox module: Element shuffle. This the first version of Form element layout. The concept is the same, but was not suitable for D7 port and had some real context leakage. FEL was therefore rewritten from scratch.