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:
- Add the mixin
<mixin>afform-entity-php@1.0.0</mixin>
to your extension'sinfo.xml
file (note: for backward compatability with versions < 5.50 you must add a shim. - Ensure the entity in question has apiv4 CRUD entities (these get generated automatically if using civix with an extension)
- Create a php file in the following location -
afformEntities/EntityName.php
as you can see here in thededuper
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'],
],
];
'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.
- Modify you XMl entity declaration at
yourextension/xml/schema/CRM/yourclassname/EntityName.xml
- 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/) - After the modification you need to rerun
civix generate:entity-boilerplate
, which will update your DAO automatically - Flush your system cache
- 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 retrycivix generate:entity-boilerplate
- Always clear your cache after your have modified the boilerplate as your changes will not appear