This module is a helper for customization of forms.
It does nothing that you wouldn't be able to do by yourself in a custom module, but tries to make it easier. It currently provides:
- Control on the inner div wrapper of the form itself.
- Control on the outer wrapper div of each visible form element.
- A single switch to get rid of the CSRF form tokens for nicer GET submit urls.
- An helper default for simple/common AJAX cases.
It works by adding additional properties, that are all grouped under a #formthemer parent, and vary slightly between $form and $element.
They are obviously all optional and fallback to Drupal's default.
Form
Control on the inner div wrapper of the form itself.
@see #1822210: Investigate removing the inner div in form.html.twig, #495480: Add class to wrapper div of form elements theme_form() or #2250381: Remove the inner div wrapper from forms for background information.
Available properties are:
- no_inner_wrapper (bool), set this to true to get rid of the inner div enterly.
- inner_wrapper (array), with the following keys:
- html_element : element to use as inner wrapper instead of the div.
- attributes: (array) standard attributes (class, etc) as used by drupal_attributes(), applied to the wrapper.
Examples, in your form generator function or in form_alter:
Original output:
<form accept-charset="UTF-8" id="contact-site-form" method="post" action="/contact" class="contact-form">
<div>
<div class="form-item form-type-textfield form-item-name">
<label for="edit-name">Your name <span title="This field is required." class="form-required">*</span></label>
<input type="text" class="form-text required" maxlength="255" size="60" value="" name="name" id="edit-name">
</div>
<!--[...]-->
</div>
</form>
No wrapper:
$form['#formthemer']['no_inner_wrapper'] = TRUE;
<form accept-charset="UTF-8" id="contact-site-form" method="post" action="/contact" class="contact-form">
<div class="form-item form-type-textfield form-item-name">
<label for="edit-name">Your name <span title="This field is required." class="form-required">*</span></label>
<input type="text" class="form-text required" maxlength="255" size="60" value="" name="name" id="edit-name">
</div>
<!--[...]-->
</form>
Custom element:
$form['#formthemer']['inner_wrapper'] = array(
'html_element' => 'fieldset',
'attributes' => array(
'class' => array('my-first-class', 'my-second-class'),
'data-myAttribute' => 'myCustomValue',
),
);
<form accept-charset="UTF-8" id="contact-site-form" method="post" action="/contact" class="contact-form">
<fieldset class="my-first-class my-second-class" data-myattribute="myCustomValue">
<div class="form-item form-type-textfield form-item-name">
<label for="edit-name">Your name <span title="This field is required." class="form-required">*</span></label>
<input type="text" class="form-text required" maxlength="255" size="60" value="" name="name" id="edit-name">
</div>
<!--[...]-->
</fieldset>
</form>
Form elements
Control on the outer wrapper div of each visible form element.
Available properties are:
- no_wrapper (bool), set this to true to get rid of the wrapper div enterly.
- wrapper (array), with the following keys:
- html_element: element to use as wrapper instead of the div.
- attributes: (array) standard attributes (class, etc) as used by drupal_attributes(), applied to the wrapper.Default is to add them to the standard Drupal ones, not to replace them (see below).
- no_default_classes (bool): remove standard drupal classes. If some are given in the 'attributes' property, your custom ones will still be added. Be aware that some modules' js/css might expect those.
Examples, in your form generator function or in form_alter:
Original output:
<div class="form-item form-type-textfield form-item-name">
<label for="edit-name">Your name <span title="This field is required." class="form-required">*</span></label>
<input type="text" class="form-text required" maxlength="255" size="60" value="" name="name" id="edit-name">
</div>
No wrapper:
$form['name']['#formthemer']['no_wrapper'] = TRUE;
<label for="edit-name">Your name <span title="This field is required." class="form-required">*</span></label>
<input type="text" class="form-text required" maxlength="255" size="60" value="" name="name" id="edit-name">
Custom element:
$form['name']['#formthemer']['wrapper'] = array(
'html_element' => 'li',
'attributes' => array(
'class' => array('my-first-class', 'my-second-class'),
'data-myAttribute' => 'myCustomValue',
),
);
<li data-myattribute="myCustomValue" class="my-first-class my-second-class form-item form-type-textfield form-item-name">
<label for="edit-name">Your name <span title="This field is required." class="form-required">*</span></label>
<input type="text" class="form-text required" maxlength="255" size="60" value="admin" name="name" id="edit-name">
</li>
Custom element, no default classes:
$form['name']['#formthemer']['wrapper'] = array(
'html_element' => 'li',
'attributes' => array(
'class' => array('my-first-class', 'my-second-class'),
'data-myAttribute' => 'myCustomValue',
),
'no_default_classes' => TRUE,
);
<li data-myattribute="myCustomValue" class="my-first-class my-second-class">
<label for="edit-name">Your name <span title="This field is required." class="form-required">*</span></label>
<input type="text" class="form-text required" maxlength="255" size="60" value="admin" name="name" id="edit-name">
</li>
Form token
A single switch to get rid of the CSRF form tokens for nicer GET submit urls.
@see #1191278: Simplify DX of removing form_id, form_build_id, and token from RESTful GET forms for background and security aspects.
IMPORTANT: there are serious security risks in doing so, only use if you are certain of what you are doing
Available property is:
- no_token (mixed), set this to true (or anything not FALSE) to get rid of the form tokens and submit it using the GET method. Or to 'POST' if you want to get rid of the tokens but still submit using POST (can't think of a use case for that, but let me know if you find one, curious !).
Usage:
$form['#formthemer']['no_token'] = TRUE;
Note it doesn't remove automatically the submit button name, you still have to manually set the 'name' attribute:
$form['submit'] = array(
'#type' => 'button',
'#value' => t('Apply'),
'#attributes' => array(
'name' => '',
),
);
ajax helper
In the majority of cases, adding an #ajax property to a form element consists of declaring a callback function that will just return an element of the form, and set a wrapper on the target element.
To avoid having to repeat this task every time, formthemer provides the ability to defer both the wrapping of the target and the callback implementation.
Available property is:
- ajax (array) with the following keys
-
return (mixed) #parents of the target form element, either as an array
array('grand_parent', 'parent', 'target')
or a string'grand_parent][parent][target'
- wrapper_element (string) html element to use as wrapper around the target, default to 'div'.
- any standard FAPI '#ajax' parameters (effect, …)
-
return (mixed) #parents of the target form element, either as an array
Before:
/**
* Form declaration.
*/
function mymodule_myform($form, $form_state) {
$form['a_parent_element']['my_target'] = array(
'#prefix' => '<div id="my-target-id">',
'#suffix' => '</div>',
'#type' => 'container',
//…
);
$form['my_trigger_element'] = array(
'#type' => 'button',
'#ajax' => array(
'wrapper' => 'my-target-id',
'callback' => 'mymodule_myform_ajax',
),
//…
);
}
/**
* Ajax callback.
*/
function mymodule_myform_ajax($form, $form_state) {
return $form['a_parent_element']['my_target'];
}
You can simply use:
/**
* Form declaration.
*/
function mymodule_myform($form, $form_state) {
$form['a_parent_element']['my_target'] = array(
'#type' => 'container',
//…
);
$form['my_trigger_element'] = array(
'#type' => 'button',
'#formthemer' => array(
'ajax' => array(
'return' => array(
'a_parent_element',
'my_target',
),
),
),
//…
);
}
Support for additional tweaks "might" be added, like customization of labels and descriptions, but it probably (hopefully) will die with drupal 7.
Project information
- Minimally maintained
Maintainers monitor issues, but fast responses are not guaranteed. - Maintenance fixes only
Considered feature-complete by its maintainers. - Module categories: Developer Tools
- 12 sites report using this module
- Created by bellesmanieres on , updated
- Stable releases for this project are covered by the security advisory policy.
Look for the shield icon below.
Releases
Development version: 7.x-1.x-dev updated 1 Feb 2016 at 08:08 UTC