Skip to content

ECA Form

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:
    • Textfield
    • Checkboxes
    • Select lists
    • etc.
  • 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.

Usage

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.

Note

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).
  • Ajax (JavaScript) that is changing the output of a form without reloading the whole page. Ajax triggering can (but is not forced to) partially or completely suppress validation errors. However, not all Ajax handlers submit a form, and therefore they won't trigger validation and submission. But many ajax handlers do so, because they can instruct the form to completely rebuild, and they do so by submitting the 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 getFormId of the according form class, for example Drupal\system\Form\SiteInformationForm::getFormId which returns system_site_information_settings as 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 user and for a taxonomy term it is taxonomy_term.
  • 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 node has the following operations available: default (used for the add form), edit (for the edit form) and delete.

Caveats

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.

Examples

Installation

1
2
composer require drupal/eca
drush pm:install eca_form

Instead of using Drush to enable the module, you can also go to "Administration / Extend" (/admin/modules) and enable the module ECA Form from there.