Skip to content
Snippets Groups Projects
Commit fe861aa8 authored by Andie Hunt's avatar Andie Hunt
Browse files

hook_civicrm_merge: fixed formatting

parent e6b3f9a8
No related branches found
No related tags found
No related merge requests found
Hide whitespace changes
Inline Side-by-side
docs/hooks/hook_civicrm_merge.md
+ 111
− 101
View file @ fe861aa8
...@@ -12,121 +12,131 @@ This hook was first available in CiviCRM 3.2.3. ...@@ -12,121 +12,131 @@ This hook was first available in CiviCRM 3.2.3.
## Definition ## 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 ## Parameters
- $type the type of data being passed - string `$type` - the type of data being passed
(cidRefs|eidRefs|relTables|sqls) (`cidRefs`, `eidRefs`, `relTables`, or `sqls`)
- $data the data, which depends on the value of $type (see Details) - array `$data` - the data, which depends on the value of `$type` (see Details)
- $mainId contact_id of the contact that survives the merge (only - int `$mainId` - ID of the contact that survives the merge (only
when $type == 'sqls') when `$type` is `sqls`)
- $otherId contact_id of the contact that will be absorbed and - int `$otherId` - ID of the contact that will be absorbed and
deleted (only when $type == 'sqls') deleted (only when `$type` is `sqls`)
- $tables when $type is "sqls", an array of tables as it may have - array `$tables` - when `$type` is `sqls`, an array of tables as it may have
been handed to the calling function been handed to the calling function
## Details ## 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: passed:
- 'relTables': - `relTables`:
- an array of tables used for asking user which elements to merge, an array of tables used for asking user which elements to merge,
as used at civicrm/contact/merge; each table in the array has as used at `civicrm/contact/merge`. Each table in the array has
this format: this format:
'rel_table_UNIQUE-TABLE-NICKNAME' => array( ```php
'title' => ts('TITLE'), 'rel_table_UNIQUE-TABLE-NICKNAME' => array(
'tables' => array('TABLE-NAME' [, ...]), 'title' => ts('TITLE'),
'url' => CRM_Utils_System::url(PATH, QUERY), 'tables' => array('TABLE-NAME' [, ...]),
) 'url' => CRM_Utils_System::url(PATH, QUERY),
),
```
- 'sqls': - `sqls`:
- a one-dimensional array of SQL statements to be run in the final a one-dimensional array of SQL statements to be run in the final
merge operation; merge operation. These SQL statements are run within a single transaction.
- 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:
'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': ```php
- an array of tables and their fields referencing 'TABLE-NAME' => array('COLUMN-NAME' [, ...])
civicrm_contact.contact_id with entity_id; ```
- each table in the array has this format:
'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 ## Example
/* In this example we assume our module has created its own tables to store extra data on CiviCRM contacts: ```php
* Table civitest_foo stores a relationship between two contacts, and contains the two relevant columns: /** In this example we assume our module has created its own tables to store extra data on CiviCRM contacts:
* civitest_foo.contact_id and civitest_foo.foo_id, both of which are foreign keys to civicrm_contact.id * Table civitest_foo stores a relationship between two contacts, and contains the two relevant columns:
* Table civitest_bar stores extra properties for contacts, and contains one relevant column: * civitest_foo.contact_id and civitest_foo.foo_id, both of which are foreign keys to civicrm_contact.id
* civitest_bar.contact_id is a foreign key 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. *
*/ * 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 ) { */
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. // If you are using Drupal and you use separate DBs for Drupal and CiviCRM, use the following to prefix
global $db_url; // your tables with the name of the Drupal database.
if (!empty($db_url) { global $db_url;
$db_default = is_array($db_url) ? $db_url['default'] : $db_url; if (!empty($db_url) {
$db_default = ltrim(parse_url($db_default, PHP_URL_PATH), '/'); $db_default = is_array($db_url) ? $db_url['default'] : $db_url;
} $db_default = ltrim(parse_url($db_default, PHP_URL_PATH), '/');
else { }
$db_default = ''; else {
} $db_default = '';
}
switch ($type) {
case 'relTables': switch ($type) {
// Allow user to decide whether or not to merge records in `civitest_foo` table case 'relTables':
$data['rel_table_foo'] = array( // Allow user to decide whether or not to merge records in `civitest_foo` table
'title' => ts('Foos'), // Title as shown to user for this type of data $data['rel_table_foo'] = array(
'tables' => array($db_default .'civitest_foo'), // Name of database table holding these records // Title as shown to user for this type of data
'url' => CRM_Utils_System::url('civicrm/civitest/foo', 'action=browse&cid=$cid'), 'title' => ts('Foos'),
// URL to view this data for this contact, // Name of database table holding these records
// in this case using CiviCRM's native URL utility 'tables' => array($db_default .'civitest_foo'),
// NOTE: '$cid' will be replaced with correct // URL to view this data for this contact,
// CiviCRM contact ID. // in this case using CiviCRM's native URL utility
); 'url' => CRM_Utils_System::url('civicrm/civitest/foo', 'action=browse&cid=$cid'),
break; // NOTE: '$cid' will be replaced with correct CiviCRM contact ID.
);
case 'cidRefs': break;
// 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 case 'cidRefs':
// table will be automatically included in the merge. // Add references to civitest_foo.contact_id, and civitest_foo.foo_id, both of which
$data[$db_default . 'civitest_foo'] = array('contact_id', 'foo_id'); // are foreign keys to civicrm_contact.id. By adding this to $data, records in this
break; // table will be automatically included in the merge.
$data[$db_default . 'civitest_foo'] = array('contact_id', 'foo_id');
case 'eidRefs': break;
// 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 case 'eidRefs':
// adding this to $data, records in this table will be automatically included in // Add references to civitest_bar table, which is keyed to civicrm_contact.id
// the merge. // using `bar_entity_id` column, when `entity_table` is equal to 'civicrm_contact'. By
$data[$db_default . 'civitest_bar'] = array('entity_table' => 'bar_entity_id'); // adding this to $data, records in this table will be automatically included in
break; // the merge.
$data[$db_default . 'civitest_bar'] = array('entity_table' => 'bar_entity_id');
case 'sqls': break;
// 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` case 'sqls':
// will be listed in $data when $tables is set; SQL statements related to table // Note that this hook can be called twice with $type = 'sqls': once with $tables
// `civitest_bar` will be listed in $data when $tables is NOT set. The deciding // and once without. In our case, SQL statements related to table `civitest_foo`
// factor here is that `civitest_foo` was referenced above as part of the 'relTables' // will be listed in $data when $tables is set; SQL statements related to table
// data, whereas `civitest_bar` was not. // `civitest_bar` will be listed in $data when $tables is NOT set. The deciding
if ($tables) { // factor here is that `civitest_foo` was referenced above as part of the 'relTables'
// Nothing to do in our case. In some cases, you might want to find and // data, whereas `civitest_bar` was not.
// modify existing SQL statements in $data. if ($tables) {
} else { // Nothing to do in our case. In some cases, you might want to find and
// Nothing to do in our case. In some cases, you might want to find and // modify existing SQL statements in $data.
// modify existing SQL statements in $data. }
} else {
break; // 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
}
}
```
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment