CiviCRM hook specification - CiviCRM Documentation

Goals and Background

This documents how to extend CiviCRM to meet your needs. We are extending CiviCRM in a very similar manner to Drupal, primarily because based on our experience with Drupal's extension architecture, we think it is clean and non-intrusive, yet incredibly powerful. For a simple example module check civitest module

See Drupal hook documentation for a description of how hooks are implemented.

See CRM/Utils/Hook.php for CiviCRM for the source code that invokes these hooks.

hook_civicrm_pre

Description

This hook is called before a db write on some core objects. This hook does not allow the abort of the operation, use a form hook instead.

Note that Drupal does not support pre and post hooks. We suspect the pre and post hooks will be useful for developers building more complex applications and need to perform operations before CiviCRM takes action. This is very applicable when you need to maintain foreign key constraints etc (when deleting an object, the child objects have to be deleted first). Another good use for the pre hook is to see what is changing between the old and new data.

Definition

hook_civicrm_pre( $op, $objectName, $objectId, &$objectRef )

Availability

CiviCRM <version?>

Parameters

$op - operation being performed with CiviCRM object. Can have the following values:
- 'view' : The CiviCRM object is going to be displayed
- 'create' : The CiviCRM object is created (or contacts are being added to a group)
- 'edit' : The CiviCRM object is edited
- 'delete' : The CiviCRM object is being deleted (or contacts are being removed from a group)

$objectName - can have the following values:
- 'Individual'
- 'Household'
- 'Organization'
- 'Group'
- 'GroupContact'
- 'Relationship'
- 'Contribution'
- 'Profile' (while this is not really an object, people have expressed an interest to perform an action when a profile is created/edited)
- 'Membership'
- 'Participant'
- 'UFMatch' (when an object is linked to a CMS user record, at the request of GordonH. A UFMatch object is passed for both the pre and post hooks)

$objectId the object id if available
$params the parameters used for object creation / editing

Returns

None

Example

hook_civicrm_post

Description

This hook is called after a db write on some core objects.

Note that Drupal does not support pre and post hooks. We suspect the pre and post hooks will be useful for developers building more complex applications and need to perform operations before CiviCRM takes action. This is very applicable when you need to maintain foreign key constraints etc (when deleting an object, the child objects have to be deleted first).

Definition

hook_civicrm_post( $op, $objectName, $objectId, &$objectRef )

Availability

CiviCRM <version?>

Parameters

$op - operation being performed with CiviCRM object. Can have the following values:
- 'view' : The CiviCRM object is going to be displayed
- 'create' : The CiviCRM object is created (or contacts are being added to a group)
- 'edit' : The CiviCRM object is edited
- 'delete' : The CiviCRM object is being deleted (or contacts are being removed from a group)

$objectName - can have the following values:
- 'Individual'
- 'Household'
- 'Organization'
- 'Group'
- 'GroupContact'
- 'Relationship'
- 'Contribution'
- 'Profile' (while this is not really an object, people have expressed an interest to perform an action when a profile is created/edited)
- 'Membership'
- 'Participant'
- 'UFMatch' (when an object is linked to a CMS user record, at the request of GordonH. A UFMatch object is passed for both the pre and post hooks)

$objectId - the unique identifier for the object
$objectRef - the reference to the object if available

Returns

None

Example

hook_civicrm_links

Description

These hooks are used to inject UI into CiviCRM pages such as the Contact Summary page. They are first implemented in CiviCRM version 1.5.

Note: remember to use the string & url processing functions of your host framework ( url() and t() for Drupal ).

Definition

hook_civicrm_links( $op, $objectName, $objectId )

Availability

CiviCRM <version?>

Parameters

*$op - can have the following values:

- 'view.activityLink' : CiviCRM is about to render activity links for this object.
$objectName- can have the following values:
- 'Contact'
- 'Group'
- 'GroupContact'
- 'Relationship'
- 'Contribution'

$objectId -the CiviCRM internal ID of the object (a contact ID, group ID, etc.).

Returns

Example

/**
 * This hook retrieves links from other modules and injects it into
 * CiviCRM forms
 *
 * @param string $op         the type of operation being performed
 * @param string $objectName the name of the object
 * @param int    $objectId   the unique identifier for the object
 *
 * @return array|null        an array of arrays, each element is a tuple consisting of url, img, title
 *
 * @access public
 */
function MODULENAME_civicrm_links( $op, $objectName, $objectId ) {
  $links = array();
  switch ($objectName) {
    case 'Contact':
      switch ($op) {
        case 'view.activityLinks':
          // Adds some links to the contact-view page.
          // You may also want to test for some condition here.
          $links[] =
            array('url' => "/mymodule/signup/$objectId",
                  'img' => "/image/cute-lil-icon.gif",
                  'title' => "Sign Up For Lottery");
          $links[] =
            array('url' => "/mymodule/bug_letter/$objectId",
                  'img' => "/image/big-icon.gif",
                  'title' => "Send Contact The Bug Letter");
          break;
        case 'tabs.contact.activity':
          // Adds a new tab.
          $links[] = array(
            'id' => 'Mymoduleactions',
            'title' => 'My Module Actions',
            'url' => 'mymodule/civicrm/actions/'. $objectId,
            'weight' => 10,
          );
          break;
      }
  }
  return $links;
}

hook_civicrm_validate

Description

Validation of forms

Definition

hook_civicrm_validate( $formName, &$fields, &$files, &$form )

Availability

CiviCRM 2.0+

Parameters

$formName - Name of the form being validated, you will typically switch off this value.
$fields - Array of name value pairs for all 'POST'ed form values
$files - Array of file properties as sent by PHP POST protocol
$form - Reference to the civicrm form object. This is useful if you want to retrieve any values that we've constructed in the form

Returns

true if form validates successfully, otherwise array with error message strings

Example

function MODULENAME_civicrm_validate( $formName, &$fields, &$files, &$form ) {
    // sample implementation
    $errors = array( );
    if ( $formName == 'CRM_Contact_Form_Edit' ) {
       // ensure that external identifier is present and valid
       $externalID = CRM_Utils_Array::value( 'external_identifier', $fields );
       if ( ! $externalID ) {
          $errors['external_identifier'] = ts( 'External Identifier is a required field' );
       } else if ( ! myCustomValidatorFunction( $externalID ) ) {
          $errors['external_identifier'] = ts( 'External Identifier is not valid' );
       }
    }
    return empty( $errors ) ? true : $errors;

}

hook_civicrm_buildForm

Description

This hook is invoked when building a CiviCRM form. This hook should also
be used to set the default values of a form element

Definition

hook_civicrm_buildForm( $formName, &$form )

Availability

CiviCRM 2.1+

Parameters

string $formName - the name of the form
object $form - reference to the form object
Returns

Example

hook_civicrm_postProcess

Description

This hook is invoked when a CiviCRM form is submitted. If the module has injected
any form elements, this hook should save the values in the database.

Definition

hook_civicrm_postProcess ( $formName, &$form)

Availability

CiviCRM 2.1+

Parameters

string $formName - the name of the form
object $form - reference to the form object

Returns

null - the return value is ignored
Example

hook_civicrm_custom

Description

This hook is called before a db write on a custom table

Definition

hook_civicrm_custom( $op, $groupID, $entityID, &$params )

Availability

CiviCRM 2.1+

Parameters

string $op - the type of operation being performed
string $groupID - the custom group ID
object $entityID - the entityID of the row in the custom table
array $params - the parameters that were sent into the calling function

Returns

null - the return value is ignored

Example

/**
 * This example generates a custom contact ID (year + number, ex: 20080000001)
 */

function MODULENAME_civicrm_custom( $op, $groupID, $entityID, &$params ) {
    if ( $op != 'create' && $op != 'edit' ) {
        return;
    }
    
    if ($groupID == 1) {
        $needs_update = false;
        $tableName = CRM_Core_DAO::getFieldValue( 'CRM_Core_DAO_CustomGroup',
                                                      $groupID,
                                                      'table_name' );


        $sql = "SELECT member_id_4 FROM $tableName WHERE entity_id = $entityID";
        $dao = CRM_Core_DAO::executeQuery( $sql, CRM_Core_DAO::$_nullArray );
            
        if (! $dao->fetch()) {
            $needs_update = true;
        }
            
        // Value may also be empty. i.e. delete the value in the interface to reset the field.
        if (! $dao->member_id_4) {
            $needs_update = true;
        }
            
        if ($needs_update) {                   
                $member_id = date('Y') . sprintf('%07d', $entityID);
                    
                $sql = "UPDATE $tableName SET member_id_4 = $member_id WHERE entity_id = $entityID";
                CRM_Core_DAO::executeQuery( $sql, CRM_Core_DAO::$_nullArray );
        }
    }
}

hook_civicrm_aclWhereClause

Description

This hook is called when composing the ACL where clause to restrict
visibility of contacts to the logged in user

Definition

Availability

CiviCRM 2.1+

Parameters

$type - type of permission needed
array $tables - (reference ) add the tables that are needed for the select clause
array $whereTables - (reference ) add the tables that are needed for the where clause
int $contactID - the contactID for whom the check is made
string $where - the currrent where clause

Returns

null - the return value is ignored

Example

hook_civicrm_aclGroup

Description

Definition

hook_civicrm_aclGroup( $type, $contactID, $tableName, &$allGroups, &$currentGroups )

Goals and Background

hook_civicrm_pre

Description

Definition

Availability

Parameters

Returns

Example

hook_civicrm_post

Description

Definition

Availability

Parameters

Returns

Example

hook_civicrm_links

Description

Definition

Availability

Parameters

Returns

Example

hook_civicrm_validate

Description

Definition

Availability

Parameters

Returns

Example

hook_civicrm_buildForm

Description

Definition

Availability

Parameters

Returns

Example

hook_civicrm_postProcess

Description

Definition

Availability

Parameters

Returns

Example

hook_civicrm_custom

Description

Definition

Availability

Parameters

Returns

Example

hook_civicrm_aclWhereClause

Description

Definition

Availability

Parameters

Returns

Example

hook_civicrm_aclGroup

Description

Definition

Availability

Parameters

Returns

Example

hook_civicrm_xmlMenu

Description

Definition

Availability

Parameters

Returns

Example

hook_civicrm_dashboard

Description

Definition

Availability

Parameters

Returns

Example