Skip to content

Form Builder

Form Builder provides a flexible form interface allowing editing a variety of CiviCRM entities as well as a developer interface.

Extending Form Builder

Via event listener

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

Via an entityType declaration file

It is also possible to expose entities in Form Builder 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'],
  ],
];
4. 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. 5. 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.

Making fields available for use in Form Builder

If an expected element for an Entity is missing from Form Builder, it's likely that the <html><type> needs to be added to the xml file for that Entity so that Form Builder can render it.

Via XML declaration

The beauty of FormBuilder is that any changes that are presently made in your XML file will be integrated directly into FormBuilder after a regeneration of the boilerplate. This is also the forward direction of CiviCRM.

  1. Modify you XMl entity declaration at yourextension/xml/schema/CRM/yourclassname/EntityName.xml
  2. Within the <field> declaration you will want to add a <html> declaration, which essentially tells FormBuilder how to display this field (works also for FormBuilder filters). One example is the AcitivtyContact entity here or other examples [here])(https://github.com/civicrm/civicrm-core/blob/master/xml/schema/)
  3. After the modification you need to rerun civix generate:entity-boilerplate, which will update your DAO automatically
  4. Flush your system cache
  5. Now all the new fields that you have added will just work in FormBuilder and Searchkit
Examples of HTML fields
    <html>
      <type>EntityRef</type>
      <label>Created By</label>
    </html>
    <html>
      <type>Number</type>
    </html>
    <html>
      <type>CheckBox</type>
    </html>
    <html>
      <type>Text</type>
    </html>

Hot tips

  • If you receive an error when attempting to regenerate your boilerplate then you will need to perform a civix upgrade and then retry civix generate:entity-boilerplate
  • Always clear your cache after your have modified the boilerplate as your changes will not appear