diff --git a/docs/hooks/hook_civicrm_links.md b/docs/hooks/hook_civicrm_links.md
index 796c5a9d86a714a45705678c0822f681ec904c75..f38e637958da5085b1bcfda081e377629755a1a3 100644
--- a/docs/hooks/hook_civicrm_links.md
+++ b/docs/hooks/hook_civicrm_links.md
@@ -7,145 +7,144 @@ include 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.
Note: remember to use the string processing functions of your host
-framework ( ts() for CiviCRM extensions, t() for Drupal modules, etc).
-
-**This hook has had major changes for 4.5
-([CRM-13434](http://issues.civicrm.org/jira/browse/CRM-13434)****).
-Please [see the 4.4
-documentation](https://wiki.civicrm.org/confluence/display/CRMDOC44/hook_civicrm_links) for
-previous usage of this hook.\
-**
+framework ( `ts()` for CiviCRM extensions, `t()` for Drupal modules, etc).
## Definition
- hook_civicrm_links( $op, $objectName, $objectId, &$links, &$mask, &$values )
+```php
+hook_civicrm_links($op, $objectName, $objectId, &$links, &$mask, &$values)
+```
## Parameters
-- $op = the context in which the links appear, such as
- 'view.contact.activity', 'survey.dashboard.row', or
- 'pdfFormat.manage.action'
-- $objectName = the entity the links relate to (or null if $op ==
- 'create.new.shorcuts')
-- $objectId = the CiviCRM internal ID of the entity (or null if $op
- == 'create.new.shorcuts')
-- $links = the links array to modify in-place\
- each item in the array may have:
- - name: the link text
- - url: the link URL base path (like 'civicrm/contact/view', and
- fillable from $values)
- - qs: the link URL query parameters to be used by sprintf() with
- $values (like 'reset=1&cid=%%id%%' when $values['id'] is the
+- string `$op` - the context in which the links appear, such as
+ `view.contact.activity`, `survey.dashboard.row`, or
+ `pdfFormat.manage.action`
+
+- string `$objectName` - the entity the links relate to (or `NULL` if `$op` is
+ `create.new.shorcuts`)
+
+- int `$objectId` - the CiviCRM internal ID of the entity (or `NULL` if `$op`
+ is `create.new.shorcuts`)
+
+- array `$links` - the links to modify in place
+
+ each item in the array may have:
+ - `name`: the link text
+ - `url`: the link URL base path (like `civicrm/contact/view`, and
+ fillable from `$values`)
+ - `qs`: the link URL query parameters to be used by sprintf() with
+ $values (like `reset=1&cid=%%id%%` when `$values['id']` is the
contact ID)
- - title (optional): the text that appears when hovering over the
+ - `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
+ - `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>
+ - `ref` (optional, recommended): a CSS class to apply to the `<a>`
tag.
- - class (optional): Any other CSS classes to apply to the <a>
+ - `class` (optional): Any other CSS classes to apply to the `<a>`
tag (e.g. no-popup).
-- $mask = a bitmask that will fiter $links
-- $values = values to fill $links['url'], $links['qs'], and/or
- $links['extra'] using sprintf()-style percent signs
-
-## Returns
-
-- null
-
-## Example
-
- function MODULENAME_civicrm_links( $op, $objectName, $objectId, &$links, &$mask, &$values ) {
- $myLinks = array();
- switch ($objectName) {
- case 'Contact':
- switch ($op) {
- case 'view.contact.activity':
- // Adds a link to the main tab.
- $links[] = array(
- 'name' => ts('My Module Actions'),
- 'url' => 'mymodule/civicrm/actions/%%myObjId%%',
- 'title' => 'New Thing',
- );
- $values['myObjId'] = $objectId;
- break;
-
- case 'contact.selector.row':
- // Add a similar thing when a contact appears in a row
- $links[] = array(
- 'name' => ts('My Module'),
- 'url' => 'mymodule/civicrm/actions/%%myObjId%%',
- 'title' => 'New Thing',
- 'qs' => 'reset=1&tid=%%thingId%%',
- );
- $values['myObjId'] = $objectId;
- $values['thingId'] = 'mything';
- break;
-
- case 'create.new.shorcuts':
- // add link to create new profile
- $links[] = array(
- 'url' => '/civicrm/admin/uf/group?action=add&reset=1',
- 'name' => ts('New Profile'), // old extensions using 'title' will still work
- );
- break;
- }
- }
- return $myLinks;
- }
-
-
+- int `$mask` - a bitmask that will fiter `$links`
+- array `$values` - values to fill `$links['url']`, `$links['qs']`, and/or
+ `$links['extra']` using `sprintf()`-style percent signs
-**Adding contextual links to the rows of a contact's Events tab and Find
-Participants search result**
-
- //part of a native Civi extension, not CMS-specfic
-
- 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', array(
- 'sequential' => 1,
- 'return' => "contact_id_b",
- 'relationship_type_id' => 1,
- 'contact_id_a' => $cid,
- ));
+## Returns
- $parent_id = $result['values'][0]['contact_id_b'];
+- `NULL`
+
+## Examples
+
+```php
+function MODULENAME_civicrm_links( $op, $objectName, $objectId, &$links, &$mask, &$values ) {
+ $myLinks = array();
+ switch ($objectName) {
+ case 'Contact':
+ switch ($op) {
+ case 'view.contact.activity':
+ // Adds a link to the main tab.
+ $links[] = array(
+ 'name' => ts('My Module Actions'),
+ 'url' => 'mymodule/civicrm/actions/%%myObjId%%',
+ 'title' => 'New Thing',
+ );
+ $values['myObjId'] = $objectId;
+ break;
+
+ case 'contact.selector.row':
+ // Add a similar thing when a contact appears in a row
+ $links[] = array(
+ 'name' => ts('My Module'),
+ 'url' => 'mymodule/civicrm/actions/%%myObjId%%',
+ 'title' => 'New Thing',
+ 'qs' => 'reset=1&tid=%%thingId%%',
+ );
+ $values['myObjId'] = $objectId;
+ $values['thingId'] = 'mything';
+ break;
+
+ case 'create.new.shorcuts':
+ // add link to create new profile
+ $links[] = array(
+ 'url' => '/civicrm/admin/uf/group?action=add&reset=1',
+ 'name' => ts('New Profile'), // old extensions using 'title' will still work
+ );
+ break;
+ }
+ }
+ return $myLinks;
+}
+```
+
+Adding contextual links to the rows of a contact's Events tab and Find
+Participants search result
+
+```php
+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', array(
+ 'sequential' => 1,
+ 'return' => "contact_id_b",
+ 'relationship_type_id' => 1,
+ 'contact_id_a' => $cid,
+ ));
- if ($parent_id > 0) {
- $cid = $parent_id;
- }
+ $parent_id = $result['values'][0]['contact_id_b'];
- $links[] = array(
- 'name' => ts('Send Invoice'),
- 'title' => ts('Send Invoice'),
- 'url' => 'civicrm/activity/email/add',
- 'qs' => "action=add&reset=1&cid=$cid&selectedChild=activity&atype=3&order_id=$order_id"
- );
- break;
+ if ($parent_id > 0) {
+ $cid = $parent_id;
}
- }
- }
- 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'];
- }
\ No newline at end of file
+ $links[] = array(
+ 'name' => ts('Send Invoice'),
+ 'title' => 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'];
+}
+```
diff --git a/docs/hooks/hook_civicrm_mailingGroups.md b/docs/hooks/hook_civicrm_mailingGroups.md
index e447cb09c73b4c95593fc2eb76a278ecf532fad2..f7d11b0a8e4dd39d8022ca6d55064bf42a3262de 100644
--- a/docs/hooks/hook_civicrm_mailingGroups.md
+++ b/docs/hooks/hook_civicrm_mailingGroups.md
@@ -7,25 +7,31 @@ other groups as needed.
## Definition
- hook_civicrm_mailingGroups( &$form, &$groups, &$mailings )
+```php
+hook_civicrm_mailingGroups(&$form, &$groups, &$mailings)
+```
## Parameters
-- $form - the form object for which groups / mailings being displayed
-- $groups - the list of groups being included / excluded
-- $mailings - the list of mailings being included / excluded
+- object `$form` - the form object for which groups / mailings being displayed
+
+- array `$groups` - the list of groups being included / excluded
+
+- array `$mailings` - the list of mailings being included / excluded
## Returns
-- null - the return value is ignored
+- `NULL` - the return value is ignored
## Example
- function civitest_civicrm_mailingGroups( &$form, &$groups, &$mailings ) {
+```php
+function civitest_civicrm_mailingGroups( &$form, &$groups, &$mailings ) {
- // unset group id 4
- unset( $groups[4] );
+ // unset group id 4
+ unset( $groups[4] );
- // add a fictitious mailing
- $mailings[1] = 'This mailing does not exist';
- }
\ No newline at end of file
+ // add a fictitious mailing
+ $mailings[1] = 'This mailing does not exist';
+}
+```
diff --git a/docs/hooks/hook_civicrm_managed.md b/docs/hooks/hook_civicrm_managed.md
index b45ebcce0929e8b8b93d9b44af4cf8ac5095f8ab..d1e053a3dcb3381315ebf047f38bf8c40701b8df 100644
--- a/docs/hooks/hook_civicrm_managed.md
+++ b/docs/hooks/hook_civicrm_managed.md
@@ -13,40 +13,50 @@ Installation](http://civicrm.org/blogs/totten/api-and-art-installation).
## Definition
- hook_civicrm_managed(&$entities)
+```php
+hook_civicrm_managed(&$entities)
+```
## Parameters
-- array $entities - the list of entity declarations; each declaration
- is an array with these following keys:\
- - 'module': string; for module-extensions, this is the
- fully-qualifed name (e.g. "*com.example.mymodule*"); for Drupal
- modules, the name is prefixed by "drupal" (e.g.
- *"drupal.mymodule*")
- - 'name': string, a symbolic name which can be used to track this
+- array `$entities` - the list of entity declarations; each declaration
+ is an array with these following keys:
+
+ - string `module` - for module-extensions, this is the
+ fully-qualifed name (e.g. `com.example.mymodule`); for Drupal
+ modules, the name is prefixed by `drupal` (e.g.
+ `drupal.mymodule`)
+
+ - string `name` - a symbolic name which can be used to track this
entity (*Note: Each module creates its own namespace*)
- - 'entity': string, an entity-type supported by the [CiviCRM
+
+ - string `entity` - an entity-type supported by the [CiviCRM
API](https://wiki.civicrm.org/confluence/display/CRMDOC/API+Reference) (*Note: this
currently must be an entity which supports the 'is_active'
property*)
- - 'params': array, the entity data as supported by the [CiviCRM
+
+ - array `params` - the entity data as supported by the [CiviCRM
API](https://wiki.civicrm.org/confluence/display/CRMDOC/API+Reference)
- - 'update' (**v4.5+**): string, a policy which describes when to
+
+ - string `update` - a policy which describes when to
update records
- - 'always' (**default**): always update the managed-entity
- record; changes in $entities will override any local
+
+ - `always` (**default**): always update the managed-entity
+ record; changes in `$entities` will override any local
changes (eg by the site-admin)
- - 'never': never update the managed-entity record; changes
+ - `never`: never update the managed-entity record; changes
made locally (eg by the site-admin) will override changes in
- $entities
- - 'cleanup' (**v4.5+**): string, a policy which describes whether
- to cleanup the record when it becomes orphaned (ie when
- $entities no longer references the record)\
- - 'always' (**default**): always delete orphaned records
- - 'never': never delete orphaned records
- - 'unused': only delete orphaned records if there are no other
+ `$entities`
+
+ - string `cleanup` - a policy which describes whether
+ to cleanup the record when it becomes orphaned (i.e. when
+ $entities no longer references the record)
+
+ - `always` (**default**): always delete orphaned records
+ - `never`: never delete orphaned records
+ - `unused`: only delete orphaned records if there are no other
references to it in the DB. (This is determined by calling
- the API's "getrefcount" action.)
+ the API's `getrefcount` action.)
## Returns
@@ -54,21 +64,23 @@ Installation](http://civicrm.org/blogs/totten/api-and-art-installation).
## Example
- /**
- * Declare a report-template which should be activated whenever this module is enabled
- */
- function modulename_civicrm_managed(&$entities) {
- $entities[] = array(
- 'module' => 'com.example.modulename',
- 'name' => 'myreport',
- 'entity' => 'ReportTemplate',
- 'params' => array(
- 'version' => 3,
- 'label' => 'Example Report',
- 'description' => 'Longish description of the example report',
- 'class_name' => 'CRM_Modulename_Report_Form_Sybunt',
- 'report_url' => 'mymodule/mysbunt',
- 'component' => 'CiviContribute',
- ),
- );
- }
\ No newline at end of file
+```php
+/**
+ * Declare a report-template which should be activated whenever this module is enabled
+ */
+function modulename_civicrm_managed(&$entities) {
+ $entities[] = array(
+ 'module' => 'com.example.modulename',
+ 'name' => 'myreport',
+ 'entity' => 'ReportTemplate',
+ 'params' => array(
+ 'version' => 3,
+ 'label' => 'Example Report',
+ 'description' => 'Longish description of the example report',
+ 'class_name' => 'CRM_Modulename_Report_Form_Sybunt',
+ 'report_url' => 'mymodule/mysbunt',
+ 'component' => 'CiviContribute',
+ ),
+ );
+}
+```
diff --git a/docs/hooks/hook_civicrm_membershipTypeValues.md b/docs/hooks/hook_civicrm_membershipTypeValues.md
index e46f9e55a1b1567a296daec50e4b8220f15fe12e..29c59fdc42840faabdec5f180bcd794b74abf44f 100644
--- a/docs/hooks/hook_civicrm_membershipTypeValues.md
+++ b/docs/hooks/hook_civicrm_membershipTypeValues.md
@@ -2,44 +2,49 @@
## Description
-This 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
+This hook is called when composing the array of membership types and
+their costs during a membership registration (new or renewal). Note the
+hook is called on initial page load and also reloaded after submit ([PRG
+pattern](https://en.wikipedia.org/wiki/Post/Redirect/Get)). 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).
## Definition
- hook_civicrm_membershipTypeValues( &$form, &$membershipTypeValues ) {
+```php
+hook_civicrm_membershipTypeValues( &$form, &$membershipTypeValues ) {
+```
## Parameters
-- $form the form object that is presenting the page
-- $membershipTypeValues the array of membership types and their
- amount
+- object `$form` - the form object that is presenting the page
+- array `$membershipTypeValues` - the membership types and their amounts
## Examples
Give a 50% discount to some memberships in the sample data
- function civitest_civicrm_membershipTypeValues( &$form, &$membershipTypeValues ) {
- $membershipTypeValues[1]['name'] = 'General (50% discount)';
- $membershipTypeValues[1]['minimum_fee'] = '50.00';
+```php
+function civitest_civicrm_membershipTypeValues( &$form, &$membershipTypeValues ) {
+ $membershipTypeValues[1]['name'] = 'General (50% discount)';
+ $membershipTypeValues[1]['minimum_fee'] = '50.00';
- $membershipTypeValues[2]['name'] = 'Student (50% discount)';
- $membershipTypeValues[2]['minimum_fee'] = '25.00';
- }
+ $membershipTypeValues[2]['name'] = 'Student (50% discount)';
+ $membershipTypeValues[2]['minimum_fee'] = '25.00';
+}
+```
Modify specific fee values
- function mymodule_civicrm_membershipTypeValues( &$form, &$membershipTypeValues ) {
- foreach ( $membershipTypeValues as &$values) {
- if ( $values['name'] == 'General') {
- $values['minimum_fee'] = "5.55";
- }
- if ( $values['name'] == 'Student') {
- $values['minimum_fee'] = "2.22";
- }
- }
- }
\ No newline at end of file
+```php
+function mymodule_civicrm_membershipTypeValues(&$form, &$membershipTypeValues) {
+ foreach ($membershipTypeValues as &$values) {
+ if ($values['name'] == 'General') {
+ $values['minimum_fee'] = "5.55";
+ }
+ if ($values['name'] == 'Student') {
+ $values['minimum_fee'] = "2.22";
+ }
+ }
+}
+```
diff --git a/docs/hooks/hook_civicrm_merge.md b/docs/hooks/hook_civicrm_merge.md
index e8edebdfd04d53eeb5356585f8efb89b3414f5c0..4523b236338442fbe6068065c863246429a4db41 100644
--- a/docs/hooks/hook_civicrm_merge.md
+++ b/docs/hooks/hook_civicrm_merge.md
@@ -12,121 +12,131 @@ This hook was first available in CiviCRM 3.2.3.
## Definition
- hook_civicrm_merge ( $type, &$data, $mainId = NULL, $otherId = NULL, $tables = NULL )
+```php
+hook_civicrm_merge($type, &$data, $mainId = NULL, $otherId = NULL, $tables = NULL)
+```
## Parameters
-- $type the type of data being passed
- (cidRefs|eidRefs|relTables|sqls)
-- $data the data, which depends on the value of $type (see Details)
-- $mainId contact_id of the contact that survives the merge (only
- when $type == 'sqls')
-- $otherId contact_id of the contact that will be absorbed and
- deleted (only when $type == 'sqls')
-- $tables when $type is "sqls", an array of tables as it may have
+- string `$type` - the type of data being passed
+ (`cidRefs`, `eidRefs`, `relTables`, or `sqls`)
+- array `$data` - the data, which depends on the value of `$type` (see Details)
+- int `$mainId` - ID of the contact that survives the merge (only
+ when `$type` is `sqls`)
+- int `$otherId` - ID of the contact that will be absorbed and
+ deleted (only when `$type` is `sqls`)
+- array `$tables` - when `$type` is `sqls`, an array of tables as it may have
been handed to the calling function
## Details
-The contents of $data will vary based on the $type of data being
+The contents of `$data` will vary based on the `$type` of data being
passed:
-- 'relTables':
- - an array of tables used for asking user which elements to merge,
- as used at civicrm/contact/merge; each table in the array has
- this format:
+- `relTables`:
+ an array of tables used for asking user which elements to merge,
+ as used at `civicrm/contact/merge`. Each table in the array has
+ this format:
- 'rel_table_UNIQUE-TABLE-NICKNAME' => array(
- 'title' => ts('TITLE'),
- 'tables' => array('TABLE-NAME' [, ...]),
- 'url' => CRM_Utils_System::url(PATH, QUERY),
- )
+ ```php
+ 'rel_table_UNIQUE-TABLE-NICKNAME' => array(
+ 'title' => ts('TITLE'),
+ 'tables' => array('TABLE-NAME' [, ...]),
+ 'url' => CRM_Utils_System::url(PATH, QUERY),
+ ),
+ ```
-- 'sqls':
- - a one-dimensional array of SQL statements to be run in the final
- merge operation;
- - These SQL statements are run within a single transaction.
-- 'cidRefs':
- - an array of tables and their fields referencing
- civicrm_contact.contact_id explicitely;
- - each table in the array has this format:
+- `sqls`:
+ a one-dimensional array of SQL statements to be run in the final
+ merge operation. These SQL statements are run within a single transaction.
- 'TABLE-NAME' => array('COLUMN-NAME' [, ...])
+- `cidRefs`:
+ an array of tables and their fields referencing
+ civicrm_contact.contact_id explicitly. Each table in the array has this format:
-- 'eidRefs':
- - an array of tables and their fields referencing
- civicrm_contact.contact_id with entity_id;
- - each table in the array has this format:
+ ```php
+ 'TABLE-NAME' => array('COLUMN-NAME' [, ...])
+ ```
- 'TABLE-NAME' => array('entity_table-COLUMN-NAME' => 'entity_id-COLUMN-NAME')
+- `eidRefs`:
+ an array of tables and their fields referencing
+ `civicrm_contact.contact_id` with `entity_id`. Each table in the array has this format:
+
+ ```php
+ 'TABLE-NAME' => array('entity_table-COLUMN-NAME' => 'entity_id-COLUMN-NAME')
+ ```
## Example
- /* In this example we assume our module has created its own tables to store extra data on CiviCRM contacts:
- * Table civitest_foo stores a relationship between two contacts, and contains the two relevant columns:
- * civitest_foo.contact_id and civitest_foo.foo_id, both of which are foreign keys to civicrm_contact.id
- * Table civitest_bar stores extra properties for contacts, and contains one relevant column:
- * civitest_bar.contact_id is a foreign key to civicrm_contact.id
- *
- * This hook ensures that data in these two tables is included in CiviCRM merge operations.
- */
- function civitest_civicrm_merge ( $type, &$data, $mainId = NULL, $otherId = NULL, $tables = NULL ) {
-
- // If you are using Drupal and you use separate DBs for Drupal and CiviCRM, use the following to prefix
- // your tables with the name of the Drupal database.
- global $db_url;
- if (!empty($db_url) {
- $db_default = is_array($db_url) ? $db_url['default'] : $db_url;
- $db_default = ltrim(parse_url($db_default, PHP_URL_PATH), '/');
- }
- else {
- $db_default = '';
- }
-
- switch ($type) {
- case 'relTables':
- // Allow user to decide whether or not to merge records in `civitest_foo` table
- $data['rel_table_foo'] = array(
- 'title' => ts('Foos'), // Title as shown to user for this type of data
- 'tables' => array($db_default .'civitest_foo'), // Name of database table holding these records
- 'url' => CRM_Utils_System::url('civicrm/civitest/foo', 'action=browse&cid=$cid'),
- // URL to view this data for this contact,
- // in this case using CiviCRM's native URL utility
- // NOTE: '$cid' will be replaced with correct
- // CiviCRM contact ID.
- );
- break;
-
- case 'cidRefs':
- // Add references to civitest_foo.contact_id, and civitest_foo.foo_id, both of which
- // are foreign keys to civicrm_contact.id. By adding this to $data, records in this
- // table will be automatically included in the merge.
- $data[$db_default . 'civitest_foo'] = array('contact_id', 'foo_id');
- break;
-
- case 'eidRefs':
- // Add references to civitest_bar table, which is keyed to civicrm_contact.id
- // using `bar_entity_id` column, when `entity_table` is equal to 'civicrm_contact'. By
- // adding this to $data, records in this table will be automatically included in
- // the merge.
- $data[$db_default . 'civitest_bar'] = array('entity_table' => 'bar_entity_id');
- break;
-
- case 'sqls':
- // Note that this hook can be called twice with $type = 'sqls': once with $tables
- // and once without. In our case, SQL statements related to table `civitest_foo`
- // will be listed in $data when $tables is set; SQL statements related to table
- // `civitest_bar` will be listed in $data when $tables is NOT set. The deciding
- // factor here is that `civitest_foo` was referenced above as part of the 'relTables'
- // data, whereas `civitest_bar` was not.
- if ($tables) {
- // Nothing to do in our case. In some cases, you might want to find and
- // modify existing SQL statements in $data.
- } else {
- // Nothing to do in our case. In some cases, you might want to find and
- // modify existing SQL statements in $data.
- }
- break;
-
- }
- }
\ No newline at end of file
+```php
+/** In this example we assume our module has created its own tables to store extra data on CiviCRM contacts:
+ * Table civitest_foo stores a relationship between two contacts, and contains the two relevant columns:
+ * civitest_foo.contact_id and civitest_foo.foo_id, both of which are foreign keys to civicrm_contact.id
+ * Table civitest_bar stores extra properties for contacts, and contains one relevant column:
+ * civitest_bar.contact_id is a foreign key to civicrm_contact.id
+ *
+ * This hook ensures that data in these two tables is included in CiviCRM merge operations.
+ */
+function civitest_civicrm_merge($type, &$data, $mainId = NULL, $otherId = NULL, $tables = NULL) {
+
+ // If you are using Drupal and you use separate DBs for Drupal and CiviCRM, use the following to prefix
+ // your tables with the name of the Drupal database.
+ global $db_url;
+ if (!empty($db_url) {
+ $db_default = is_array($db_url) ? $db_url['default'] : $db_url;
+ $db_default = ltrim(parse_url($db_default, PHP_URL_PATH), '/');
+ }
+ else {
+ $db_default = '';
+ }
+
+ switch ($type) {
+ case 'relTables':
+ // Allow user to decide whether or not to merge records in `civitest_foo` table
+ $data['rel_table_foo'] = array(
+ // Title as shown to user for this type of data
+ 'title' => ts('Foos'),
+ // Name of database table holding these records
+ 'tables' => array($db_default .'civitest_foo'),
+ // URL to view this data for this contact,
+ // in this case using CiviCRM's native URL utility
+ 'url' => CRM_Utils_System::url('civicrm/civitest/foo', 'action=browse&cid=$cid'),
+ // NOTE: '$cid' will be replaced with correct CiviCRM contact ID.
+ );
+ break;
+
+ case 'cidRefs':
+ // Add references to civitest_foo.contact_id, and civitest_foo.foo_id, both of which
+ // are foreign keys to civicrm_contact.id. By adding this to $data, records in this
+ // table will be automatically included in the merge.
+ $data[$db_default . 'civitest_foo'] = array('contact_id', 'foo_id');
+ break;
+
+ case 'eidRefs':
+ // Add references to civitest_bar table, which is keyed to civicrm_contact.id
+ // using `bar_entity_id` column, when `entity_table` is equal to 'civicrm_contact'. By
+ // adding this to $data, records in this table will be automatically included in
+ // the merge.
+ $data[$db_default . 'civitest_bar'] = array('entity_table' => 'bar_entity_id');
+ break;
+
+ case 'sqls':
+ // Note that this hook can be called twice with $type = 'sqls': once with $tables
+ // and once without. In our case, SQL statements related to table `civitest_foo`
+ // will be listed in $data when $tables is set; SQL statements related to table
+ // `civitest_bar` will be listed in $data when $tables is NOT set. The deciding
+ // factor here is that `civitest_foo` was referenced above as part of the 'relTables'
+ // data, whereas `civitest_bar` was not.
+ if ($tables) {
+ // Nothing to do in our case. In some cases, you might want to find and
+ // modify existing SQL statements in $data.
+ }
+ else {
+ // Nothing to do in our case. In some cases, you might want to find and
+ // modify existing SQL statements in $data.
+ }
+ break;
+
+ }
+}
+```
diff --git a/docs/hooks/hook_civicrm_navigationMenu.md b/docs/hooks/hook_civicrm_navigationMenu.md
index 0efaf96ff482d69d6609916082532df564c9edb3..46e5aea3ef3b402d3922de5884f8ba03bef9f0a8 100644
--- a/docs/hooks/hook_civicrm_navigationMenu.md
+++ b/docs/hooks/hook_civicrm_navigationMenu.md
@@ -8,119 +8,122 @@ for any parent.
## Definition
- hook_civicrm_navigationMenu( &$params )
+```php
+hook_civicrm_navigationMenu(&$params)
+```
## Parameters
-- $params the navigation menu array
+- `$params` the navigation menu array
-Attributes of the menu :
+ Attributes of the menu :
- 1. label : Navigation Title
+ - string `label`: navigation title
- 2. Name : Internal Name
+ - string `name`: internal name
- 3. url : url in case of custom navigation link
+ - string `url`: URL in case of custom navigation link
- 4. permission : comma separated Permissions for menu item
+ - string `permission`: comma separated permissions for menu item
- 5. operator : Permission Operator ( AND/OR)
+ - string `operator`: permission operator (`AND` or `OR`)
- 6. seperator : 0 or null = No Separator, 1 = Separator after this
-menu item, 2 = Separator before this menu item.
+ - int `separator`: whether to insert a Separator
- 7. parentID : Parent navigation item, used for grouping
+ - `0` or `NULL` = No Separator,
+ - `1` = Separator after this menu item,
+ - `2` = Separator before this menu item.
- 8. navID : ID of the menu
+ - int `parentID`: parent navigation item, used for grouping
- 9. active : is active ?
+ - int`navID`: ID of the menu
-## Example
+ - bool `active`: whether the item is active
- function _getMenuKeyMax($menuArray) {
- $max = array(max(array_keys($menuArray)));
- foreach($menuArray as $v) {
- if (!empty($v['child'])) {
- $max[] = _getMenuKeyMax($v['child']);
- }
- }
- return max($max);
- }
-
- function civicrm_civicrm_navigationMenu( &$params ) {
-
- // Get the maximum key of $params
- $maxKey = getMenuKeyMax($params);
-
- $params[$maxKey+1] = array (
- 'attributes' => array (
- 'label' => 'Custom Menu Entry',
- 'name' => 'Custom Menu Entry',
- 'url' => null,
- 'permission' => null,
- 'operator' => null,
- 'separator' => null,
- 'parentID' => null,
- 'navID' => $maxKey+1,
- 'active' => 1
- ),
- 'child' => array (
- '1' => array (
- 'attributes' => array (
- 'label' => 'Custom Child Menu',
- 'name' => 'Custom Child Menu',
- 'url' => 'http://www.testlink.com',
- 'permission' => 'access CiviContribute',
- 'operator' => null,
- 'separator' => 1,
- 'parentID' => $maxKey+1,
- 'navID' => 1,
- 'active' => 1
- ),
- 'child' => null
- ) ) );
- }
+## Examples
-## Example: to add your menu item to an existing menu
-
- function donortrends_civicrm_navigationMenu(&$params) {
-
- // Check that our item doesn't already exist
- $menu_item_search = array('url' => 'civicrm/trends');
- $menu_items = array();
- CRM_Core_BAO_Navigation::retrieve($menu_item_search, $menu_items);
-
- if ( ! empty($menu_items) ) {
- return;
- }
-
- $navId = CRM_Core_DAO::singleValueQuery("SELECT max(id) FROM civicrm_navigation");
- if (is_integer($navId)) {
- $navId++;
- }
- // Find the Report menu
- $reportID = CRM_Core_DAO::getFieldValue('CRM_Core_DAO_Navigation', 'Reports', 'id', 'name');
- $params[$reportID]['child'][$navId] = array (
- 'attributes' => array (
- 'label' => ts('Donor Trends',array('domain' => 'org.eff.donortrends')),
- 'name' => 'Donor Trends',
- 'url' => 'civicrm/trends',
- 'permission' => 'access CiviReport,access CiviContribute',
- 'operator' => 'OR',
- 'separator' => 1,
- 'parentID' => $reportID,
- 'navID' => $navId,
- 'active' => 1
- )
- );
+```php
+function _getMenuKeyMax($menuArray) {
+ $max = array(max(array_keys($menuArray)));
+ foreach($menuArray as $v) {
+ if (!empty($v['child'])) {
+ $max[] = _getMenuKeyMax($v['child']);
}
-
-
-
-
-
-Both of these examples were a bit dangerous - they each provide a way to
-find the next available id, but the first one fails because it's not
-finding the child menu id numbers, and the second one fails because it's
-not taking into account the id's that other extensions might have added.
-I've just added a little recursive function to the first one to fix it.
\ No newline at end of file
+ }
+ return max($max);
+}
+
+function civicrm_civicrm_navigationMenu(&$params) {
+
+ // Get the maximum key of $params
+ $maxKey = getMenuKeyMax($params);
+
+ $params[$maxKey+1] = array(
+ 'attributes' => array(
+ 'label' => 'Custom Menu Entry',
+ 'name' => 'Custom Menu Entry',
+ 'url' => null,
+ 'permission' => null,
+ 'operator' => null,
+ 'separator' => null,
+ 'parentID' => null,
+ 'navID' => $maxKey + 1,
+ 'active' => 1
+ ),
+ 'child' => array(
+ '1' => array(
+ 'attributes' => array(
+ 'label' => 'Custom Child Menu',
+ 'name' => 'Custom Child Menu',
+ 'url' => 'http://www.testlink.com',
+ 'permission' => 'access CiviContribute',
+ 'operator' => NULL,
+ 'separator' => 1,
+ 'parentID' => $maxKey + 1,
+ 'navID' => 1,
+ 'active' => 1
+ ),
+ 'child' => NULL,
+ ),
+ ),
+ );
+}
+```
+
+To add your menu item to an existing menu
+
+```php
+function donortrends_civicrm_navigationMenu(&$params) {
+
+ // Check that our item doesn't already exist
+ $menu_item_search = array('url' => 'civicrm/trends');
+ $menu_items = array();
+ CRM_Core_BAO_Navigation::retrieve($menu_item_search, $menu_items);
+
+ if ( ! empty($menu_items) ) {
+ return;
+ }
+
+ $navId = CRM_Core_DAO::singleValueQuery("SELECT max(id) FROM civicrm_navigation");
+ if (is_integer($navId)) {
+ $navId++;
+ }
+ // Find the Report menu
+ $reportID = CRM_Core_DAO::getFieldValue('CRM_Core_DAO_Navigation', 'Reports', 'id', 'name');
+ $params[$reportID]['child'][$navId] = array(
+ 'attributes' => array (
+ 'label' => ts('Donor Trends',array('domain' => 'org.eff.donortrends')),
+ 'name' => 'Donor Trends',
+ 'url' => 'civicrm/trends',
+ 'permission' => 'access CiviReport,access CiviContribute',
+ 'operator' => 'OR',
+ 'separator' => 1,
+ 'parentID' => $reportID,
+ 'navID' => $navId,
+ 'active' => 1
+ ),
+ );
+}
+```
+
+The second example is a bit dangerous because it isn't taking into account the IDs that other extensions might have added.
diff --git a/docs/hooks/hook_civicrm_notePrivacy.md b/docs/hooks/hook_civicrm_notePrivacy.md
index 7de3fd5daf98504352d5904d82fcaf8a05ba223a..8c56cfc31772126a61a585953159b890fe6d9473 100644
--- a/docs/hooks/hook_civicrm_notePrivacy.md
+++ b/docs/hooks/hook_civicrm_notePrivacy.md
@@ -16,31 +16,37 @@ This hook is available in CiviCRM 3.3+.
## Definition
- notePrivacy(&$noteValues)
+```php
+hook_civicrm_notePrivacy(&$noteValues)
+```
## Parameters
-- &$noteValues - an array. The values from an object of type
- CRM_Core_DAO_Note, converted to an array.
+- array `$noteValues` - The values from an object of type
+ `CRM_Core_DAO_Note`, converted to an array.
## Returns
-- null
+- `NULL`
## Example
- function civitest_civicrm_notePrivacy (&$note) {
- /* CiviCRM will check for existence of $note['notePrivacy_hidden'].
- * If this value is not set, CiviCRM will show or display the note
- * based on the default, which is to display private notes only to
- * the note author.
- * If this value is set, CiviCRM will hide the note if the value is
- * TRUE, and display the note if the value is FALSE.
- */
- if ($note['is_private']) {
- if ($my_business_rules_say_so) {
- $note['notePrivacy_hidden'] = TRUE;
- } else {
- $note['notePrivacy_hidden'] = FALSE;
- }
- }
\ No newline at end of file
+```php
+function civitest_civicrm_notePrivacy(&$noteValues) {
+ /* CiviCRM will check for existence of $note['notePrivacy_hidden'].
+ * If this value is not set, CiviCRM will show or display the note
+ * based on the default, which is to display private notes only to
+ * the note author.
+ * If this value is set, CiviCRM will hide the note if the value is
+ * TRUE, and display the note if the value is FALSE.
+ */
+ if ($noteValues['is_private']) {
+ if ($my_business_rules_say_so) {
+ $noteValues['notePrivacy_hidden'] = TRUE;
+ }
+ else {
+ $noteValues['notePrivacy_hidden'] = FALSE;
+ }
+ }
+}
+```
diff --git a/docs/hooks/hook_civicrm_optionValues.md b/docs/hooks/hook_civicrm_optionValues.md
index e18196f78c659ec76bab17204ded530bc00e65f1..a56ffce33c8cee23ad896b5d4f479d45d6f9d3d7 100644
--- a/docs/hooks/hook_civicrm_optionValues.md
+++ b/docs/hooks/hook_civicrm_optionValues.md
@@ -1,7 +1,7 @@
# hook_civicrm_optionValues
!!! warning "Deprecated"
- This hook is deprecated in 4.7 in favor of [hook_civicrm_fieldOptions](https://wiki.civicrm.org/confluence/display/CRMDOC/hook_civicrm_fieldOptions). Use that instead for modifying all option lists, not limited to items in the civicrm_option_values table.
+ This hook is deprecated in 4.7 in favor of [hook_civicrm_fieldOptions](https://wiki.civicrm.org/confluence/display/CRMDOC/hook_civicrm_fieldOptions). Use that instead for modifying all option lists, not limited to items in the `civicrm_option_values` table.
## Description
@@ -11,13 +11,15 @@ hook to add/remove options from the option group.
## Definition
- civicrm_optionValues(&$options, $name)
+```php
+hook_civicrm_optionValues(&$options, $name)
+```
## Parameters
-- $options - the current set of options
-- $name - the name of the option group
+- array `$options` - the current set of options
+- string `$name` - the name of the option group
## Returns
-- null
\ No newline at end of file
+- `NULL`