hook_civicrm_links¶
Summary¶
This hook allows you to modify action links including: the actions at the end of a search result row, the Create New dropdown, and the Actions dropdown at the top of a contact record.
Notes¶
Warning
The operation create.new.shorcuts
is now deprecated and has been replaced with the correctly spelled create.new.shortcuts
.
Definition¶
hook_civicrm_links($op, $objectName, $objectId, &$links, &$mask, &$values)
Parameters¶
-
string
$op
- the context in which the links appear, such asview.contact.activity
,survey.dashboard.row
,pcp.user.actions
orpdfFormat.manage.action
. This should be lowercase but there are some inconsistencies in CiviCRM core (eg.view.contact.userDashBoard
). -
string
$objectName
- the entity the links relate to (orNULL
if$op
iscreate.new.shortcuts
) -
int
$objectId
- the CiviCRM internal ID of the entity (orNULL
if$op
iscreate.new.shortcuts
) -
array
$links
- the links to modify in placeeach item in the array may have:
-
name
: the link text -
url
: the link URL base path (likecivicrm/contact/view
, and fillable from$values
) -
qs
: the link URL query parameters to be used by sprintf() with $values (likereset=1&cid=%%id%%
when$values['id']
is the contact ID) -
title
(optional): the text that appears when hovering over the link -
extra
(optional): additional attributes for the<a>
tag (fillable from$values
) -
bit
(optional): a binary number that will be fitered by $mask (sending nothing as$links['bit']
means the link will always display) -
ref
(optional, recommended): a CSS class to apply to the<a>
tag. -
class
(optional): Any other CSS classes to apply to the<a>
tag (e.g. no-popup).
-
-
int
$mask
- a bitmask that will filter$links
-
array
$values
- values to fill$links['url']
,$links['qs']
, and/or$links['extra']
usingsprintf()
-style percent signs
!!!tip If you omit the qs
parameter, Civi will interpret the url
as a regular URL rather than as a Civi admin page. This is useful if you want to link to a non-Civi page. If needed, you can add query string parameters to the url
by obtaining the needed values from &$values
. (Works for Civi Profile search results.)
Returns¶
NULL
Examples¶
function MODULENAME_civicrm_links($op, $objectName, $objectId, &$links, &$mask, &$values) {
$myLinks = [];
switch ($objectName) {
case 'Contact':
switch ($op) {
case 'view.contact.activity':
// Adds a link to the main tab.
$links[] = [
'name' => E::ts('My Module Actions'),
'url' => 'mymodule/civicrm/actions/%%myObjId%%',
'title' => 'New Thing',
'class' => 'no-popup',
];
$values['myObjId'] = $objectId;
break;
case 'contact.selector.row':
// Add a similar thing when a contact appears in a row
$links[] = [
'name' => E::ts('My Module'),
'url' => 'mymodule/civicrm/actions/%%myObjId%%',
'title' => 'New Thing',
'qs' => 'reset=1&tid=%%thingId%%',
'class' => 'no-popup',
];
$values['myObjId'] = $objectId;
$values['thingId'] = 'mything';
break;
case 'create.new.shortcuts':
// add link to create new profile
$links[] = [
'url' => '/civicrm/admin/uf/group?action=add&reset=1',
'name' => E::ts('New Profile'),
// old extensions using 'title' will still work
];
break;
case 'view.report.links':
// disable copy & delete links.
unset($links['copy']);
unset($links['delete']);
}
}
return $myLinks;
}
Adding contextual links to the rows of a contact's Events tab and Find Participants search result
function mymodule_civicrm_links($op, $objectName, $objectId, &$links, &$mask, &$values) {
// Create a Send Invoice link with the context of the participant's order ID (a custom participant field)
switch ($objectName) {
case 'Participant':
switch ($op) {
case 'participant.selector.row':
$cid = $values['cid'];
$order_id = lg_get_order_id_by_pid($objectId);
//check if this participant is a student with a parent, for saving the email.
//if not, fall back to current contact record
$result = civicrm_api3('Relationship', 'get', [
'sequential' => 1,
'return' => "contact_id_b",
'relationship_type_id' => 1,
'contact_id_a' => $cid,
]);
$parent_id = $result['values'][0]['contact_id_b'];
if ($parent_id > 0) {
$cid = $parent_id;
}
$links[] = [
'name' => E::ts('Send Invoice'),
'title' => E::ts('Send Invoice'),
'url' => 'civicrm/activity/email/add',
'qs' => "action=add&reset=1&cid=$cid&selectedChild=activity&atype=3&order_id=$order_id",
];
break;
}
}
}
function lg_get_order_id_by_pid($pid) {
$result = civicrm_api3('Participant', 'get', array(
'sequential' => 1,
'return' => "custom_11",
'id' => $pid,
));
return $result['values'][0]['custom_11'];
}