Skip to content

Search Kit - Links and Tasks

Most API entities provide a set of "paths" which Search Kit can use to display view/edit/delete links per row. For example, the Contact entity contains the following paths: 

"add": "civicrm/contact/add?reset=1&ct=[contact_type]",
"view": "civicrm/contact/view?reset=1&cid=[id]",
"update": "civicrm/contact/add?reset=1&action=update&cid=[id]",
"delete": "civicrm/contact/view/delete?reset=1&delete=1&cid=[id]"
You can add these "paths" in your own entity as part of the XML that defines the entity (as part of the table definition as you can see in the example below: 
<table>
  <base>CRM/Koalecttocivi</base>
  <class>KoalectLog</class>
  <name>civicrm_koalect_log</name>
  <comment>Log for incoming Koalect Transactions</comment>
  <log>true</log>
  <paths>
    <view>civicrm/koalecttocivi/koalectlog?reset=1&amp;action=view&amp;lid=[id]</view>
    <update>civicrm/koalecttocivi/koalectlog?reset=1&amp;action=update&amp;lid=[id]</update>
    <delete>civicrm/koalecttocivi/koalectlog/delete?reset=1&amp;lid=[id]</delete>
  </paths>

More on the XML schema

You can find more on how the XML schema for entities works in XML 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 (availble 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)

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'));