Skip to content

Search Kit - Links and Tasks

Overview

SearchKit allows users to take action on the results via links and tasks.

  • Links point to an actual page url (could be a traditional page-route or an Afform with a route).
  • Tasks perform api actions on one or more selected records. Tasks appear in the dropdown menu above a search display. A task can also be presented as a link if it's suitable for a single record.
  • Legacy Tasks are page urls for bulk tasks from older searches. SearchKit is able to present them in the dropdown as well.

Links are gathered for an entity using the getLinks Api4 action. For most entities this api returns a handful of paths e.g. to add/view/update/delete entities.

Some entities implement hooks to expand or customize these links, for example Activity.getLinks will return multiple "add" links for various activity types, which SearchKit automatically transforms into a dropdown menu in the toolbar. It also returns specialized 'update' links for some activity types.

To programmatically alter the links available to an entity, use a class (example: ContactLinksProvider) to implement callbacks for one or both of these events:

  • civi.api4.getLinks: Allows you to add or alter the stock list of links for an entity.
  • civi.api.respond: Generic api post-event is useful if you want to alter links based on entity values (e.g. the ActivityLinksProvider uses this to contextually alter links based on input values.

More on the schema

You can see where links are initially defined for entities in Schema defintion

Search Kit treats anything within brackets like a token and replaces the value, e.g. [id] becomes the actual contact ID for each row.

Tasks

Angular-based Tasks

New tasks built for Search Kit consist of an Angular controller, which receives the name of the entity (e.g. "Contact") and an array of IDs to be acted upon. Typically this controller will present the user with a configuration form, and then run crmSearchBatchRunner which performs an api action on 500 records at a time & shows a progress bar to the user.

Note that the api that is called needs to be the same entity as the Search Kit entity. For example if you want to take a custom action on a contact you should ensure the entity for your custom action is 'Contact'

Extensions wishing to add new actions to Search Kit should implement hook_civicrm_searchKitTasks.

ApiBatch Tasks (available in CiviCRM 5.56+)

For tasks that involve calling an api action once per row, extensions can skip writing their own Angular templates and controllers by setting 'apiBatch' which will use a generic controller and template provided by SearchKit. When implementing hook_civicrm_searchKitTasks, add the following settings (example from the Delete action):

  $tasks[$entityName]['delete'] = [
    'title' => E::ts('Delete %1', [1 => $entity['title_plural']]),
    'icon' => 'fa-trash',
    'apiBatch' => [
      'action' => 'delete', // Name of API action to call once per row
      // note that entity cannot be specified and will be the same as `$entityName`
      'params' => NULL, // Optional array of additional api params
      'confirmMsg' => E::ts('Are you sure you want to delete %1 %2?'), // If omitted, the action will run immediately with no confirmation
      'runMsg' => E::ts('Deleting %1 %2...'),
      'successMsg' => E::ts('Successfully deleted %1 %2.'),
      'errorMsg' => E::ts('An error occurred while attempting to delete %1 %2.'),
    ],
  ];

Note that strings within the apiBatch setting should be translated but will be further processed by javascript to replace the following tokens:

  • %1: Row count
  • %2: Title of entity (pluralized if count > 1)

ApiBatch Tasks with custom APIv4 action

apiBatch['action'] can also be a custom APIv4 action

ApiBatch Tasks with user input (available in CiviCRM 5.80+)

The values to be used in the batch action can be specified by the user. Use the 'fields' param.

  $tasks['Contact']['set_source'] = [
    'title' => E::ts('Set contact source),
    'icon' => 'fa-trash',
    'apiBatch' => [
      'action' => 'update', // Name of API action to call once per row
      // note that entity cannot be specified and will be the same as `$entityName`
      'fields' => [['name' => 'contact_source', 'required' => TRUE, 'default_value' => 'Tis a mystery'],  // Array of fields to prompt for.  Values are then used in the update.
      'confirmMsg' => E::ts('Are you sure you want to set source for %1 %2?'), // If omitted, the action will run immediately with no confirmation
      'runMsg' => E::ts('Setting source for %1 %2...'),
      'successMsg' => E::ts('Successfully set source for %1 %2.'),
      'errorMsg' => E::ts('An error occurred while attempting to set source for %1 %2.'),
    ],
  ];

Legacy Search Tasks

For transitional purposes, Search Kit supports many of the tasks from Advanced Search, namely the ones that work in "standalone" mode (can be accessed via a url outside of the Advanced Search screen). To illustrate, here's a snippet from CRM_Contact_Task: 

self::TASK_PRINT => [
  'title' => ts('Print selected rows'),
  'class' => 'CRM_Contact_Form_Task_Print',
  'result' => FALSE,
],
self::LABEL_CONTACTS => [
  'title' => ts('Mailing labels - print'),
  'class' => 'CRM_Contact_Form_Task_Label',
  'result' => TRUE,
  'url' => 'civicrm/task/make-mailing-label',
  'icon' => 'fa-print',
],
Notice that the first task does not contain a url key and therefore is not available in Search Kit, whereas the second task is accessible via a standalone url (and looks nice in the task list because of the icon).

Any task with a url property added via hook_civicrm_searchTasks will appear in Search Kit as well.

For Contact searches, the above should be sufficient, and the $form->_contactIds variable will be populated with the selected record ids as usual. For other searches such as on Contributions, the $form->_contributionIds variable will not be populated for you as usual. You will need to retrieve it in preProcess() using e.g. $this->_contributionIds = explode(',', $this->get('id'));