Skip to content

FormBuilder

Home > Developer Guide > FormBuilder (Afform) FormBuilder provides a flexible form interface allowing editing a variety of CiviCRM entities as well as a developer interface.

Exposing an entity to FormBuilder

Via event listener

The FormBuilder GUI can be extended via the civi.afform_admin.metadata event. This event is used for adding entities, elements, input types, etc.

Via an Afform entityType declaration file

It is also possible to expose entities in FormBuilder by adding a declaration. To do this:

  1. Add the mixin <mixin>afform-entity-php@1.0.0</mixin> to your extension's info.xml file (note: for backward compatability with versions < 5.50 you must add a shim.
  2. Ensure the entity in question has apiv4 CRUD entities (these get generated automatically if using civix with an extension)
  3. Create a php file in the following location - afformEntities/EntityName.php as you can see here in the deduper extension. For more complex examples see core.
<?php

use CRM_MyExtension_ExtensionUtil as E;

return [
  'type' => 'primary',
  'defaults' => "{}",
  'boilerplate' => [
    ['#tag' => 'af-field', 'name' => 'name'],
    ['#tag' => 'af-field', 'name' => 'xxx'],
  ],
];
  1. The boilerplate specifies the fields that are automatically added to a new Submission Form. In the example above, the fields 'name' and 'xxx' would be added.
  2. An entity can be available for "Submission forms" and/or for "Field blocks". In order for the entity to be available for Submission forms, add 'type' => 'primary' example or only as Field blocks, leave blank or add 'type' => 'join' example. A Field block (or join) is only available in relation to a primary entity.

Core afform entities have examples of other parameters that can be added such as repeat_max, unique_fields, boilerplate, icon, alterFields, and data defaults. Be sure to test them out to see what works best with a custom entity.

!!! tip "Making fields available for use in FormBuilder" If an expected element for an Entity is missing from FormBuilder, it's likely that input_type needs to be added to the field. See Entities for possible values. Find the getFields function in the corresponding .entityType.php file for that Entity and add an appropriate input type. (for older entities using legacy xml schema files, the corresponding tag would be <html><type> and the code generator script would need to be run after updating).