This module allows to change and extend any existing form. Examples:
- Disable or hide existing fields
- Set fields as required
- Add or change available options
- Set and change default values
- Add new form fields:
- Select lists
- Group field elements together
- Collapsible HTML details and containers
- Validate user input
- Set granular form field errors
- Execute custom logic on form submissions
- Check for any submitted user input and react accordingly
- Redirect to a certain page
- Make the form a multistep worflow
- Optionally with ajax
- Build up custom forms from scratch
- This ability requires the ECA Render module to be installed.
Everything about forms within ECA will most likely be found within this module. As always in ECA, form-related workflows always start with a certain event. This module covers all main form events that occur when Drupal is processing a form.
The following events take place, listed ascending in their time occurring order:
- Build form: This is the earliest form event, also to be seen as the first layer of form building events. This type of event happens, when the render array of the form is initially being build up.
- Process form: This is the second layer of form building events. This can and will be used by components that may rely on logic that happened before within the Build form event layer.
- After build form: The third layer of form building events. This can be used for internal follow-up actions,
that don't affect the final result of the form display anymore.
All three events listed above are parts of the form building events. These types of events are being triggered in order to display a form to a user.
Form building events are being triggered at least once when a form is being rendered on a page. It may be called multiple times on the same page, when a component instructs to rebuild a form.
One note about fields of content entities:
The processing of content entity fields is usually happening within the second layer of form events, Process form. In case you want to change or extend those fields, the earliest event to react upon is a Process form event. Reacting upon Build form event to work with entity fields will most likely not work.
When submitting a form, Drupal always involves two layers: Validation and Submission. Drupal always first executes the validation layer. When the validation layer results with no validation error, then Drupal will execute the submission layer.
That means, when at least one validation error was found, then Drupal won't execute the submission layer at all. Derived from that core mechanic, ECA offers two according types of events:
- Validate form: This happens when Drupal executes the validation layer.
- Submit form: This happens when Drupal executes the submission layer - but only when no validation errors occurred.
Typical triggers of form validation and submission are
- The user submitted a form by clicking on a submit button (for example "Save" on a content form).
- Programmatic client instructions: For example, automated frontend tests that may fake a form submission by sending form input as a POST request to the web server.
When to use form events¶
Form events are mostly useful to change the output, and to extend validation and submission behavior of an existing form. Whenever data is coming from form input that needs to be processed, form events may help to achieve this.
Furthermore, new custom forms can be created by using actions of the ECA Render module, specifically the action "Render: custom form" is meant for such use case.
When it's about adding or changing data of a content entity in general, events of the ECA Content may be more suitable and preferred over form events. Specifically events such as Presave content entity, Insert content entity and Update content entity may be considered.
How to configure a form event¶
Any sort of form event always has the following restriction options, in order to specify for which form(s) the event should apply:
- Restrict by form ID: At most forms, the element ID of the rendered
<form>HTML tag can be set here. Note for developers: The form ID is being mapped to a machine name of a Drupal form. The machine name of a Drupal form can be found by looking into PHP code. Specifically, it is the method
getFormIdof the according form class, for example
system_site_information_settingsas the form ID value. When working with entity forms, the other options listed below can be specified instead.
- Restrict by entity type ID: The machine name of the entity type. When the model should change something on a
content item (for example an article), then the machine name is
node. For a user form, it is
userand for a taxonomy term it is
- Restrict by entity bundle: Besides the entity type ID, it can be additionally restricted to certain bundle(s)
only. When the model should be applied only for articles, and the machine name of the content type is
article, then exactly this machine name can be set here.
- Restrict by operation: When targeting a specific entity form, this should usually be specified here too.
Otherwise, if not specified, this event will apply for any form having the specified type of entity. Besides edit
forms, this would also include delete confirmation forms as an example. Unfortunately at this time, the info what
operations exist for a specific type of entity, can only be found by looking into PHP code, specifically within the
annotation of the according entity class. A
nodehas the following operations available:
default(used for the add form),
edit(for the edit form) and
Using the form validation event for a different purpose¶
It is generally a bad idea to execute logic within the form validation error that has nothing to do with form validation. This layer should only be used to validate form input.
Reading and working with submitted form input¶
On simple forms, using the action Form field: get submitted value can be helpful. But for complex forms, such as of a content entity, it may be hard to get any targeted form input value using this action. When the form is about a certain content entity, such an entity can be build up using the action Entity form: build entity. With that mechanic, one can directly work with an entity, reading and setting field values with actions provided by the ECA Content module.
Hiding form fields¶
It is possible to hide a form field by using the action Form field: set access. It should be noted though, that such instruction is only about display logic in a specific form. Many times however, it is about a real access issue. For example, certain users may never be allowed to see a certain field of a content entity. For such case, using components of the ECA Access module is more advisable. Setting up field access using ECA Access, it makes sure a user will never be able to access a certain field, which includes form displays.
Instead of using Drush to enable the module, you can also go to "Administration / Extend" (
enable the module ECA Form from there.