Skip to content

civi.afform.prefill

Summary

This Symfony event is dispatched when prefilling an Afform (Angular Form) with default/existing data. It is dispatched once for each entity on the form in topological dependency order (determined by civi.afform.sort.prefill). It allows developers to customize or override the IDs used to load default values for entities and join relationships on the form, or set field prefill values directly.

Definition

This event is dispatched via the Symfony EventDispatcher.

public static function onAfformPrefill(\Civi\Afform\Event\AfformPrefillEvent $event): void

Parameters

  • \Civi\Afform\Event\AfformPrefillEvent $event

Event Methods

  • getAfform(): array - Returns the main Afform configuration array.
  • getFormDataModel(): \Civi\Afform\FormDataModel - Returns the form data model instance.
  • getApiRequest(): \Civi\Api4\Action\Afform\Prefill - Returns the active API request initiating the prefill processor. Methods on the processor include loadEntity(), unloadEntity(), getFillMode(), getArgs(), and getSubmitterContactID().
  • getEntityType(): ?string - Returns the entity type of the current entity being prefilled (e.g. Contact, Activity).
  • getEntityName(): string - Returns the name of the entity on the form (e.g. Individual1, Activity1).
  • getEntity(): array - Returns the form data model definition for the current entity.
  • getSecureApi4(): callable - Returns a secure, API4-style wrapper for executing APIv4 actions on behalf of the current entity.
  • getEntityId(int $index = 0): mixed - Returns the ID of the entity at the given repetition index if already resolved.
  • getEntityIds(?string $entityName = null): array - Returns all resolved ID values for the given entity name (useful for referencing dependencies).
  • setEntityId(int $index, int|string $entityId): self - Sets the database ID for the entity instance at the specified index and causes its data and joins to be loaded into the prefill processor.
  • setJoinIds(int $index, string $joinEntity, array $joinIds): self - Sets the IDs for a joined entity (e.g. relationship or location blocks) at the specified index.
  • getRecords(): array - Returns all prefill records for the current entity.
  • setRecords(array $records): self - Replaces the prefill records for the current entity.
  • getValue(string $field, int $index = 0): mixed - Returns the value of a specific field for the entity instance at the given index.
  • getValues(int $index = 0): array - Returns all field values for the entity instance at the given index.
  • setValue(string $field, mixed $value, ?int $index = null): self - Sets a single field prefill value. If $index is null, sets the field across all existing records for the entity (or on the first record if none exist yet).
  • setValues(array $values, ?int $index = null): self - Sets multiple field prefill values. If $index is null, sets the fields across all existing records for the entity (or on the first record if none exist yet).

Availability

  • Available since CiviCRM 5.56
  • Method getEntityIds() added in CiviCRM 5.57
  • Methods getRecords(), setRecords(), getValue(), getValues(), setValue(), and setValues() added in CiviCRM 6.20

Example

use Civi\Afform\Event\AfformPrefillEvent;

public static function onAfformPrefill(AfformPrefillEvent $event): void {
  // If prefilling a specific entity named 'Individual1'
  if ($event->getEntityName() === 'Individual1' && !$event->getEntityId()) {
    // Force prefilling contact ID 123
    $event->setEntityId(0, 123);
  }

  // Or set field defaults directly based on custom logic
  if ($event->getEntityName() === 'Individual1') {
    $event->setValue('first_name', 'DefaultName');
    $event->setValues([
      'job_title' => 'Volunteer',
    ]);
  }
}

Alternatively, developers can use $event->getApiRequest() directly to load or unload entities:

use Civi\Afform\Event\AfformPrefillEvent;

public static function onAfformPrefill(AfformPrefillEvent $event): void {
  $apiRequest = $event->getApiRequest();
  if ($event->getEntityName() === 'Individual1' && !$event->getEntityId()) {
    $apiRequest->loadEntity($event->getEntity(), [['id' => 123]]);
  }
}