E-mail
|
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)Plugins in the civicrm groups should be used to access hooks in Joomla. Information on Joomla plugin development can be found at http://docs.joomla.org/Plugin. Joomla plugins implement the observer design pattern. Hook plugins should be placed in the civicrm plugin group in a subfolder with the same name as the plugin.. Once created plugins may be packaged and installed with the Joomla installer or the files can be placed in the appropriate folder and installed with the discover method. A simple example is given below. It consists of two file tabs.php and tabs.xml along with the blank index.html file which is considered good Joomla coding practice. Tabs.php: Tabs.xml You can make plugins that include multiple hooks or you can make separate plugins. What is appropriate will depend on the application. Note on setting and getting custom field values in hooks
For 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): Note that custom field values may not always be available when you might expect. For instance, you can't retrieve custom field values in the 'create' operation in the _pre and _post hooks, because the custom field values haven't been stored yet. However, you can retrieve values in the 'edit' operation. Form related hookshook_civicrm_validateDescriptionValidation of forms DefinitionParameters
Returnstrue if form validates successfully, otherwise array with input field names as keys and error message strings as values 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 be used to set the default values of a form element DefinitionParameters
ReturnsExample
hook_civicrm_postProcessDescriptionThis hook is invoked when a CiviCRM form is submitted. If the module has injected This hook is not called when using the API, only when using the regular forms. If you want to have an action that is triggered no matter if it's a form or an API, use the pre and post hooks instead. DefinitionParameters
Returns
ExampleDatabase related hookshook_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_customDescriptionThis hook is called AFTER the db write on a custom table DefinitionParameters
Returns
Examplehook_civicrm_copyDescriptionThis hook is called after a CiviCRM object (Event, ContributionPage, Profile) has been copied DefinitionParameters
Returns
Permission related hookshook_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 GUI related hookshook_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_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, which is used to render urls in CiviCRM. This hook should be used when you want to register your custom module url's in CiviCRM. You will need to visit <your_site>/civicrm/menu/rebuild?reset=1 to pick up your additions. Note: If you just want to register url in top Navigation, you should use hook_civicrm_navigationMenu 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_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_pageRunDescriptionThis hook is called before a CiviCRM page is rendered. Note that this does not execute on every CiviCRM page in the general sense. CiviCRM's pages are classified as either 'Forms' or 'Pages', and this only runs on pages classified as 'Pages'. If you are not sure if a particular page is a Page, test it by adding some temporary debug code to /CRM/Utils/Hook.php 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_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_summaryActions (introduced in 4.1)DescriptionThis hook allows User to customize context menu Actions on Contact Summary Page. DefinitionParameters
Examplehook_civicrm_searchTasksDescriptionThis hook is called to display the list of actions allowed after doing a search. This allows the module developer to inject additional actions or to remove existing actions. DefinitionParameters
Returns
Examplehook_civicrm_searchColumnsDescriptionThis hook is called after a search is done. This allows the developer to modify the headers and/or the values that are displayed as part of this search. The BIGGEST drawback with this hook is that you may need to modify the result template to include your fields. The result files are CRM/{Contact,Contribute,Member,Event…}/Form/Selector.tpl. However, if you use the same number of columns, you can overwrite the existing columns with the values that you want displayed. This is a HACK, but avoids template modification. 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_tokensDescriptionThis hook is called to get all the tokens that can be used Definitionhook_civicrm_tokens( &$tokens )Parameters
Returns
hook_civicrm_alterMailingLabelParamsDescriptionThis hook is called to alter the parameters used to generate mailing labels. To be added in CiviCRM 4.1 or later. DefinitionParameters
@param array $args an array of the args for the tcpdf MultiCell api call with the variable names below converted into string keys
(ie $w become 'w' as the first key for $args).
If ishtml is set true, then a subset of the args will be passed to the tcdpdf writeHTMLCell api call instead.
float $w Width of cells. If 0, they extend up to the right margin of the page.
float $h Cell minimum height. The cell extends automatically if needed.
string $txt String to print
mixed $border Indicates if borders must be drawn around the cell block. The value can
be either
a number:
0: no border (default)
1: frame or
a string containing some or all of the following characters (in any order):
L: left
T: top
R: right
B: bottom
string $align Allows to center or align the text. Possible values are:
L or empty string: left align
C: center
R: right align
J: justification (default value when $ishtml=false)
int $fill Indicates if the cell background must be painted (1) or transparent (0). Default value: 0.
int $ln Indicates where the current position should go after the call. Possible values are:
0: to the right
1: to the beginning of the next line DEFAULT
2: below
float $x x position in user units
float $y y position in user units
boolean $reseth if true reset the last cell height (default true).
int $stretch stretch carachter mode:
0 = disabled
1 = horizontal scaling only if necessary
2 = forced horizontal scaling
3 = character spacing only if necessary
4 = forced character spacing
boolean $ishtml set to true if $txt is HTML content (default = false).
boolean $autopadding if true, uses internal padding and automatically adjust it to account for line width.
float $maxh maximum height. It should be >= $h and less then remaining space to the bottom of the page,
or 0 for disable this feature. This feature works only when $ishtml=false.
NB: not all html tags are supported, not all style parameters are supported, and improperly constructed html tends to lead to errors and crashes. Returns
Examplehook_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_tokenValuesDescriptionThis hook is called to get all the values for the tokens registered. For a good overview of usage, see lobo's blog. DefinitionParameters
Returns
hook_civicrm_mailingGroupsDescriptionThis hook is called when composing a mailing. You can include / exclude other groups as needed. DefinitionParameters
Returns
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_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:
Example 1 - Modifying the queryExample 2 - Using Drupal to update custom tableshook_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
DetailsExamplehook_civicrm_emailProcessorDescriptionThis hook is called AFTER EACH email has been processed by the script bin/EmailProcessor.php DefinitionParameters
Returns
AvailabilityThis hook was first available in CiviCRM 3.4.0 hook_civicrm_importDescriptionThis hook is called after contacts have been imported into the system, and before the temp import table has been destroyed. It can be used to take custom action on the imported records or handle special columns in the import file. It currently is only applicable to contact import, but in future versions may extend to other objects. DefinitionParameters
Returns
Availability
Examplehook_civicrm_alterAPIPermissionsDescriptionThis hook is called when API 3 permissions are checked and can alter the $permissions structure from CRM/Core/DAO/.permissions.php (as well as the API $params array) based on the $entity and $action (or unconditionally). Note that if a given entity/action permissions are unset, the default ‘access CiviCRM’ permission is enforced. DefinitionParameters
Returns
Availability
Examplehook_civicrm_dupeQueryDescriptionThis hook is called during the dedupe lookup process, and can be used to alter the parameters and queries used to determine if two contacts are duplicates. The dedupe mechanism is triggered in four places:
Using the hook parameters, you can isolate how and when your rule modifications are used. Note that this hook depends upon the existence of a dedupe rule created in the interface in order for it to be called. It works by allowing access to the queries constructed by an interface-create rule.You can modify or completely replace the query or queries that would be run at the point the hook is called, as illustrated below. You cannot define rule groups with this hook. DefinitionParameters
Returns
Availability
ExampleThe example below rewrites the queries for the individual rule group entitled "My Dedupe Rule Group Name" when performing site-wide deduping. It combines six fields into a single query, thus speeding up the duplicate search process. hook_civicrm_buildStateProvinceForCountryDescriptionThis hook is called during the ajax callback that is used to build the options that display in the State/Province select widget for a specific country, and can be used to alter the list of State/Province options for particular countries. DefinitionParameters
Returns
Availability
ExampleThe example below reorders the Irish State list so that Dublin is at the top of the list (by default, Dublin would be placed in the list in alphabetical order. Obsolete hookshook_civicrm_shortcutsDescriptionThis hook is obsoleted in CiviCRM v3.2.4 in favor of hook_civicrm_links ( For more details check hook_civicrm_links documentation ) |
Labels