|
Table of Contents
Goals and BackgroundThis 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 the section on Joomla within this article for a description of how to implement hooks in Joomla. See CRM/Utils/Hook.php for CiviCRM for the source code that invokes these hooks. Procedures for implementing hooks (for Drupal)All your hook implementations should be collected within one or more modules, so to begin create a module:
Procedures for implementing hooks (for Joomla)
Note on setting and getting custom field values in hooksFor setting and getting custom field values in hooks, you need to know the field ID of the custom field(s) you want to work with. The easiest place to find these IDs is in the civicrm_custom_field table in the database. You'll then access these fields as "custom_ID". So if you have a field holding a custom value whose ID in the civicrm_custom_field table is 34, you'll use "custom_34" to access it. Once you have the ID(s), you'll want to use the setValues and getValues functions in the CRM/Core/BAO/CustomValueTable.php file. Here are a couple of examples of their use: Setting values (on a Contribution object's custom fields): Getting values (from a Contribution's associated Contact object): hook_civicrm_preDescriptionThis 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. We suspect the pre hook 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. DefinitionParameters
Returns
Examplehook_civicrm_postDescriptionThis hook is called after a db write on some core objects. pre and post hooks are 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). DefinitionParameters
Returns
ExampleHere is a simple example that will send you an email whenever an INDIVIDUAL Contact is either Added, Updated or Deleted: Create a new folder called example_sendEmailOnIndividual in this directory /drupal_install_dir/sites/all/modules/civicrm/drupal/modules/ and then put the following two files in that directory (change the email addresses to yours). FILE #1 /drupal_install_dir/sites/all/modules/civicrm/drupal/modules/example_sendEmailOnIndividual/example_sendEmailOnIndividual.info FILE #2 /drupal_install_dir/sites/all/modules/civicrm/drupal/modules/example_sendEmailOnIndividual/example_sendEmailOnIndividual.module Once the files are in the directory, you need to login to Drupal admin, go to Modules and enable our new module and click Save. Now go and edit a contact and you should get an email! hook_civicrm_linksDescriptionThese hooks are used to inject UI into CiviCRM pages such as the Contact Summary page. Note: remember to use the string & url processing functions of your host framework ( url() and t() for Drupal ). DefinitionParameters
Returns
Examplehook_civicrm_validateDescriptionValidation of forms DefinitionParameters
Returnstrue if form validates successfully, otherwise array with error message strings ExampleBeginning in CiviCRM 3.2, from within this hook, you can also manipulate validation errors set by CiviCRM. For example, to unset a validation error triggered by CiviCRM: hook_civicrm_buildFormDescriptionThis hook is invoked when building a CiviCRM form. This hook should also DefinitionParameters
Examplehook_civicrm_postProcessDescriptionThis hook is invoked when a CiviCRM form is submitted. If the module has injected DefinitionParameters
Returns
Examplehook_civicrm_customDescriptionThis hook is called AFTER the db write on a custom table DefinitionParameters
Returns
Examplehook_civicrm_aclWhereClauseDescriptionThis hook is called when composing the ACL where clause to restrict visibility of contacts to the logged in user. NB: This function will not be called at all if the logged in user has access to the "edit all contacts" permission. DefinitionParameters
Returns
Examplehook_civicrm_aclGroupDescriptionThis hook is called when composing the ACL to restrict access to civicrm entities (civicrm groups, profiles and events). NOTE: In order to use this hook you must uncheck "View All Contacts" AND "Edit All Contacts" in Drupal Permissions for the user role you want to limit. You can then go into CiviCRM and grant permission to Edit or View "All Contacts" or "Certain Groups". See the Forum Topic at: http://forum.civicrm.org/index.php/topic,14595.0.html for more information. DefinitionParameters
Returns
ExampleCheck HRD Module hook_civicrm_dashboardDescriptionThis hook is called when rendering the dashboard page. This hook can be used to add content to the dashboard page. DefinitionParameters
Returns
ExampleAlso check Civitest Sample Module hook_civicrm_xmlMenuDescriptionThis hook is called when building CiviCRM's menu structure. You will need to visit <your_site>/civicrm/menu/rebuild&reset=1 to pick up your additions. DefinitionParameters
Returns
ExampleHere's how you can override an existing menu item. First create an XML file like this, and place it in the same folder as your hook implementation: <?xml version="1.0" encoding="iso-8859-1" ?> hook_civicrm_alterPaymentProcessorParamsDescriptionThis hook is called during the processing of a contribution after the payment processor has control, but just before the CiviCRM processor specific code starts a transaction with the back-end payments server (e.g., PayPal, Authorized.net, or Moneris). It allows you to modify the parameters passed to the back end so that you can pass custom parameters, or use features of your back-end that CiviCRM does not "know" about. DefinitionParameters
ReturnsExamplehook_civicrm_pageRunDescriptionThis hook is called before a CiviCRM page is rendered DefinitionParameters
Returns
hook_civicrm_copyDescriptionThis hook is called after a CiviCRM object (Event, ContributionPage, Profile) has been copied DefinitionParameters
Returns
hook_civicrm_tokensDescriptionThis hook is called to get all the tokens that can be used DefinitionParameters
Returns
hook_civicrm_tokenValuesDescriptionThis hook is called to get all the values for the tokens registered DefinitionParameters
Returns
hook_civicrm_customFieldOptionsDescriptionThis hook is called when CiviCRM needs to edit/display a custom field with options (select, radio, checkbox, adv multiselect) DefinitionParameters
Returns
ExampleThis syntax may be more convenient if you are a managing differing sets of options for different fields: hook_civicrm_searchTasksDescriptionThis hook is called to display the list of actions allowed after doing a contact search. This allows the module developer to inject additional actions or to remove existing actions. DefinitionParameters
Returns
Examplehook_civicrm_buildAmountDescriptionThis hook is called when building the amount structure for a Contribution or Event Page. It allows you to modify the set of radio buttons representing amounts for contribution levels and event registration fees. DefinitionParameters
Returns
Examplehook_civicrm_tabsDescriptionThis hook is called when composing the tabs to display when viewing a contact DefinitionParameters
Returns
Examplehook_civicrm_mailingGroupsDescriptionThis hook is called when composing a mailing. You can include / exclude other groups as needed. DefinitionParameters
Returns
Examplehook_civicrm_shortcutsDescriptionThis hook is obsoleted in CiviCRM v3.2.4 in favor of hook_civicrm_links ( For more details check hook_civicrm_links documentation ) hook_civicrm_summaryDescriptionThis hook is called when contact summary is rendered and you can add on top, below or replace summary with your own html content. DefinitionParameters
Examplehook_civicrm_contactListQueryDescriptionUse this hook to populate the list of contacts returned by Contact Reference custom fields. By default, Contact Reference fields will search on and return all CiviCRM contacts. If you want to limit the contacts returned to a specific group, or some other criteria - you can override that behavior by providing a SQL query that returns some subset of your contacts. The hook is called when the query is executed to get the list of contacts to display. DefinitionParameters
ExampleThis example limits contacts in my contact reference field lookup (custom field id=4) to a specific group (group id=5) hook_civicrm_membershipTypeValuesDescriptionThis hook is called when composing the array of membershipTypes and their cost during a membership registration (new or renewal). Note the hook is called on initial page load and also reloaded after submit (PRG pattern). You can use it to alter the membership types when first loaded, or after submission (for example if you want to gather data in the form and use it to alter the fees). DefinitionParameters
ExamplesGive a 50% discount to some memberships in the sample data Modify specific fee values hook_civicrm_alterMailParamsDescriptionThis hook is called when an email is about to be sent by CiviCRM. DefinitionParameters
Details
hook_civicrm_caseSummaryDescriptionThis hook is called when the manage case screen is displayed. It allows the injection of label/value pairs which are rendered inside divs underneath the existing summary table. DefinitionParameters
Returns
Examplehook_civicrm_configDescriptionThis hook is called soon after the CRM_Core_Config object has ben initialized. You can use this hook to modify the config object and hence behavior of CiviCRM dynamically. DefinitionParameters
Examplehook_civicrm_navigationMenuDescriptionThis hook is called after the menus are rebuild. You can use this hook to add new menu, add children to new menu and get the list of menu items for any parent. DefinitionParameters
Attributes of the menu : 1. label : Navigation Title 2. Name : Internal Name 3. url : url in case of custom navigation link 4. permission : comma separated Permissions for menu item 5. operator : Permission Operator ( AND/OR) 6. seperator : If separator needs to be added after this menu item. 7. parentID : Parent navigation item, used for grouping 8. navID : ID of the menu 9. active : is active ? Examplehook_civicrm_mergeDescriptionThis hook allows modification of the data used to perform merging of duplicates. This can be useful if your custom module has added its own tables related to CiviCRM contacts. AvailabilityThis hook was first available in CiviCRM 3.2.3. DefinitionParameters
DetailsThe contents of $data will vary based on the $type of data being passed:
Examplehook_civicrm_exportDescriptionThis hook allows to manipulate or change the output of CSV during export. AvailabilityThis hook was first available in CiviCRM 3.2.4 DefinitionParameters
DetailsExample |
CiviCRM hook specification
Skip to end of metadata
Go to start of metadata
Labels:
