diff --git a/docs/api/actions.md b/docs/api/actions.md
index 771298b2db9cc0777031538b10dd33c4d5ec5258..428595ce804ae2fc37b9c605ff1e64275272d0c5 100644
--- a/docs/api/actions.md
+++ b/docs/api/actions.md
@@ -1,17 +1,20 @@
+API Actions
+===========
+
Most entities support the following actions:
create
------
-Insert or update one record. (Note: If an *"id*" is specified, then an
+Insert or update one record. (Note: If an `id` is specified, then an
existing record will be modified.)
delete
------
-Delete one record. (Note: Requires an explicit "*id*". Note: if you
+Delete one record. (Note: Requires an explicit `id`. Note: if you
want to skip the 'recycle bin' for entities that support undelete (e.g.
-contacts) you should set \$param['skip\_undelete'] =\> 1);
+contacts) you should set `$param['skip_undelete'] => 1);`
get
---
@@ -26,11 +29,8 @@ returns the record in a simplified format which is easy to use)
getvalue
--------
-Does a **getsingle** & returns a single value - you need to also set
-
-````
-$param['return'] => 'fieldname'
-````
+Does a `getsingle` and returns a single value - you need to also set
+`$param['return'] => 'fieldname'`.
getcount
--------
@@ -58,32 +58,33 @@ getoptions
----------
Returns the options for a specified field e.g.
-````
+```php
civicrm_api3(
'contact',
'getoptions',
array('field' => 'gender_id')
);
-````
+```
returns
-````
+```php
array(
1 => 'Female',
2 => 'Male',
3 => 'Transgender'
)
-````
+```
replace
-------
Replace an old set of records with a new or modified set of records.
(For example, replace the set of "Phone" numbers with a different set of
-"Phone" numbers.).Â
+"Phone" numbers.).
-Warning - REPLACE includes an implicit delete - use with care & test well before using in productions
+Warning - REPLACE includes an implicit delete - use with care & test well
+before using in productions
<del>setvalue</del>
-------------------
diff --git a/docs/api/chaining.md b/docs/api/chaining.md
index 685c913406b248deb083fe8db7d98ecbeffddc06..4bcb0abfe7dbf7d59b221ba5d9fc16f2ac2bfee2 100644
--- a/docs/api/chaining.md
+++ b/docs/api/chaining.md
@@ -1,61 +1,72 @@
-It is now possible to do two api calls at once with the first call feeding into the second. E.g. to create a contact with a contribution you can nest the contribution create into the contact create. Once the contact has been created it will action the contribution create using the id from the contact create as 'contact\_id'. Likewise you can ask for all activities or all contributions to be returned when you do a get. Some examples will explain
+API Chaining
+============
-* [https://github.com/civicrm/civicrm-core/blob/master/api/v3/examples/ContactCreate.php](https://github.com/civicrm/civicrm-core/blob/master/api/v3/examples/ContactCreate.php)
+It is now possible to do two API calls at once with the first call feeding into
+the second. E.g. to create a contact with a contribution you can nest the
+contribution create into the contact create. Once the contact has been created
+it will action the contribution create using the id from the contact create as
+`contact_id`. Likewise you can ask for all activities or all contributions to
+be returned when you do a get.
-* [https://github.com/civicrm/civicrm-core/blob/master/api/v3/examples/ContactGet.php](https://github.com/civicrm/civicrm-core/blob/master/api/v3/examples/ContactGet.php)
+See [api/v3/examples] within the core source code for a plethora of examples
+(from unit tests) that use API chaining. To start, look at these examples:
-* [https://github.com/civicrm/civicrm-core/blob/master/api/v3/examples/Contact/APIChainedArray.php](https://github.com/civicrm/civicrm-core/blob/master/api/v3/examples/Contact/APIChainedArray.php)
+- [APIChainedArray.php]
+- [APIChainedArrayFormats.php]
+- [APIChainedArrayValuesFromSiblingFunction.php]
-* [https://github.com/civicrm/civicrm-core/blob/master/api/v3/examples/Contact/APIChainedArrayFormats.php](https://github.com/civicrm/civicrm-core/blob/master/api/v3/examples/Contact/APIChainedArrayFormats.php)
+[api/v3/examples]: https://github.com/civicrm/civicrm-core/tree/master/api/v3/examples
+[APIChainedArray.php]: https://github.com/civicrm/civicrm-core/blob/master/api/v3/examples/Contact/APIChainedArray.php
+[APIChainedArrayFormats.php]: https://github.com/civicrm/civicrm-core/blob/master/api/v3/examples/Contact/APIChainedArrayFormats.php
+[APIChainedArrayValuesFromSiblingFunction.php]: https://github.com/civicrm/civicrm-core/blob/master/api/v3/examples/Contact/APIChainedArrayValuesFromSiblingFunction.php
-* [https://github.com/civicrm/civicrm-core/blob/master/api/v3/examples/Contact/APIChainedArrayValuesFromSiblingFunction.php](https://github.com/civicrm/civicrm-core/blob/master/api/v3/examples/Contact/APIChainedArrayValuesFromSiblingFunction.php)
-Note that there are a few supported syntaxes
+Note that there are a few supported syntaxes:
-```
-civicrm('Contact', 'Create',
-array(
- 'version' => 3,
- 'contact_type' => 'Individual',
- 'display_name' => 'BA Baracus',
- 'api.website.create' => array('url' => 'Ateam.com'));
+```php
+civicrm('Contact', 'Create', array(
+ 'version' => 3,
+ 'contact_type' => 'Individual',
+ 'display_name' => 'BA Baracus',
+ 'api.website.create' => array('url' => 'example.com'));
```
is the same as
-````
+```php
civicrm('Contact', 'Create', array(
- 'version' => 3,
- 'contact_type' => 'Individual',
- 'display_name' => 'BA Baracus',
- 'api.website' => array('url' => 'Ateam.com'));
-````
+ 'version' => 3,
+ 'contact_type' => 'Individual',
+ 'display_name' => 'BA Baracus',
+ 'api.website' => array('url' => 'example.com'));
+```
-If you have 2 websites to create you can pass them as ids after the '.'
+If you have 2 websites to create you can pass them as ids after the `.`
or an array
-````
+```php
civicrm('Contact', 'Create', array(
- 'version' => 3,
- 'contact_type' => 'Individual',
- 'display_name' => 'BA Baracus',
- 'api.website.create' => array('url' => 'Ateam.com',),
- 'api.website.create.2' => array('url' => 'warmbeer.com', ));
-
-````
+ 'version' => 3,
+ 'contact_type' => 'Individual',
+ 'display_name' => 'BA Baracus',
+ 'api.website.create' => array('url' => 'example.com',),
+ 'api.website.create.2' => array('url' => 'example.org', ));
+```
OR
-````
+```php
civicrm('Contact', 'Create', array(
'version' => 3,
'contact_type' => 'Individual',
'display_name' => 'BA Baracus',
'api.website.create' => array(
- array('url' => 'Ateam.com', ),
- array('url' => 'warmbeer.com', )));
-````
+ array('url' => 'example.com', ),
+ array('url' => 'example.org', )));
+```
the format you use on the way in will dictate the format on the way out.
-Currently this supports any entity & it will convert to 'entity\_id' - ie. a PledgePayment inside a contribution will receive the contribution\_id from the outer call
+Currently this supports any entity and it will convert to `entity_id` -
+i.e. a PledgePayment inside a contribution will receive the `contribution_id`
+from the outer call.
diff --git a/docs/api/general.md b/docs/api/general.md
index 14676676dd3a0469b848c319e1271dd06c2aeb4b..2c4e3cf567ed183ea086cf068e99860816e4ec58 100644
--- a/docs/api/general.md
+++ b/docs/api/general.md
@@ -1,124 +1,78 @@
+The CiviCRM API
+===============
+
CiviCRM has a stable comprehensive **API** (Application Programming
Interface) that can be used to access and manage data in CiviCRM. The
API is the recommended way for any CiviCRM extension, CMS module, or
-external program to interact with CiviCRM. This section of the wiki
-gives you an introduction to the basics of the API. This page's children
-dive into the depths of the API.
+external program to interact with CiviCRM.
-Why use the API?
-----------------
+Utilizing the API is superior to accessing core functions directly (e.g.
+calling raw SQL, or calling functions within the BAO files)
+because the API offers a consistent interface to CiviCRM's features. It is
+designed to function predictably with every new release so as to preserve
+backwards compatibility of the API for several versions of CiviCRM. If
+you decide to use other ways to collect data (like your own SQL statements),
+you risk running into future problems when changes to the schema and
+BAO arguments inevitably occur.
-If you're not familiar with APIs, you might ask why you would use the
-API when you could access the core functions (e.g. the BAO files) or the
-data in the MySQL database directly?
+The best place to begin working with the API is your own ***test*** install of
+CiviCRM, using the API explorer and the API parameter list.
-The answer is that the community will ensure that the API will function
-as expected with every new release. Great effort is made to preserve
-backwards compatibility of the API for several versions of CiviCRM. If
-you decide to use other ways to collect data (like your own MySQL
-statements), you are left to your own devices. Changes in the schema and
-BAO arguments, etc. will cause you grief.
-
-A few comments before we start
-------------------------------
-
-The API is something that we as a community develop and maintain
-together. A pretty awesome achievement so a big round of applause for
-everyone who contributes! It also means that:
-
-- the API is continuously developed and improved. Once you have
- mastered the basics from this introduction it is a good idea to
- delve deeper into the wiki and the forums for the latest and
- greatest
-
-- there is always a chance you run into a bug, if you do please report
- it on the forum or go to the CiviCRM IRC channel if it is a real
- urgency. Obviously it will be greatly appreciated if you fix it,
- send it as a patch with a unit test
-
-- This introduction is updated by the community too. If you do happen
- to find some mistake, please log in and change
-
-Exploring the API and documentation
------------------------------------
-
-The best place to learn about the API is your own ***test*** install of
-CiviCRM, using the API explorer and the API parameter list.Â
-
-Each install comes with two tools that will help you to explore the
-wonders of the API and learn a little more about each one:
-
-1. The**API parameter list**, which shows all available entities which
- can be manipulated by the API and is available
- at http://[CIVICRM\_URL]/civicrm/api/doc (or
- http://[CIVICRM\_URL]/?q=civicrm/api/doc if you do not use clean
- URLs in Drupal). You will first get a list of all the API entities.
- If you click on an entity you will get a list of parameters that are
- available for that specific entity, with the type of the parameter.
- This can be very useful if you want to check what you can retrieve
- with the API and what parameters you can use to refine your get
- action or complete your create or update action.
-2. The **API explorer**, which is available
- at http://[CIVICRM\_URL]/civicrm/api/explorer (or
- http://[CIVICRM\_URL]/?q=civicrm/api/explorer if you do not use
- clean URLs in Drupal). This gives you the possibility to actually
- try out the API in action. You can select the entity you want to
- use, for example ' Contact' and the action you want to perform, for
- example ' Get' . Again, be careful as the API explorer will actually
- perform your actions! So if you delete a contact to check what API
- call to use, it will really delete the contact. The API explorer
- will show you the code you need to have to execute the API call you
- have been testing. To see an example of the API explorer in action
- check
- [http://civicrm.org/API\_version\_3](http://civicrm.org/API_version_3).
- It may be that it uses an older version of the API explorer, but you
- will get the idea!
-
-Public API
-Explorer:Â [http://drupal.sandbox.civicrm.org/civicrm/api/explorer](http://drupal.sandbox.civicrm.org/civicrm/api/explorer)Â (login
-as demo/demo)
-
-On top of these tools, your CiviCRM installation will also contain a
-directory full of examples on how the API can be used. These examples
-will be inside the api/v3 directory and is called 'examples'. You can
-also find the examples on GitHub:
-[https://github.com/civicrm/civicrm-core/tree/master/api/v3/examples](https://github.com/civicrm/civicrm-core/tree/master/api/v3/examples)
-
-There is also the code-level documentation which can be found at
-[http://api.civicrm.org/v3/](http://api.civicrm.org/v3/)
-
-Also, the [API Reference](https://wiki.civicrm.org/confluence/display/CRMDOC/API+Reference) page
-on this wiki.
-Changelog
----------
+API explorer
+------------
+
+The API explorer gives you the possibility to actually
+try out the API in action and is available at
+
+```text
+http://[CIVICRM\_URL]/civicrm/api/explorer
+```
+
+You can select the entity you want to
+use, for example `Contact` and the action you want to perform, for
+example `Get`. Again, be careful as the API explorer will actually
+perform your actions! So if you delete a contact to check what API
+call to use, it will really delete the contact. The API explorer
+will show you the specific code necessary to execute the API call you
+have been testing.
-Any API change you should be aware of will be recorded on this wiki
-documentation at [API changes](https://wiki.civicrm.org/confluence/display/CRMDOC/API+changes)
+Try out the [API explorer on the demo site], *after you login as demo/demo*.
-Examples
-========
+[API explorer on the demo site]: http://drupal.sandbox.civicrm.org/civicrm/api/explorer
-<h3>Online Examples</h3>
-All the API examples included with CiviCRM core are auto-generated so
-the validity of the code is certain.Â
+API parameter list
+------------------
-|Version|URL|
-|:-----------|-------------|
-|Upcoming Version|[https://github.com/civicrm/civicrm-core/tree/master/api/v3/examples](https://github.com/civicrm/civicrm-core/tree/master/api/v3/examples)|
-|CiviCRM 4.5|[https://github.com/civicrm/civicrm-core/tree/4.5/api/v3/examples](https://github.com/civicrm/civicrm-core/tree/4.5/api/v3/examples)|
-|CiviCRM 4.2 LTS|[https://github.com/CiviCRM42/civicrm42-core/tree/4.2/api/v3/examples](https://github.com/CiviCRM42/civicrm42-core/tree/4.2/api/v3/examples)|
+The API parameter list shows all available entities which
+can be manipulated by the API and is available at:
-Â
+```text
+http://[CIVICRM_URL]/civicrm/api/doc
+```
-<h3>Local Examples</h3>
+You will first get a list of all the API entities.
+If you click on an entity you will get a list of parameters that are
+available for that specific entity, with the type of the parameter.
+This can be very useful if you want to check what you can retrieve
+with the API and what parameters you can use to refine your get
+action or complete your create or update action.
-CiviCRM ships with API examples included in the distribution. You can
+
+API Examples
+------------
+
+CiviCRM ships with API examples included in the distribution. You can
find the examples specific to your installed version at:
-<civicrm\_root\>/api/v3/examples
+`<civicrm_root>/api/v3/examples`
+
+[Explore these examples on GitHub](https://github.com/civicrm/civicrm-core/tree/master/api/v3/examples)
+
+
+Changelog
+---------
-For example, if you have CiviCRM installed with Drupal the location to
-the examples would be:
-[/path/to/your/drupalroot/sites/all/modules/civicrm/api/v3/examples](http://path/to/your/drupalroot/sites/all/modules/civicrm/api/v3/examples)
+All important changes made to the API are be recorded on the wiki at:
+[API changes](https://wiki.civicrm.org/confluence/display/CRMDOC/API+changes)
diff --git a/docs/api/params.md b/docs/api/params.md
index b59e04e379a66fe70c855ac32a07318a59663bc5..799e830e7d2fe2534bf9f4227fa426f06bdd9c16 100644
--- a/docs/api/params.md
+++ b/docs/api/params.md
@@ -1,71 +1,61 @@
+API Parameters
+==============
+
There are many parameters accepted by the CiviCRM API. Most parameters
-depend on the entity – for current details in your version, see the
-"Documentation" section; in particular, see the "API Explorer" and the
-API examples. However, some parameters are particularly dynamic or
+depend on the entity – for current details in your see the [API Explorer]
+and the [API examples]. However, some parameters are particularly dynamic or
generic; these may not be explained well by the auto-generated
documentation. The format for passing options as parameters using the
-REST interface is explained at [REST
+REST interface is explained at [REST
interface\#optionsparameters](https://wiki.civicrm.org/confluence/display/CRMDOC/REST+interface#RESTinterface-optionsparameters).
+[API Explorer]: /api/general/#api-explorer
+[API examples]: /api/general/#api-examples
-**sequential**
---------------
-
-* **Action**: get
-
-* **Type**: bool
+sequential
+----------
-* **Default**: FALSE
+- **Action**: get
+- **Type**: bool
+- **Default**: FALSE
+- **Compatibility**: ??
+- **Description**:
-* **Compatibility**: ??
+Determine whether the returned records are indexed sequentially (0, 1, 2, ...)
+or by ID.
-* **Description**:
+Example without sequential:
-Determine whether the returned records are indexed sequentially (0, 1, 2, ...) or by ID.
-
-Without sequential
-````
+```php
$result= civicrm_api('UFMatch','Get', array('version' =>3, 'uf_id' => $user->uid);
$contactid=$contact['values'][$result['id']]['contact_id'] );
-````
-With sequential
-````
-$result= civicrm_api('UFMatch','Get', array('version' =>3, 'uf_id' => $user->uid, 'sequential' => 1);
-$contactid=$result['values'][0]['contact_id'] );
-````
-
-Note that a single record is returned in this example - whenever a single record is returned the entity_id of that record should be in $result['id']
-
-<h3>Example: sequential</h3>
-
-````
-
- civicrm_api('UFMatch','Get', array(
- 'version' => 3,
- 'uf_id' => $user->uid,
- 'sequential' => 1,
-));
-
-````
+```
-**options.limit**
------------------
+Example with sequential:
-* **Action**: get
+```php
+$result= civicrm_api('UFMatch','Get', array('version' =>3, 'uf_id' => $user->uid, 'sequential' => 1);
+$contactid=$result['values'][0]['contact_id'] );
+```
-* **Type**: int
+Note that a single record is returned in this example - whenever a single
+record is returned the `entity_id` of that record should be in `$result['id']`
-* **Default**: 25
-* **Compatibility**: ??
+options.limit
+-------------
-* **Description**:
+- **Action**: get
+- **Type**: int
+- **Default**: 25
+- **Compatibility**: ??
+- **Description**:
The maximum number of records to return
-<h3>Example: options.limit</h3>
+Example:
-````
+```php
civicrm_api('UFMatch','Get', array(
'version' => 3,
'uf_id' => $user->uid,
@@ -73,25 +63,22 @@ civicrm_api('UFMatch','Get', array(
'limit' => 25,
),
));
-````
-
-
-**options.offset**
-------------------
-
-* **Action**: get
+```
-* **Type**: int
-* **Default**: 0
+options.offset
+--------------
-* **Description**:
+- **Action**: get
+- **Type**: int
+- **Default**: 0
+- **Description**:
The numerical offset of the first result record
-<h3>Example: options.offset</h3>
+Example:
-````
+```php
civicrm_api('UFMatch','Get', array(
'version' => 3,
'uf_id' => $user->uid,
@@ -100,51 +87,44 @@ civicrm_api('UFMatch','Get', array(
'offset' => 50,
),
));
-````
-
-**options.sort**
-----------------
-
-* **Action**: get
-
-* **Type**: ??
+```
-* **Default**: ??
+options.sort
+------------
-* **Parameters**: field name, order (ASC / DESC)
-* **Description**:
+- **Action**: get
+- **Type**: ??
+- **Default**: ??
+- **Parameters**: field name, order (ASC / DESC)
+- **Description**:
The criterion to sort on
-<h3>Example: options.sort</h3>
+Example
-````
+```php
civicrm_api3('Contact', 'get', array(
'sequential' => 1,
'return' => "contact_type",
'options' => array('sort' => "contact_type ASC"),
));
-````
-
-**options.reload**
-------------------
-
-* **Action**: create
-
-* **Type**: bool
-
-* **Default**: FALSE
+```
-* **Compatibility**: v4.4+
+options.reload
+--------------
-* **Description**:
+- **Action**: create
+- **Type**: bool
+- **Default**: FALSE
+- **Compatibility**: v4.4+
+- **Description**:
Whether to reload and return the final record after the saving process
completes.
-<h3>Example: options.reload</h3>
+Example:
-```
+```php
civicrm_api('Contact', 'create', array(
'version' => 3,
'contact_type' => 'Individual',
@@ -157,32 +137,26 @@ civicrm_api('Contact', 'create', array(
));
```
-**options.match**
------------------
-
-* **Action**: create | replace
-
-* **Type**: string | array
+options.match
+-------------
-* **Default**: NULL
-
-* **Compatibility**: v4.4+
-
-* **Description**:
+- **Action**: create | replace
+- **Type**: string | array
+- **Default**: NULL
+- **Compatibility**: v4.4+
+- **Description**:
Attempt to update an existing record by matching against the specified
field.
-<br />
-If **one** matching record already exists, then the record will be
-**updated**.
-<br />
-If **no** matching record exists, then a new one will be **inserted**.
-<br />
-If **multiple** matching records exist, then return an **error**.
-<h3>Example: options.match</h3>
+- If **one** matching record already exists, then the record will be
+ **updated**.
+- If **no** matching record exists, then a new one will be **inserted**.
+- If **multiple** matching records exist, then return an **error**.
-```
+Example:
+
+```php
civicrm_api('contact', 'create', array(
'version' => 3,
'contact_type' => 'Individual',
@@ -196,32 +170,26 @@ civicrm_api('contact', 'create', array(
));
```
-**options.match-mandatory**
----------------------------
-
-* **Action**: create | replace
-
-* **Type**: string | array
+options.match-mandatory
+-----------------------
-* **Default**: NULL
-
-* **Compatibility**: v4.4+
-
-* **Description**:
+- **Action**: create | replace
+- **Type**: string | array
+- **Default**: NULL
+- **Compatibility**: v4.4+
+- **Description**:
Attempt to update an existing record by matching against the specified
field.
-<br />
-If **one** matching record already exists, then the record will be
-updated.
-<br />
-If **no** matching record exists, then return an **error**.
-<br />
-If **multiple** matching records exist, then return an **error**.
-Â
-<h3>Example: options.match-mandatory</h3>
-```
+- If **one** matching record already exists, then the record will be
+ updated.
+- If **no** matching record exists, then return an **error**.
+- If **multiple** matching records exist, then return an **error**.
+
+Example:
+
+```php
civicrm_api('contact', 'create', array(
'version' => 3,
'contact_type' => 'Individual',
@@ -236,38 +204,45 @@ civicrm_api('contact', 'create', array(
```
-**Custom Data**
----------------
+Custom Data
+-----------
-Custom data attached to entities is referenced by custom\_N where N is
+Custom data attached to entities is referenced by `custom_N` where `N` is
the unique numerical ID for the custom data field.
To set a custom field, or find entities with custom fields of a
particular value, you typically use a parameter like this:
-```
+```php
$param['custom_N'] => 'value';
```
To return custom data for an entity, you typically pass a param like the
following:
-```
+```php
$param['return.custom_N'] => 1;
```
*or (depending on which API entity you are querying)*
-```
+```php
$param['return'] => 'custom_N';
```
-*or*Â
-```
+*or*
+```php
$param['return'] => 'custom_N,custom_O,custom_P';
```
-For setting custom date fields, (ie CustomValue create), date format is YmdHis, for example:Â 20050425000000.
+For setting custom date fields, (ie CustomValue create), date format is
+`YmdHis`, for example: `20050425000000`.
-This is just a brief introduction; each API may have different requirements and allow different formats for accessing the custom data. Â See the [API function documentation](https://wiki.civicrm.org/confluence/display/CRMDOC/Using+the+API) and also read the comments and documentation in each API php file (under civicrm/CRM/api/v3 in your CiviCRM installation) for exact details, which vary for each API entity and function.
+This is just a brief introduction; each API may have different requirements
+and allow different formats for accessing the custom data. See the
+[API function documentation](https://wiki.civicrm.org/confluence/display/CRMDOC/Using+the+API)
+and also read the comments and documentation in each API php file
+(under civicrm/CRM/api/v3 in your CiviCRM installation) for exact details,
+which vary for each API entity and function.
-For more details and examples, [see the tutorial on using custom data with the API here](https://wiki.civicrm.org/confluence/display/CRMDOC/Using+Custom+Data+with+the+API).
+For more details and examples,
+[see the tutorial on using custom data with the API here](https://wiki.civicrm.org/confluence/display/CRMDOC/Using+Custom+Data+with+the+API).
diff --git a/docs/api/usage.md b/docs/api/usage.md
index a3d84468b99337226e0bb4285266906540d52128..f8ef33f4af6da05c59091586d768793694ed7db4 100644
--- a/docs/api/usage.md
+++ b/docs/api/usage.md
@@ -1,3 +1,6 @@
+API Usage
+=========
+
Every API call consists of three elements: the *entity*, *action*, and
*parameters*. For example, consider a few commonly-used entities along
with the supported actions and parameters:
@@ -9,7 +12,10 @@ with the supported actions and parameters:
| <code>Activity</code> | An phone call, meeting,<br /> or email message. that <br /> has occurred (or will <br /> occur) at a specific <br /> date and time|<code>create</code><br/><code>get</code><br/><code>delete</code><br/>| <code>activity\_type\_id</code> <br /> <code>source\_contact\_id</code> <br /> <code>assignee\_contact\_id</code> |
| <code>Address</code> | A street-address related <br /> to a contact. |<code>create</code><br/><code>get</code><br/><code>delete</code><br/>| <code>contact\_id</code>, <br /> <code>street\_address</code> <br /> <code>city</code> <br /> <code>state\_province\_id</code> <br /> <code>country\_id</code> |
-(*For full, up-to-date details about specific entities and parameters, use the "API Explorer".*)
+(*For full, up-to-date details about specific entities and parameters, use the
+[API Explorer].*)
+
+[API Explorer]: /api/general/#api-explorer
The API is available in many different environments (such as PHP, REST, and
Javascript), and the notation differs slightly in each environment.
@@ -41,12 +47,12 @@ array(
The result of a failed API call typically looks like this:
-````
+```php
array(
'is_error' => 1,
'error_message' => /* a descriptive error message */,
)
-````
+```
(**Note**: A few specialized actions like `getsingle` or `getvalue` may
return success in a different format.)
@@ -57,7 +63,7 @@ PHP (civicrm_api3)
This is the most common way to call the API.
-```
+```php
try {
$contacts = civicrm_api3('contact', 'get', array(
'first_name' => 'Alice',
@@ -73,19 +79,19 @@ printf("Found %d item(s)\n", $contacts['count']);
This format matches canonical format almost exactly, with a few improvements
for usability:
- * The function `civicrm_api3()` is easier to remember.
- * The `version => 3` parameter is not required.
- * Errors are reported as PHP exceptions. You may catch the exceptions or (by default) allow
- them to bubble up.
+- The function `civicrm_api3()` is easier to remember.
+- The `version => 3` parameter is not required.
+- Errors are reported as PHP exceptions. You may catch the exceptions or
+ (by default) allow them to bubble up.
*Note*: If you're writing a Drupal module, a Joomla extension, a WordPress
plugin, or a standalone script, then you may need to **bootstrap** CiviCRM
-before using the API. See the examples in [Bootstrap
-Reference](https://wiki.civicrm.org/confluence/display/CRMDOC/Bootstrap+Reference).Â
+before using the API. See the examples in [Bootstrap Reference].
+[Bootstrap Reference]: https://wiki.civicrm.org/confluence/display/CRMDOC/Bootstrap+Reference
PHP (class.api.php)
-----------------------------
+-------------------
CiviCRM v3.4 introduced an object-oriented API client, `class.api.php`.
This class be used locally or remotely to invoke APIs, as in:
@@ -105,17 +111,17 @@ if ($api->Contact->Get($apiParams)) {
echo $api->errorMsg();
}
```
-Â
If you call the API in the object oriented fashion, you do not have to
specify 'version' as a parameter
+
REST
----
-````javascript
+For external services:
-// For external services
+```text
http://www.example.com/sites/all/modules/civicrm/extern/rest.php
?api_key=t0ps3cr3t
&key=an07h3rs3cr3t
@@ -126,8 +132,11 @@ http://www.example.com/sites/all/modules/civicrm/extern/rest.php
&action=get
&first_name=Alice
&last_name=Roberts
+```
-// For sessions already authenticated by the CMS (e.g. AJAX)
+For sessions already authenticated by the CMS (e.g. AJAX)
+
+```text
http://www.example.com/civicrm/ajax/rest
?json=1
&debug=1
@@ -136,72 +145,81 @@ http://www.example.com/civicrm/ajax/rest
&action=get
&first_name=Alice
&last_name=Roberts
-
-````
+```
Obviously you should substitute your site in! You can explore the syntax
-and options available using the [api
-explorer](http://sandbox.civicrm.org/civicrm/ajax/doc#explorer) (also on
-your site!)
+and options available using the [API Explorer].
-Please note that the REST interface is subject to [API Security](https://wiki.civicrm.org/confluence/display/CRMDOC/API+Security).
+Please note that the REST interface is subject to
+[API Security](https://wiki.civicrm.org/confluence/display/CRMDOC/API+Security).
For more details, see [REST
interface](http://wiki.civicrm.org/confluence/display/CRMDOC/REST+interface).Â
+
AJAX
----
-````
+```javascript
CRM.api3('entity', 'action', [params], [statusMessage]);
+```
-````
+For more details, see [AJAX Interface].
-For more details, see [AJAX
-Interface](https://wiki.civicrm.org/confluence/display/CRMDOC/AJAX+Interface).
+[AJAX Interface]: https://wiki.civicrm.org/confluence/display/CRMDOC/AJAX+Interface
-The AJAX interface is automatically available for web-pages generated through CiviCRM (such as ***standard CiviCRM web-page****s***, CiviCRM ***extensions***, and custom CiviCRM ***templates***).
+The AJAX interface is automatically available for web-pages generated through
+CiviCRM (such as standard CiviCRM web-pages, CiviCRM extensions,
+and custom CiviCRM templates).
-The AJAX interface could be made available to other parts of the same website (e.g. a drupal module or wordpress widget) by calling CRM\_Core\_Resources::singleton()-\>addCoreResources() from php. Please note that the AJAX interface is subject to [API Security](https://wiki.civicrm.org/confluence/display/CRMDOC/API+Security) and [Same Origin Policy](http://en.wikipedia.org/wiki/Same_origin_policy). To use it from an external site or application, see REST interface documentation.
+The AJAX interface could be made available to other parts of the same website
+(e.g. a drupal module or wordpress widget) by calling
+`CRM_Core_Resources::singleton()->addCoreResources()`
+from php. Please note that the AJAX interface is subject to
+[API Security](https://wiki.civicrm.org/confluence/display/CRMDOC/API+Security)
+and
+[Same Origin Policy](http://en.wikipedia.org/wiki/Same_origin_policy).
+To use it from an external site or application, see REST interface documentation.
Smarty
------
-````
-
+```smarty
{crmAPI var="myContactList" entity="Contact" action="get" version="3" first_name="Alice" last_name="Roberts" }
Found {$myContactList.count} item(s).
+```
-````
+The smarty call is to add extra information, therefore *create* or *delete*
+actions don't make sense in this case.
+For more details, see
+[Smarty API interface](https://wiki.civicrm.org/confluence/display/CRMDOC/Smarty+API+interface).
-The smarty call is to add extra information, therefore *create* or
-*delete* actions don't make sense in this case.
+Command line
+------------
-For more details, see [Smarty API
-interface](https://wiki.civicrm.org/confluence/display/CRMDOC/Smarty+API+interface).
+### drush
-CLI (drush)
------
+To run on the default Drupal site:
-```
-## To run on the default Drupal site
+```bash
drush civicrm-api contact.get first_name=Alice last_name=Roberts
+```
+
+To run on Drupal multisite, specify the site name:
-## To run on Drupal multisite, specify the site name
+```bash
drush -l www.example.com civicrm-api contact.get first_name=Alice last_name=Roberts
```
-CLI (wp-cli)
------
+### wp-cli
-```
+```bash
wp civicrm-api contact.get first_name=Alice last_name=Roberts
```
-CLI (cv)
------
+### cv
-````
+```bash
cv api contact.get first_name=Alice last_name=Roberts
-````
+```
diff --git a/docs/build.md b/docs/build.md
index 19b91c36348aa208dd4ff1e227d09bbcea1590cd..74eac75cbb88fdaa1e7ef0c134172d4fd5435c63 100644
--- a/docs/build.md
+++ b/docs/build.md
@@ -1,7 +1,8 @@
-*Build.md*
+Building CiviCRM
+================
TODO:
- * Nightlies vs gitify vs civibuild
- * gitify
- * civibuild (https://github.com/civicrm/civicrm-buildkit/blob/master/doc/civibuild.md)
+- Nightlies vs gitify vs civibuild
+- gitify
+- civibuild (https://github.com/civicrm/civicrm-buildkit/blob/master/doc/civibuild.md)
diff --git a/docs/customize.md b/docs/customize.md
index c2377aa0059cf654d1f1665282363c4c04d28d4f..fa6e5147c49295735bbe6bbfb9ef635c418de436 100644
--- a/docs/customize.md
+++ b/docs/customize.md
@@ -1,12 +1,14 @@
-*Customize*
+Customizing CiviCRM
+===================
TODO:
- * *(Requirements: Don't need full git install)*
- * *(When possible, link to User/Admin Guide or other existing docs instead of giving details.)*
- * Custom fields, profiles, option groups, etc
- * webform_civicrm
- * Extensions (download+install; web and CLI).
- * (Maybe) CiviRules
- * (Maybe) CSS override
- * (Maybe) *.extra.tpl
+- *(Requirements: Don't need full git install)*
+- *(When possible, link to User/Admin Guide or other existing docs instead
+ of giving details.)*
+- Custom fields, profiles, option groups, etc
+- webform_civicrm
+- Extensions (download+install; web and CLI).
+- (Maybe) CiviRules
+- (Maybe) CSS override
+- (Maybe) *.extra.tpl
diff --git a/docs/develop.md b/docs/develop.md
index 738197f7cdd7408c670397d59787907c239fb563..800291f4b741faf4c99da44fd828c0f85b0d5765 100644
--- a/docs/develop.md
+++ b/docs/develop.md
@@ -1,22 +1,38 @@
-# Develop
-
-Tip: If Git or GitHub are unfamiliar to you, see [Git and GitHub](git.md) first.
-
-## Repositories
-
-CiviCRM is divided into a few repositories. This allows developers to work with different components, allows different teams to manage each component, and will allow all the pieces to be remixed using different tools (civibuild, shell scripts, Drush & Drush make, or composer). The repositories are:
-
-* [civicrm-core](https://github.com/civicrm/civicrm-core/) - Core application which can be embedded in different systems (Drupal, Joomla, etc).
-* [civicrm-drupal](https://github.com/civicrm/civicrm-drupal/) - Drupal integration modules, with branches for each CiviCRM release & Drupal major version (e.g. 7.x-4.6, 7.x-4.7, 6.x-4.4, 6.x-4.6).
-* [civicrm-joomla](https://github.com/civicrm/civicrm-joomla/) - Joomla integration modules.
-* [civicrm-wordpress](https://github.com/civicrm/civicrm-wordpress/) - WordPress integration modules.
-* [civicrm-packages](https://github.com/civicrm/civicrm-packages/) - External dependencies required by CiviCRM.
-* [civicrm-l10n](https://github.com/civicrm/civicrm-l10n/) - Localization data.
-
-## Obtaining a development build of CiviCRM
-
-The recommended method is to use [CiviCRM Buildkit](https://github.com/civicrm/civicrm-buildkit/) to build a CiviCRM codebase to develop with.
-
-## Deprecated instructions
-
-Previous methods for obtaining a CiviCRM source build are documented at [Deprecated Developer Processes](develop-deprecated.md).
+Developing CiviCRM
+==================
+
+Repositories
+------------
+
+CiviCRM is divided into a few repositories. This allows developers to work
+with different components, allows different teams to manage each component,
+and will allow all the pieces to be remixed using different tools (civibuild,
+shell scripts, Drush & Drush make, or composer). The repositories are:
+
+- [civicrm-core](https://github.com/civicrm/civicrm-core/) -
+ Core application which can be embedded in different systems
+ (Drupal, Joomla, etc).
+- [civicrm-drupal](https://github.com/civicrm/civicrm-drupal/) -
+ Drupal integration modules, with branches for each CiviCRM release &
+ Drupal major version (e.g. 7.x-4.6, 7.x-4.7, 6.x-4.4, 6.x-4.6).
+- [civicrm-joomla](https://github.com/civicrm/civicrm-joomla/) -
+ Joomla integration modules.
+- [civicrm-wordpress](https://github.com/civicrm/civicrm-wordpress/) -
+ WordPress integration modules.
+- [civicrm-packages](https://github.com/civicrm/civicrm-packages/) -
+ External dependencies required by CiviCRM.
+- [civicrm-l10n](https://github.com/civicrm/civicrm-l10n/) -
+ Localization data.
+
+Obtaining a development build of CiviCRM
+----------------------------------------
+
+The recommended method is to use
+[CiviCRM Buildkit](https://github.com/civicrm/civicrm-buildkit/) to build a
+CiviCRM codebase to develop with.
+
+Deprecated instructions
+-----------------------
+
+Previous methods for obtaining a CiviCRM source build are documented at
+[Deprecated Developer Processes](develop-deprecated.md).
diff --git a/docs/extend-stages.md b/docs/extend-stages.md
index c723c70fe62591e951c678de8b661d8a1dc409e6..6b27d41c3288f58c5672d87df2744d0bf6ec59d5 100644
--- a/docs/extend-stages.md
+++ b/docs/extend-stages.md
@@ -1,5 +1,8 @@
-The CiviCRM ecosystem is built on the belief that non-profit organizations
-can serve themselves best by collaborating in development of their
+Extension Life cycle
+====================
+
+The CiviCRM ecosystem is built on the belief that non-profit
+organizations can serve themselves best by collaborating in development of their
data-management applications. As staff, volunteers, and consultants for
non-profit organizations, we can share our new enhancements and extensions --
and build a richer whole for the entire ecosystem.
@@ -7,50 +10,88 @@ and build a richer whole for the entire ecosystem.
Of course, this sharing arrangement means that many members of the community
have a split role, e.g.
- * Sometimes, we are consumers. We want to quickly browse the available
- extensions, pick the ones which look best, and install them. We
- expect these to just work -- both now and going forward (with future upgrades).
- * Sometimes, we are developers. We enjoy building great functionality, and we
- want to invite people to use our products, but we need to juggle the
- publishing tasks (like testing and maintenance releases) with the goals
- and resources provided by our bosses and clients.
+- Sometimes, we are consumers. We want to quickly browse the available
+ extensions, pick the ones which look best, and install them. We
+ expect these to just work -- both now and going forward (with future
+ upgrades).
+- Sometimes, we are developers. We enjoy building great functionality, and we
+ want to invite people to use our products, but we need to juggle the
+ publishing tasks (like testing and maintenance releases) with the goals
+ and resources provided by our bosses and clients.
The purpose of this document is to describe the process of publishing
extensions through the CiviCRM ecosystem.
-## Definitions
-
- * __Project Maturity__: Should we expect this to work for most users? Should we expect to work in 6 months?
- * __Experimental__: An experimental project offers zero support, stability, or maintenance. It may be useful for discussion, finding collaborators, or proving a concept.
- * __Incubation__: An incubation project offers some degree of support, stability, or maintenance. It's probably in use at multiple organizations. However, the levels are not guaranteed; some gaps and roadbumps should be expected. A project may be "Incubation" for days or months or years.
- * __Stable__: A stable project has undertaken significant efforts to ensure that it works and continues working in the future. It has a strong quality-signal.
- * __Deprecated__: The project is no longer being maintained. It may work today; but it's liable to break tomorrow (unless someone steps up to manage it).
- * __Stewardship__: Who manages a project? Who decides whether the project is experimental? Or maintained? Or unmaintained?
- * __Contributed__: This project is managed by an individual or company in the ecosystem. All design, support, and maintenance are at discretion of the original author.
- * __Official__: The project is monitored as a community resource. Generally, the original author retains editorial control, but the project receives more strenuous reviews and follows stricter standards with feedback from others in the community.
- * __Seeking Maintainer__: This project does not have a person or organization responsible for it. If you think the project is useful, feel free to take responsibility for it.
- * __Support Model__: How do you submit questions and requests about issues?
- * __Free__: Submit questions and requests to an open bug-tracker.
- * __Negotiated__: Issues may be reported to open bug-tracker. If the author agrees it is critical or data-loss, they may address it. Otherwise, you need to negotiate a contract.
- * __Pre-Paid__: The author will not engage in any support discussions unless you have pre-paid for support.
- * __Quality Signals__: How do we know if an extension is any good?
- * __Self-Assessment__: An author makes a claim about the stability of his work. (This is a low-tech, low-touch process.)
- * __Informal Discussion__: One or more experts give gut reactions. (This is a low-tech, high-touch process.)
- * __Formal Review__: One or more experts assesses the quality, maintainability, best-practices, etc. using formal criteria. (This is a low-tech, high-touch process.)
- * __Social Metrics__: Data-points (such as #installations or average 5-star rating) is collected from many people. (This is a high-tech, low-touch process.)
- * __Technical Metrics__: Technical details (such as test-coverage, test-results, style-checks, or cyclomatic complexity) are checked by a bot. (This is a high-tech, low-touch process.)
-
-## Workflow
-
-The database on `civicrm.org` publishes information about available extensions, including maturity and stewardship.
-This is significant because it affects authors (who publish the extension) and users (who download the extension) and
-determines access to communal resources on `civicrm.org`. The particulars are determined the maturity and stewardship
-of the project -- with a few basic rules of thumb:
-
- * The author always registers his extension on `civicrm.org` by creating an `extension` node.
- * *Official* extensions are subject to more scrutiny than *Contributed* extensions.
- * *Experimental*, *Incubation*, and *Deprecated* extensions have simple, open processes -- such as *Self-Assessment* or *Informal Discussion*.
- * *Stable* extensions require some kind of *Formal Review*.
+Definitions
+-----------
+
+- **Project Maturity**: Should we expect this to work for most users? Should
+ we expect to work in 6 months?
+ - **Experimental**: An experimental project offers zero support,
+ stability, or maintenance. It may be useful for discussion, finding
+ collaborators, or proving a concept.
+ - **Incubation**: An incubation project offers some degree of support,
+ stability, or maintenance. It's probably in use at multiple
+ organizations. However, the levels are not guaranteed; some gaps and
+ road bumps should be expected. A project may be "Incubation" for days
+ or months or years.
+ - **Stable**: A stable project has undertaken significant efforts to
+ ensure that it works and continues working in the future. It has a
+ strong quality-signal.
+ - **Deprecated**: The project is no longer being maintained. It may work
+ today; but it's liable to break tomorrow (unless someone steps up to
+ manage it).
+- **Stewardship**: Who manages a project? Who decides whether the project is
+ experimental? Or maintained? Or unmaintained?
+ - **Contributed**: This project is managed by an individual or company in
+ the ecosystem. All design, support, and maintenance are at discretion
+ of the original author.
+ - **Official**: The project is monitored as a community resource.
+ Generally, the original author retains editorial control, but the
+ project receives more strenuous reviews and follows stricter standards
+ with feedback from others in the community.
+ - **Seeking Maintainer**: This project does not have a person or
+ organization responsible for it. If you think the project is useful,
+ feel free to take responsibility for it.
+- **Support Model**: How do you submit questions and requests about issues?
+ - **Free**: Submit questions and requests to an open bug-tracker.
+ - **Negotiated**: Issues may be reported to open bug-tracker. If the
+ author agrees it is critical or data-loss, they may address it.
+ Otherwise, you need to negotiate a contract.
+ - **Pre-Paid**: The author will not engage in any support discussions
+ unless you have pre-paid for support.
+- **Quality Signals**: How do we know if an extension is any good?
+ - **Self-Assessment**: An author makes a claim about the stability of his
+ work. (This is a low-tech, low-touch process.)
+ - **Informal Discussion**: One or more experts give gut reactions. (This
+ is a low-tech, high-touch process.)
+ - **Formal Review**: One or more experts assesses the quality,
+ maintainability, best-practices, etc. using formal criteria. (This is a
+ low-tech, high-touch process.)
+ - **Social Metrics**: Data-points (such as #installations or average
+ 5-star rating) is collected from many people. (This is a high-tech,
+ low-touch process.)
+ - **Technical Metrics**: Technical details (such as test-coverage,
+ test-results, style-checks, or cyclomatic complexity) are checked by a
+ bot. (This is a high-tech, low-touch process.)
+
+Workflow
+--------
+
+The database on `civicrm.org` publishes information about available extensions,
+including maturity and stewardship. This is significant because it affects
+authors (who publish the extension) and users (who download the extension) and
+determines access to communal resources on `civicrm.org`. The particulars are
+determined the maturity and stewardship of the project -- with a few basic
+rules of thumb:
+
+- The author always registers his extension on `civicrm.org` by creating an
+ `extension` node.
+- *Official* extensions are subject to more scrutiny than *Contributed*
+ extensions.
+- *Experimental*, *Incubation*, and *Deprecated* extensions have simple, open
+ processes -- such as *Self-Assessment* or *Informal Discussion*.
+- *Stable* extensions require some kind of *Formal Review*.
Based on these rules, we can fill out a full table of the workflow:
@@ -67,11 +108,13 @@ Based on these rules, we can fill out a full table of the workflow:
| Deprecated | Official | Informal Discussion | The author announces intent to deprecate in a high-visibility medium. If discussion is persuasive and no alternative maintainer comes forward, a senior member of core team flags the project as official. | Locate the extension on the website. View a block which says, "Install Instructions", which includes drush/wp-cli commands.
-## Formal Review
+Formal Review
+-------------
-To designate an extension as *Stable*, someone must conduct a *Formal Review* and assess several criteria.
-As a rule of thumb, *Contributed* extensions are subject to a gentler review (fewer criteria), and *Official*
-extensions are subject to more stringent review (more criteria).
+To designate an extension as *Stable*, someone must conduct a *Formal Review*
+and assess several criteria. As a rule of thumb, *Contributed* extensions are
+subject to a gentler review (fewer criteria), and *Official* extensions are
+subject to more stringent review (more criteria).
| | | Contributed | Official |
|------ | ----- | ----------------------------- | --------------------- |
@@ -99,9 +142,11 @@ extensions are subject to more stringent review (more criteria).
| Support | Publish documentation | Suggested (Not Required) | Required
| Support | Track issues in an open, public issue management system | Suggested (Not Required) | Required
-## Benefits
+Benefits
+--------
-Based on a project's maturity and stewardship, it may be eligible to use resources from `civicrm.org`.
+Based on a project's maturity and stewardship, it may be eligible to use
+resources from `civicrm.org`.
| Action Type | Benefit/Resource/Privilege | Eligibility |
| ----------- | ---------------------------- | ----------- |
diff --git a/docs/extend.md b/docs/extend.md
index 2d780924736a5e90407b224b4bad07ff0eb24ab4..cd6d76ad89b88058b3f14b982bc96da398bb04d1 100644
--- a/docs/extend.md
+++ b/docs/extend.md
@@ -1,12 +1,18 @@
-**CiviCRM Extensions** are packaged pieces of functionality that extend CiviCRM's out-of-the-box functionality, independent of CMS plaform.
+Creating CiviCRM Extensions
+===========================
-This section covers writing extensions, submitting extensions to the public extensions directory, and the review process for extensions submitted to the directory.
+**CiviCRM Extensions** are packaged pieces of functionality that extend
+CiviCRM's out-of-the-box functionality, independent of CMS plaform.
+
+This section covers writing extensions, submitting extensions to the public
+extensions directory, and the review process for extensions submitted to the
+directory.
TODO:
- * General overview: Use APIv3 and hooks. Package code in Civi extensions or CMS extensions (w/trade-offs).
- * Assimilate: http://wiki.civicrm.org/confluence/display/CRMDOC/Create+an+Extension
- * Assimilate: http://wiki.civicrm.org/confluence/display/CRMDOC/Publish+an+Extension
- * Assimilate: https://wiki.civicrm.org/confluence/display/CRMDOC/Extension+Review
- * Create a CiviCRM extension developer's guide to best practices (Nicolas?)
- * Reference this page from the wiki and also https://civicrm.org/extensions (in the header).
+- General overview: Use APIv3 and hooks. Package code in Civi extensions or CMS extensions (w/trade-offs).
+- Assimilate: http://wiki.civicrm.org/confluence/display/CRMDOC/Create+an+Extension
+- Assimilate: http://wiki.civicrm.org/confluence/display/CRMDOC/Publish+an+Extension
+- Assimilate: https://wiki.civicrm.org/confluence/display/CRMDOC/Extension+Review
+- Create a CiviCRM extension developer's guide to best practices (Nicolas?)
+- Reference this page from the wiki and also https://civicrm.org/extensions (in the header).
diff --git a/docs/git.md b/docs/git.md
deleted file mode 100644
index e39ae08c0578f4d000e9948d05d792351248b96c..0000000000000000000000000000000000000000
--- a/docs/git.md
+++ /dev/null
@@ -1,13 +0,0 @@
-# Git and GitHub
-
-**Git** is a "source-code management system" or "version control system" – an alternative to Subversion. It was designed for a large open-source project (Linux) and has seen broad adoption among other FOSS projects. **GitHub** is a company which provides hosted, web-based tools for enhancing Git development. For open projects like CiviCRM, its services are free.
-
-Git and GitHub offer advantages for CiviCRM development:
-
-* The tools are already popular among FOSS projects and web developers.
-* The tools are free ("as in beer") and mostly free ("as in speech").
-* They support off-line development.
-* They support lightweight branching, merging, and code-review.
-* They support open teams – anyone can jump-in, make changes, and share changes.
-
-For more introductions to Git and Github, see [help.github.com](https://help.github.com/).
diff --git a/docs/hook.md b/docs/hook.md
index 9314358639983098b24c16af8b82dc345c3f1a20..d833202d81990ba45a184cd871067bd81a1ef41f 100644
--- a/docs/hook.md
+++ b/docs/hook.md
@@ -1,94 +1,135 @@
-*The hooks*
+How to use hooks
+================
TODO:
- * http://wiki.civicrm.org/confluence/display/CRMDOC/Hooks
- * http://wiki.civicrm.org/confluence/display/CRMDOC/Hook+Reference
-
-Hooks are a common way to extend systems. The way they work in CiviCRM is that, at key points in processing - such as saving a change or displaying a page - CiviCRM checks to see whether you've "hooked in" some custom code, and runs any valid code it finds.
+- http://wiki.civicrm.org/confluence/display/CRMDOC/Hooks
+- http://wiki.civicrm.org/confluence/display/CRMDOC/Hook+Reference
-For example, let's say you want to send an email message to someone in your organization every time a contact in a particular group is edited. Hooks allow you to do this by defining a function with a specific name and adding it to your organisation's CiviCRM installation. The name of the function indicates the point at which CiviCRM should call it. CiviCRM looks for appropriate function names and calls the functions whenever it performs the indicated operations.
+Hooks are a common way to extend systems. The way they work in CiviCRM is that,
+at key points in processing - such as saving a change or displaying a page -
+CiviCRM checks to see whether you've "hooked in" some custom code, and runs any
+valid code it finds.
-Hooks are a powerful way to extend CiviCRM's functionality, incorporate additional business logic, and even integrate CiviCRM with external systems. Many CiviCRM developers find themselves using them in nearly every customization project.
+For example, let's say you want to send an email message to someone in your
+organization every time a contact in a particular group is edited. Hooks allow
+you to do this by defining a function with a specific name and adding it to your
+organisation's CiviCRM installation. The name of the function indicates the
+point at which CiviCRM should call it. CiviCRM looks for appropriate function
+names and calls the functions whenever it performs the indicated operations.
-A good test for whether or not to use a hook is to ask yourself whether what you're trying to do can be expressed with a sentence like this: "I want X to happen every time someone does Y."
+Hooks are a powerful way to extend CiviCRM's functionality, incorporate
+additional business logic, and even integrate CiviCRM with external systems.
+Many CiviCRM developers find themselves using them in nearly every customization
+project.
-How to use hooks
-================
+A good test for whether or not to use a hook is to ask yourself whether what
+you're trying to do can be expressed with a sentence like this: "I want X to
+happen every time someone does Y."
-How you use hooks depends on whether you're using CiviCRM with Drupal or Joomla!.
Using hooks with Drupal
-----------------------
-Check the CiviCRM wiki page for the most up-to-date information on setting up hooks with Drupal:
-
-* [http://tiny.booki.cc/?hooks-in-drupal](http://tiny.booki.cc/?hooks-in-drupal)
-
-* [http://wiki.civicrm.org/confluence/display/CRMDOC/CiviCRM+hook+specification\#CiviCRMhookspecification-Proceduresforimplementinghooks%28forDrupal%29](http://wiki.civicrm.org/confluence/display/CRMDOC/CiviCRM+hook+specification#CiviCRMhookspecification-Proceduresforimplementinghooks%28forDrupal%29)
-
-In order to start using hooks with a Drupal-based CiviCRM installation, you or your administrator needs to do the following:
-
-1. Create a file with the extension .info (for instance, myhooks.info) containing the following lines. Replace the example text in the first 2 lines with something appropriate for your organization, and assign 7.x to core if you use Drupal 7.
-```
-name = My Organization's Hooks
-description = Module containing the CiviCRM hooks for my organization
-dependencies[] = civicrm
-package = CiviCRM
-core = 7.x
-version = 7.x-1.0
-```
-
-2. Create a new file with the extension *.module* (for instance, *myhooks.module*) to hold your PHP functions.
-3. Upload both the *.info* and *.module* files to the server running CiviCRM, creating a new directory for them under
- */sites/all/modules* (for instance, */sites/all/modules/myhooks/*) inside your Drupal installation. The directory name you create should be short and contain only lowercase letters, digits, and underlines without spaces.
+In order to start using hooks with a Drupal-based CiviCRM installation, you or
+your administrator needs to do the following:
+
+1. Create a file with the extension .info (for instance, myhooks.info)
+ containing the following lines. Replace the example text in the first 2
+ lines with something appropriate for your organization, and assign 7.x
+ to core if you use Drupal 7.
+
+ name = My Organization's Hooks
+ description = Module containing the CiviCRM hooks for my organization
+ dependencies[] = civicrm
+ package = CiviCRM
+ core = 7.x
+ version = 7.x-1.0
+
+2. Create a new file with the extension *.module* (for instance,
+ *myhooks.module*) to hold your PHP functions.
+3. Upload both the *.info* and *.module* files to the server running CiviCRM,
+ creating a new directory for them under */sites/all/modules* (for
+ instance, */sites/all/modules/myhooks/*) inside your Drupal installation.
+ The directory name you create should be short and contain only lowercase
+ letters, digits, and underlines without spaces.
4. Enable your new hooks module through the Drupal administration page.
-NOTE that if you use certain Drupal functions from within CiviCRM, you could break whatever form you're working with! To prevent very hard-to-troubleshoot errors, do the following (at least for user\_save() with Drupal 6, possibly others):
+Note that if you use certain Drupal functions from within CiviCRM, you could
+break whatever form you're working with! To prevent very hard-to-troubleshoot
+errors, do the following (at least for `user_save()` with Drupal 6, possibly
+others):
-````
+```php
$config = CRM_Core_Config::singleton();
-````
+```
-````
+```php
$config->inCiviCRM = TRUE;
-````
+```
-````
+```php
$user = user_save('',array(..));
-````
+```
-````
+```php
$config->inCiviCRM = FALSE;
-````
+```
Using hooks with Joomla!
------------------------
-Hooks may be implemented in Joomla in two ways, depending on the version of CiviCRM and Joomla you are using. For sites running Joomla 1.5 with CiviCRM up to and including version 3.4, you implement hooks with a single civicrmHooks.php in your php override directory. Sites running Joomla 1.6+ and CiviCRM 4+ may implement with either that single hooks
-file, or by creating a Joomla plugin. In general, implementing through a plugin is preferred as you can benefit from the native access control within the plugin structure, include code that responds to other Joomla events, organize your hook implementations into multiple plugins which may be enabled/disabled as desired, and roughly follow the event-observer pattern intended by Joomla plugins.
+Hooks may be implemented in Joomla in two ways, depending on the version of
+CiviCRM and Joomla you are using. For sites running Joomla 1.5 with CiviCRM up
+to and including version 3.4, you implement hooks with a single civicrmHooks.php
+in your php override directory. Sites running Joomla 1.6+ and CiviCRM 4+ may
+implement with either that single hooks file, or by creating a Joomla plugin.
+In general, implementing through a plugin is preferred as you can benefit from
+the native access control within the plugin structure, include code that
+responds to other Joomla events, organize your hook implementations into
+multiple plugins which may be enabled/disabled as desired, and roughly follow
+the event-observer pattern intended by Joomla plugins.
-As you implement hooks in Joomla, be sure to check the CiviCRM wiki for the most up-to-date information:
+As you implement hooks in Joomla, be sure to check the CiviCRM wiki for the
+most up-to-date information:
-* [http://tiny.booki.cc/?hooks-in-joomla](http://tiny.booki.cc/?hooks-in-joomla)
-* [http://wiki.civicrm.org/confluence/display/CRMDOC/CiviCRM+hook+specification\#CiviCRMhookspecification-Proceduresforimplementinghooks%28forJoomla%29](http://wiki.civicrm.org/confluence/display/CRMDOC/CiviCRM+hook+specification#CiviCRMhookspecification-Proceduresforimplementinghooks%28forJoomla%29)
+- [http://tiny.booki.cc/?hooks-in-joomla](http://tiny.booki.cc/?hooks-in-joomla)
+- [http://wiki.civicrm.org/confluence/display/CRMDOC/CiviCRM+hook+specification\#CiviCRMhookspecification-Proceduresforimplementinghooks%28forJoomla%29](http://wiki.civicrm.org/confluence/display/CRMDOC/CiviCRM+hook+specification#CiviCRMhookspecification-Proceduresforimplementinghooks%28forJoomla%29)
To implement hooks with a single file, you will do the following:
-1. If you have not done so already, create a new directory on your server to store your PHP override files. In Joomla, that is commonly placed in the media folder, as it will not be impacted by Joomla and CiviCRM upgrades. For example, you might create the following folder: */var/www/media/civicrm/customphp*.
-2. If you have not done so already, configure your system to reference the folder you've created as your override directory. Go to: CiviCRM Administer \> Global Settings \> Directories. Change the value of Custom PHP Path Directory to the absolute path for the new directory (e.g., "/var/www/media/civicrm/customphp" if you used that suggestion in the earlier step). The custom override directory may also be used to store modified copies of core files -- thus overriding them. You may want to familiarize yourself with its purpose if you are not yet.
-3. Create a file named *civicrmHooks.php* to contain your hook implementations, and upload the file to the directory you just
- created.
-4. Within that file, your hooks will be implemented by calling the hook function prefaced by "joomla\_". For example, you would call the buildForm hook (used to modify form rendering and functionality) by adding the following function to your hook file:
-
-```
+1. If you have not done so already, create a new directory on your server to
+ store your PHP override files. In Joomla, that is commonly placed in the
+ media folder, as it will not be impacted by Joomla and CiviCRM upgrades.
+ For example, you might create the following
+ folder: `/var/www/media/civicrm/customphp`.
+2. If you have not done so already, configure your system to reference the
+ folder you've created as your override directory. Go to: CiviCRM
+ Administer > Global Settings > Directories. Change the value of Custom
+ PHP Path Directory to the absolute path for the new directory (e.g.,
+ "/var/www/media/civicrm/customphp" if you used that suggestion in the
+ earlier step). The custom override directory may also be used to store
+ modified copies of core files -- thus overriding them. You may want to
+ familiarize yourself with its purpose if you are not yet.
+3. Create a file named *civicrmHooks.php* to contain your hook
+ implementations, and upload the file to the directory you just created.
+4. Within that file, your hooks will be implemented by calling the hook
+ function prefaced by "joomla\_". For example, you would call the buildForm
+ hook (used to modify form rendering and functionality) by adding the
+ following function to your hook file:
+
+```php
function joomla_civicrm_buildForm( $formName, &$form ) {
-
//your custom code
-}
+}
```
-If you are implementing hooks with a Joomla plugin, you will create a standard, installable plugin package. At a minimum, a plugin extension will consist of an xml file (defining the plugin and its parameters), and a php file. Within the php file, define a class that extends the Joomla JPlugin class, and call your hooks but adding the appropriate functions. For example, your plugin file may look like the following:
+If you are implementing hooks with a Joomla plugin, you will create a standard,
+installable plugin package. At a minimum, a plugin extension will consist of an
+xml file (defining the plugin and its parameters), and a php file. Within the
+php file, define a class that extends the Joomla JPlugin class, and call your
+hooks but adding the appropriate functions. For example, your plugin file may
+look like the following:
```
defined('_JEXEC') or die;
@@ -96,74 +137,95 @@ jimport('joomla.plugin.plugin');
class plgCiviCRMMyPlugin extends JPlugin {
public function civicrm_tabs(&$tabs, $contactID) {
-
//your code to alter the contact summary tabs
-
}
}
```
-The first two lines are required -- the first is for security purposes, and ensures the code will exit if it has not been called from within Joomla. The second includes the necessary parent plugin class.
+The first two lines are required -- the first is for security purposes, and
+ensures the code will exit if it has not been called from within Joomla. The
+second includes the necessary parent plugin class.
-Joomla plugin classes follow standard naming conventions which you should follow. By naming this plugin class "plgCiviCRMMyPlugin," I am stating that the plugin resides in the plugin/civicrm/ folder, and the plugin file is named "myplugin.php."
+Joomla plugin classes follow standard naming conventions which you should
+follow. By naming this plugin class "plgCiviCRMMyPlugin," I am stating that the
+plugin resides in the plugin/civicrm/ folder, and the plugin file is named
+"myplugin.php."
-For more information about implementing hooks through plugins, visit this blog article:
+For more information about implementing hooks through plugins, see this [blog
+article](http://civicrm.org/blogs/mcsmom/hooks-and-joomla)
-* [http://civicrm.org/blogs/mcsmom/hooks-and-joomla](http://civicrm.org/blogs/mcsmom/hooks-and-joomla).
-
-Note the reference in the comments to a sample plugin which you can download and modify.
+Note the reference in the comments to a sample plugin which you can download
+and modify.
Refine what you want to act upon
--------------------------------
-When you create a hook, it will be called for all the types of entities. For instance, a civicrm\_post is called after the creation or modification of any object of any type (contact, tag, group, activity, etc.). But usually, you want to launch an action only for a specific type of entity.
+When you create a hook, it will be called for all the types of entities. For
+instance, a civicrm\_post is called after the creation or modification of any
+object of any type (contact, tag, group, activity, etc.). But usually, you want
+to launch an action only for a specific type of entity.
-So a hook generally starts with a test on the type of entity or type of action. For instance, if you want to act only when a new individual contact is created or modified(does this match the code?), start your civicrm\_post hook with:
+So a hook generally starts with a test on the type of entity or type of action.
+For instance, if you want to act only when a new individual contact is created
+or modified (does this match the code?), start your `civicrm_post` hook with:
-```
-if ($objectName != "Individual" || $op != "edit") { return; }
+```php
+if ($objectName != "Individual" || $op != "edit") { return; }
```
-On the other hand, if you want to run multiple hooks within the same function, you don't want to return from any single hook. Instead, you can nest the entire code for each hook within your test:
+On the other hand, if you want to run multiple hooks within the same function,
+you don't want to return from any single hook. Instead, you can nest the entire
+code for each hook within your test:
-```
-if ($objectName == "Individual" && $op == "edit") { // Your hook }
+```php
+if ($objectName == "Individual" && $op == "edit") { // Your hook }
```
Pitfalls of hooks
-----------------
-Because you have little control over what CiviCRM passes to your hook function, it is very helpful to look inside those objects (especially **\$objectRef**) to make sure you're getting what you expect. A good debugger is indispensable here. See the Developer Tips & Tricks chapter at the end of this section for more information on setting up a debugger for your development environment.
+Because you have little control over what CiviCRM passes to your hook function,
+it is very helpful to look inside those objects (especially `$objectRef`) to
+make sure you're getting what you expect. A good debugger is indispensable here.
+See the Developer Tips & Tricks chapter at the end of this section for more
+information on setting up a debugger for your development environment.
Examples of using hooks
-----------------------
-Some example hooks follow. Consult the hooks reference documentation on the CiviCRM wiki to see the full extent of what you can do:
-
-* [http://wiki.civicrm.org/confluence/display/CRMDOC/CiviCRM+hook+specification](http://wiki.civicrm.org/confluence/display/CRMDOC/CiviCRM+hook+specification)
+Some example hooks follow.
-In all of these examples, you'll put the code we provide into your *myhooks.module* file if using Drupal, or the *civicrmHooks.php* file if using Joomla!. Be sure to upload the file after each change to the appropriate location on your server to see the new code take effect.
+In all of these examples, you'll put the code we provide into your
+`myhooks.module` file if using Drupal, or the `civicrmHooks.php` file if using
+Joomla!. Be sure to upload the file after each change to the appropriate
+location on your server to see the new code take effect.
-Additionally, if you are using Drupal and add a new hook to an existing module, you will need to clear the cache for the hook to start operating. One way of doing this is by visiting the page Admin \> Build \> Modules.
+Additionally, if you are using Drupal and add a new hook to an existing module,
+you will need to clear the cache for the hook to start operating. One way of
+doing this is by visiting the page Admin > Build > Modules.
-Sending an email message when a contact in a particular group is edited
-------
+### Sending an email message when a contact in a particular group is edited
-In order to have CiviCRM tell you when a contact is edited, define the civicrm\_pre hook. This lets you see the incoming edits as well as the values of the existing record, because you may want to include that information in the email.
+In order to have CiviCRM tell you when a contact is edited, define the
+`civicrm_pre` hook. This lets you see the incoming edits as well as the values
+of the existing record, because you may want to include that information in the
+email.
-If you are using Drupal, create a function named *myhooks***\_civicrm\_pre**. If using Joomla!, create a function named
-**joomla\_civicrm\_pre**. We'll assume you're using Drupal for the rest of the example, so please adjust the code accordingly if you're using Joomla! instead.
+If you are using Drupal, create a function named `myhooks_civicrm_pre`.
+If using Joomla!, create a function named `joomla_civicrm_pre`. We'll
+assume you're using Drupal for the rest of the example, so please adjust the
+code accordingly if you're using Joomla! instead.
-````
+```php
<?php function myhooks_civicrm_pre( $op, $objectName, $objectId, &$objectRef ) {
-# configuration stuff
-$theGroupId = 1;
+# configuration stuff
+$theGroupId = 1;
-# group id we want the contacts to be in
-$emailRecipient = 'johndoe@example.org';
+# group id we want the contacts to be in
+$emailRecipient = 'johndoe@example.org';
-# person to e-mail
+# person to e-mail
# Make sure we just saved an Individual contact and that it was edited
if ($objectName == "Individual" && $op == "edit") {
@@ -171,172 +233,190 @@ $emailRecipient = 'johndoe@example.org';
# Now see if it's in the particular group we're interested in
require_once 'api/v2/GroupContact.php';
- $params = array('contact_id' => $objectId);
- $groups = civicrm_group_contact_get( $params );
- $found = false;
- foreach ($groups as $group) {
- if ($group['group_id'] == $theGroupId) {
- $found = true;
- }
- }
-
- # Exit now if contact wasn't in the group we wanted
+ $params = array('contact_id' => $objectId);
+ $groups = civicrm_group_contact_get( $params );
+ $found = false;
+ foreach ($groups as $group) {
+ if ($group['group_id'] == $theGroupId) {
+ $found = true;
+ }
+ }
+
+ # Exit now if contact wasn't in the group we wanted
if (! $found) {
return;
- }
+ }
- # We found the contact in the group we wanted, send the e-mail
+ # We found the contact in the group we wanted, send the e-mail
- $emailSubject = "Contact was edited";
- $emailBody = "Someone edited contactId $objectId\n";
+ $emailSubject = "Contact was edited";
+ $emailBody = "Someone edited contactId $objectId\n";
- # Here's where you may want to iterate over the fields
- # and compare them so you can report on what has changed.
- mail( $emailRecipient, $emailSubject, $emailBody );
- }
+ # Here's where you may want to iterate over the fields
+ # and compare them so you can report on what has changed.
+ mail( $emailRecipient, $emailSubject, $emailBody );
+ }
}
+```
-````
-
-Validating a new contribution against custom business rules
-------
+### Validating a new contribution against custom business rules
-If you have experience with other hook-based systems, you might think that the civicrm\_pre hook is the one to use for validations. But this is not the case in CiviCRM because, even though the civicrm\_pre hook is called before the record is saved to the database, you cannot abort the action from this hook.
+If you have experience with other hook-based systems, you might think that the
+`civicrm_pre` hook is the one to use for validations. But this is not the case
+in CiviCRM because, even though the `civicrm_pre` hook is called before the
+record is saved to the database, you cannot abort the action from this hook.
-This is where validation hooks come in. When you return true from a validation hook, CiviCRM saves the new or updated record. When you return an error object instead, CiviCRM aborts the operation and reports your error to the user.
+This is where validation hooks come in. When you return true from a validation
+hook, CiviCRM saves the new or updated record. When you return an error object
+instead, CiviCRM aborts the operation and reports your error to the user.
-An example follows of using a validation hook to validate new contributions against a business rule that says campaign contributions must have a source associated with them. In this example, we'll assume you are using Joomla!, so if you are using Drupal instead, be sure to change the function name accordingly.
+An example follows of using a validation hook to validate new contributions
+against a business rule that says campaign contributions must have a source
+associated with them. In this example, we'll assume you are using Joomla!, so if
+you are using Drupal instead, be sure to change the function name accordingly.
-````
-<?php function joomla_civicrm_validate( $formName, &$fields, &$files, &$form ) {
- # configuration stuff
- $campaignContributionTypeId = 3;
- # adjust for your site if different
+```php
+<?php function joomla_civicrm_validate( $formName, &$fields, &$files, &$form ) {
+ # configuration stuff
+ $campaignContributionTypeId = 3;
+ # adjust for your site if different
$errors = array();
- # $formName will be set to the class name of the form that was posted
-
- if ($formName == 'CRM_Contribute_Form_Contribution') {
-
- require_once 'CRM/Utils/Array.php';
- $contributionTypeId = CRM_Utils_Array::value( 'contribution_type_id', $fields );
-
- if ($contributionTypeId == $campaignContributionTypeId) {
- # see if the source field is blank or not
- $source = CRM_Utils_Array::value( 'source', $fields );
- if (strlen( $source ) > 0) {
- # tell CiviCRM to proceed with saving the contribution
- return true;
- } else {
- # source is blank, bzzzzzzzzzzzt!
- # assign the error to a key corresponding to the field name
+ # $formName will be set to the class name of the form that was posted
+
+ if ($formName == 'CRM_Contribute_Form_Contribution') {
+
+ require_once 'CRM/Utils/Array.php';
+ $contributionTypeId = CRM_Utils_Array::value( 'contribution_type_id', $fields );
+
+ if ($contributionTypeId == $campaignContributionTypeId) {
+ # see if the source field is blank or not
+ $source = CRM_Utils_Array::value( 'source', $fields );
+ if (strlen( $source ) > 0) {
+ # tell CiviCRM to proceed with saving the contribution
+ return true;
+ } else {
+ # source is blank, bzzzzzzzzzzzt!
+ # assign the error to a key corresponding to the field name
$errors['source'] = "Source must contain the campaign identifier for campaign contributions";
- return $errors;
- }
- } else {
- # not a campaign contribution, let it through
- return true;
- }
- }
+ return $errors;
+ }
+ } else {
+ # not a campaign contribution, let it through
+ return true;
+ }
+ }
}
-````
+```
-Automatically filling custom field values based on custom business logic
---------
+### Automatically filling custom field values based on custom business logic
-This example uses a hook to write some data back to CiviCRM. You can make a custom field read-only and then set its value from a hook. This is very handy for storing and displaying data that are derived from other attributes of a record based on custom business logic.
+This example uses a hook to write some data back to CiviCRM. You can make a
+custom field read-only and then set its value from a hook. This is very handy
+for storing and displaying data that are derived from other attributes of a
+record based on custom business logic.
-For example, let's say you are storing employee records and you want to auto-generate their network login account when new employees are added. By doing it in your code, you can enforce a policy for login account names. For this example, let's say the policy is first initial + last name. So if your name is Jack Frost, your network login name would be jfrost.
+For example, let's say you are storing employee records and you want to
+auto-generate their network login account when new employees are added. By doing
+it in your code, you can enforce a policy for login account names. For this
+example, let's say the policy is first initial + last name. So if your name is
+Jack Frost, your network login name would be jfrost.
-Add a new read-only custom field to CiviCRM called "Network Login" and then find its ID. You can find it either by:
+Add a new read-only custom field to CiviCRM called "Network Login" and then
+find its ID. You can find it either by:
-- Checking the civicrm\_custom\_field table in your CiviCRM database.
+- Checking the `civicrm_custom_field` table in your CiviCRM database.
- Editing a contact and check the name of the Network Login field.
-The code must refer to the ID as **custom**\_*id*. So if you find that
-the id of the new field is 74, refer to is as **custom\_74** in your
-code.
+The code must refer to the ID as `custom_id`. So if you find that
+the id of the new field is `74`, refer to is as `custom_74` in your code.
-Now that we have our Network Login field, let's see how to populate it automatically with a hook. We'll switch back to the Drupal naming convention for this example.
+Now that we have our Network Login field, let's see how to populate it
+automatically with a hook. We'll switch back to the Drupal naming convention for
+this example.
-Note that we use the civicrm\_post hook here because we need the new contact record's ID in order to save a value to one of its custom fields. New records don't have an ID until they have been saved in the database, so if we ran this code in the civicrm\_pre hook, it would fail.
+Note that we use the `civicrm_post` hook here because we need the new contact
+record's ID in order to save a value to one of its custom fields. New records
+don't have an ID until they have been saved in the database, so if we ran this
+code in the `civicrm_pre hook`, it would fail.
```
-<?php function myhooks_civicrm_post( $op, $objectName, $objectId, &$objectRef ) {
- # configuration stuff
- $customId = 74;
- if ($objectName == 'Individual' && $op == 'create') {
- # generate the login
- $firstName = $objectRef->first_name;
- $lastName = $objectRef->last_name;
- $firstInitial = substr( $firstName, 0, 1 );
- $networkLogin = strtolower( $firstInitial . $lastName );
- # assign to the custom field
- $customParams = array("entityID" => $objectId,
- "custom_$customId" => $networkLogin);
- require_once 'CRM/Core/BAO/CustomValueTable.php';
- CRM_Core_BAO_CustomValueTable::setValues( $customParams );
- }
+<?php function myhooks_civicrm_post( $op, $objectName, $objectId, &$objectRef ) {
+ # configuration stuff
+ $customId = 74;
+ if ($objectName == 'Individual' && $op == 'create') {
+ # generate the login
+ $firstName = $objectRef->first_name;
+ $lastName = $objectRef->last_name;
+ $firstInitial = substr( $firstName, 0, 1 );
+ $networkLogin = strtolower( $firstInitial . $lastName );
+ # assign to the custom field
+ $customParams = array("entityID" => $objectId,
+ "custom_$customId" => $networkLogin);
+ require_once 'CRM/Core/BAO/CustomValueTable.php';
+ CRM_Core_BAO_CustomValueTable::setValues( $customParams );
+ }
}
```
-Custom mail merge token
------------
+### Custom mail merge token
-The CiviMail component lets you customise a bulk email message using mail merge tokens. For instance, you can begin your message with, "Hi, {recipient.first\_name}!" and when John Doe receives it, he'll see, "Hi, John!" whereas when Suzy Queue receives it, she'll see, "Hi, Suzy!" You can find out more details about working with custom tokens on the CiviCRM wiki:
+The CiviMail component lets you customize a bulk email message using mail merge
+tokens. For instance, you can begin your message with, "Hi,
+{recipient.first_name}!" and when John Doe receives it, he'll see, "Hi, John!"
+whereas when Suzy Queue receives it, she'll see, "Hi, Suzy!"
-* [http://wiki.civicrm.org/confluence/display/CRMDOC/Mail-merge+Tokens+for+Contact+Data](http://wiki.civicrm.org/confluence/display/CRMDOC/Mail-merge+Tokens+for+Contact+Data).
+Besides the built-in tokens, you can use a hook to create new custom tokens.
+Let's make a new one that will show the largest contribution each recipient has
+given in the past. We'll use Drupal syntax again for this one.
-Besides the built-in tokens, you can use a hook to create new custom tokens. Let's make a new one that will show the largest contribution each recipient has given in the past. We'll use Drupal syntax again for this one.
+```php
+# implement the tokens hook so we can add our new token to the list of tokens
+# displayed to CiviMail users
-```
-# implement the tokens hook so we can add our new token to the list of tokens
-# displayed to CiviMail users
-
-function myhooks_civicrm_tokens( &$tokens ) {
- $tokens['contribution'] =
- array('contribution.largest' => 'Largest Contribution');
- /* just array('contribution.largest'); in 3.1 or earlier */
+function myhooks_civicrm_tokens( &$tokens ) {
+ $tokens['contribution'] =
+ array('contribution.largest' => 'Largest Contribution');
+ /* just array('contribution.largest'); in 3.1 or earlier */
}
-# now we'll set the value of our custom token;
-# it's better in general to use the API rather than SQL queries to retrieve data,
-# but in this case the MAX() function makes it very efficient to get the largest
-# contribution, so let's make an exception
-
-function myhooks_civicrm_tokenValues( &$details, &$contactIDs ) {
- # prepare the contact ID(s) for use in a database query
- if ( is_array( $contactIDs ) ) {
- $contactIDString = implode( ',', array_values( $contactIDs ) );
- $single = false;
- } else {
- $contactIDString = "( $contactIDs )";
- $single = true;
- }
- # build the database query
- $query = "SELECT contact_id,
- max( total_amount ) as total_amount
- FROM civicrm_contribution
- WHERE contact_id IN ( $contactIDString )
- AND is_test = 0
- GROUP BY contact_id";
-
- # run the query
- $dao = CRM_Core_DAO::executeQuery( $query );
- while ( $dao->fetch( ) ) {
- if ( $single ) {
- $value =& $details;
- } else {
- if ( ! array_key_exists( $dao->contact_id, $details ) ) {
- $details[$dao->contact_id] = array( );
- }
- $value =& $details[$dao->contact_id];
- }
- # set the token's value
- $value['contribution.largest'] = $dao->total_amount;
- }
+# now we'll set the value of our custom token;
+# it's better in general to use the API rather than SQL queries to retrieve data,
+# but in this case the MAX() function makes it very efficient to get the largest
+# contribution, so let's make an exception
+
+function myhooks_civicrm_tokenValues( &$details, &$contactIDs ) {
+ # prepare the contact ID(s) for use in a database query
+ if ( is_array( $contactIDs ) ) {
+ $contactIDString = implode( ',', array_values( $contactIDs ) );
+ $single = false;
+ } else {
+ $contactIDString = "( $contactIDs )";
+ $single = true;
+ }
+ # build the database query
+ $query = "SELECT contact_id,
+ max( total_amount ) as total_amount
+ FROM civicrm_contribution
+ WHERE contact_id IN ( $contactIDString )
+ AND is_test = 0
+ GROUP BY contact_id";
+
+ # run the query
+ $dao = CRM_Core_DAO::executeQuery( $query );
+ while ( $dao->fetch( ) ) {
+ if ( $single ) {
+ $value =& $details;
+ } else {
+ if ( ! array_key_exists( $dao->contact_id, $details ) ) {
+ $details[$dao->contact_id] = array( );
+ }
+ $value =& $details[$dao->contact_id];
+ }
+ # set the token's value
+ $value['contribution.largest'] = $dao->total_amount;
+ }
}
-
```
diff --git a/docs/hooks-db.md b/docs/hooks-db.md
index 98a50408efd3012d57f9078b9585c7ebed3500b9..562b0aa04d7eadba263c93b06f33e59ba1134885 100644
--- a/docs/hooks-db.md
+++ b/docs/hooks-db.md
@@ -1,16 +1,25 @@
+All Available Hooks
+===================
+
+This page provides official documentation on the specifics of each hook
+available within CiviCRM.
+
+**This page is currently incomplete**. Info needs to be moved from this
+[wiki page](https://wiki.civicrm.org/confluence/display/CRMDOC/Hook+Reference)
+
hook_civicrm_copy
=================
This hook is called after a CiviCRM object (Event, ContributionPage, Profile) has been copied
-* Parameters:
+* Parameters:
* $objectName - the name of the object that is being copied (Event, ContributionPage, UFGroup)
* $object - reference to the copied object
-* Returns:
+* Returns:
* null
-* Definition/Example:
+* Definition/Example:
```
hook_civicrm_copy( $objectName, &$object )
```
@@ -27,7 +36,7 @@ This hook is called AFTER the db write on a custom table
* object $entityID - the entityID of the row in the custom table
* array $params - the parameters that were sent into the calling function
-* Returns:
+* Returns:
* null - the return value is ignored
* Definition/Example:
@@ -36,34 +45,34 @@ This hook is called AFTER the db write on a custom table
/**
* 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 );
}
@@ -98,7 +107,7 @@ For more background, see [API and the Art of Installation](http://civicrm.org/bl
* void - the return value is ignored
-* Definition/Example:
+* Definition/Example:
```
/**
@@ -144,13 +153,13 @@ 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:
-
+
`'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.
@@ -180,7 +189,7 @@ hook_civicrm_merge ( $type, &$data, $mainId = NULL, $otherId = NULL, $tables = N
* 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;
@@ -191,7 +200,7 @@ function civitest_civicrm_merge ( $type, &$data, $mainId = NULL, $otherId = NULL
else {
$db_default = '';
}
-
+
switch ($type) {
case 'relTables':
// Allow user to decide whether or not to merge records in `civitest_foo` table
@@ -205,14 +214,14 @@ function civitest_civicrm_merge ( $type, &$data, $mainId = NULL, $otherId = NULL
// 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
@@ -220,7 +229,7 @@ function civitest_civicrm_merge ( $type, &$data, $mainId = NULL, $otherId = NULL
// 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`
@@ -236,7 +245,7 @@ function civitest_civicrm_merge ( $type, &$data, $mainId = NULL, $otherId = NULL
// modify existing SQL statements in $data.
}
break;
-
+
}
}
@@ -323,7 +332,7 @@ FILE #2 /drupal_install_dir/sites/all/modules/civicrm/drupal/modules/example_sen
```
<?php
function exampleSendEmailOnIndividual_civicrm_post($op, $objectName, $objectId, &$objectRef) {
-
+
/**************************************************************
* Send an email when Individual Contact is CREATED or EDITED or DELETED
*/
@@ -332,7 +341,7 @@ function exampleSendEmailOnIndividual_civicrm_post($op, $objectName, $objectId,
$email_from = 'me@mydomain.com'; //FROM email address
$email_sbj = 'CiviCRM exampleSendEmailOnIndividual';
$email_msg = "CiviCRM exampleSendEmailOnIndividual was called.\n".$op." ".$objectName."\n".$objectId." ";
-
+
if ($op == 'create' && $objectName == 'Individual') {
$email_sbj .= "- ADDED NEW contact";
$email_msg .= $objectRef->display_name."\n";
@@ -348,11 +357,11 @@ function exampleSendEmailOnIndividual_civicrm_post($op, $objectName, $objectId,
$email_msg .= 'Email: '.$objectRef->email."\n";
$send_an_email = true;
}
-
+
if ($send_an_email) {
mail($email_to, $email_sbj, $email_msg, "From: ".$email_from);
}
-
+
}//end FUNCTION
?>
```
@@ -376,7 +385,7 @@ hook_civicrm_postSave_[table_name]($dao)
```
hook_civicrm_postSave_civicrm_contact($dao) {
$contact_id = $dao->id;
- // Do something with this contact, but be careful not to create an infinite
+ // Do something with this contact, but be careful not to create an infinite
// loop if you update it via the api! This hook will get called again with every update.
}
```
@@ -516,7 +525,7 @@ function regionfields_civicrm_triggerInfo(&$info, $tableName) {
if(civicrm_api3('custom_field', 'getcount', array('id' => $customFieldID, 'column_name' => 'region_45', 'is_active' => 1)) == 0) {
return;
}
-
+
$sql = "
REPLACE INTO `$table_name` (entity_id, $columnName)
SELECT * FROM (
diff --git a/docs/index.md b/docs/index.md
index 14d50dc59816e2d1278f1d3ae40209a288457a96..b42d78cd1c190623137be8d72e0ffd198620f959 100644
--- a/docs/index.md
+++ b/docs/index.md
@@ -1,30 +1,65 @@
-# About this documentation
+CiviCRM Developer Guide
+=======================
-## Overview
+[CiviCRM](https://civicrm.org) is an open-source application. The code can be
+poked, prodded, twisted, and hacked. It can be customized, extended, and
+collaboratively developed. This documentation tells you how to do that.
-[CiviCRM](https://civicrm.org) is an open-source application. The code can be poked, prodded, twisted, and hacked. It can be customized, extended, and collaboratively developed. This documentation tells you how to do that.
+It starts with a high level introduction to get you familiar
+with CiviCRM development. It covers setting up your developer environment,
+ensuring that you really need to start coding (i.e. you can't achieve what you
+want thought configuration or installing an already existing extension), best
+practice ways to extend CiviCRM (aka how to write an extensions), things you
+should know before you start hacking on core, and best practice for testing.
-It starts with a ***guide*** - a high level introduction to get you familiar with CiviCRM development. It covers setting up your developer environment, ensuring that you really need to start coding (i.e. you can't achieve what you want thought configuration or installing an already existing extension), best practice ways to extend CiviCRM (aka how to write an extensions), things you should know before you start hacking on core, and best practice for testing.
+The guide also includes detailed references for tools and subsystems
+of CiviCRM. These cover topics like the API and hook system and are intended
+for use by people that are familiar with CiviCRM development.
-The guide is followed by detailed ***references*** for tools and subsystems of CiviCRM. These cover topics like the API and hook system and are intended for use by people that are familiar with CiviCRM development.
+Editing & reading offline
+-------------------------
-## Editing & reading offline
+- This documentation is made with mkdocs and
+ [stored in GitHub](https://github.com/civicrm/civicrm-dev-docs)
+- See the "[Writing Documentation](documentation.md)" section in this guide
+ for specific details on editing this documentation (and others using
+ mkdocs). You can also learn how to read these docs off-line!
-* This documentation is made with mkdocs and [stored in GitHub](https://github.com/civicrm/civicrm-dev-docs)
-* See the "[Writing Documentation](documentation.md)" section in this guide for specific details on editing this documentation (and others using mkdocs). You can also learn how to read these docs off-line!
+Migration of content is in progress
+-----------------------------------
-## Caveats
+As of early 2017 we are actively working to migrate content from the [wiki] to
+this guide. Read more about this [migration process][migration], including how
+to help out!
-* These documents are a work in progress.
-* You may find things in the [wiki](http://wiki.civicrm.org/confluence/display/CRMDOC/Develop) that are not documented here.
+[wiki]: http://wiki.civicrm.org/confluence/display/CRMDOC/Develop
+[migration]: https://wiki.civicrm.org/confluence/display/CRMDOC/Content+migration+from+wiki+to+Developer+Guide
-# Other sources of information
+Other sources of information
+------------------------------
-As an open-source project, CiviCRM is managed by an international community of developers and activists. Help from these people can be found in the following ways:
+As an open-source project, CiviCRM is managed by an international community of
+developers and activists. Help from these people can be found in the following
+ways:
-* Our [chat rooms](https://chat.civicrm.org/) and [mailing lists](http://lists.civicrm.org/lists/info/civicrm-dev) are great places to say hello and discuss CiviCRM issues with others.
-* If you need help, your best bet is probably our [stack exchange Q+A site](http://civicrm.stackexchange.com/).
-* If you've identified a problem, you can file issues on our [issue](http://issues.civicrm.org/) on our issue tracker or fix the issue and submit a pull request on [Github](https://github.com/civicrm/civicrm-core/).
-* If you've written an extension, please share it in our [extensions directory](https://civicrm.org).
-* Use the [wiki](http://wiki.civicrm.org/confluence/display/CRM/CiviCRM+Wiki) to share drafts, notes, and specs
-* And don't forget you are always welcome to come to a [real world event](https://civicrm.org/events) like a conference meet-up or sprint.
+- Our [chat rooms](https://chat.civicrm.org/) and
+ [mailing lists](http://lists.civicrm.org/lists/info/civicrm-dev) are great
+ places to say hello and discuss CiviCRM issues with others.
+
+- If you need help, your best bet is probably our
+ [stack exchange Q+A site](http://civicrm.stackexchange.com/).
+
+- If you've identified a problem, you can file issues on our
+ [issue](http://issues.civicrm.org/) on our issue tracker or fix the issue
+ and submit a pull request on
+ [Github](https://github.com/civicrm/civicrm-core/).
+
+- If you've written an extension, please share it in our
+ [extensions directory](https://civicrm.org).
+
+- Use the [wiki](http://wiki.civicrm.org/confluence/display/CRM/CiviCRM+Wiki)
+ to share drafts, notes, and specs.
+
+- And don't forget you are always welcome to come to a
+ [real world event](https://civicrm.org/events) like a conference meet-up
+ or sprint.
diff --git a/docs/markdownrules.md b/docs/markdownrules.md
index 8b9b0c48921531140d1244ca7ac29c3a1a4cc756..0f433c2d7a2f369225f82fbcf980d454909d9865 100644
--- a/docs/markdownrules.md
+++ b/docs/markdownrules.md
@@ -1,143 +1,338 @@
-Overview
-========
+Markdown Syntax
+==============
-In order for your CiviCRM extension to be compliant, you must provide a minimal extension documentation, written in [Markdown](https://guides.github.com/features/mastering-markdown/) language.
+Learning [Markdown](https://en.wikipedia.org/wiki/Markdown)
+language is useful for:
+- Writing CiviCRM [extensions](extend) -- In order for your extension to be
+ compliant, you must provide extension documentation, written in markdown.
+- Writing other *.md* files that display on [GitHub]
+- Contributing to CiviCRM [documentation](documentation)
+- Chatting on [Mattermost](http://chat.civicrm.org)
+- Q&A on [Stack Exchange](http://civicrm.stackexchange.com)
-Examples
-========
+[GitHub]: https://github.com
+Markdown language is mostly consistent across these platforms, but some
+discrepancies do exist and should be noted below.
+
+Markdown has some redundant syntax (e.g. `*italic*` and `_italic_`).
+Within CiviCRM documentation we want consistent code, so we list
+***unapproved variants*** below to make it clear which syntax is preferred by
+CiviCRM, especially in large guides like this one.
+
+
+Basics
+------
+
+- `*italics*`
+- `**bold**`
+- `***bold and italic***`
+- `~~strikethrough~~` *(GitHub/Mattermost/StackExchange)*
+- `<del>strikethrough</del>` *(mkdocs)*
+
+***Unapproved variants:*** Underscores for `_italics_` and `__bold__` work. But
+please but use asterisks for consistency.
+
+
+Hyperlinks
+----------
+
+- A basic hyperlink
+
+ Try [CiviCRM](https://civicrm.org) for your database.
+
+- With long URLs, the following syntax is better.
+
+ See [this issue][CRM-19799] for more details.
+
+ [CRM-19799]: https://issues.civicrm.org/jira/browse/CRM-19799
+
+ - The second line can be placed anywhere in the file.
+ - Optionally, if the link ID ("CRM-19799" in this case) is omitted, you
+ can use the link text ("this issue") to reference the link in the
+ second line.
+
+
+Line breaks and whitespace
+--------------------------
+
+**Single line breaks** in markdown code are eliminated in display:
+
+```md
+This text will all show up
+on the
+same
+line.
+```
+
+This makes it easy to avoid very long lines in markdown code. As a rule of
+thumb, **keep your markdown code free of lines longer than 80 characters**
+where possible.
+
+Also, please **remove trailing whitespace** from the end of markdown code.
+
+**Double line breaks** create separate paragraphs:
+
+```md
+This is
+one paragraph.
+
+This is a second.
+```
+
+
+
+Headings
+--------
+
+
+```md
Heading 1
----------
-````javascript
-This is a heading 1
-===================
-````
+=========
Heading 2
---------
-````javascript
-This is a heading 2
--------------------
-````
+```
-Heading 3
----------
+***Unapproved variants:*** `# Heading 1` and `# Heading 2` also work. But please
+use `=` and `-` for consistency.
+
+For headings beyond 1 and 2, the `#` syntax is okay...
+
+```md
+### Heading 3
+
+#### Heading 4
+```
+
+***Convention:*** Each page should have one and only one *Heading 1*,
+which should be at the top of the page as a page title. Other headings within
+page content should be level 2 or greater.
-````javascript
-### This is a heading 3
-````
-Trivial Headings
-----------------
+Lists
+-----
-Standard Markdown headings are treated as navigational elements and added to
-the navbar. However, some headings indicate trivial distinctions among
-subsections and should not be highlighted in the navigation. Demarcate these
-using raw HTML.
+### Unordered lists
-```html
-<h3>Local Heading</h3>
+```md
+- My first item is here.
+- My second item is here and a
+ bit longer than the first.
+- Then, a third.
```
+***Unapproved variants:***
-Styling Text
-------------
+- Unordered lists also recognize `*` and `+` as item delimiters.
+ But please use `-` for consistency.
+- Markdown is somewhat flexible with the quantity and position of spaces when
+ making lists, but for consistency, please stick to the example above which
+ has: **1 dash, 3 spaces, then content**, and has **long lines beginning
+ with 4 spaces** so they line up nicely.
-Both bold and italic can use either a * or an _ around the text for styling. This allows you to combine both bold and italic if needed.
+### Ordered lists
-````
-*This text will be italic*
-**This text will be bold**
-````
+```md
+1. Item
+2. Item
+3. Item
+```
-Blockquotes
------------
+***Unapproved variants:***
-You can indicate blockquotes with a >.
+- Ordered lists items are automatically re-numbered sequentially upon display
+ which means all items can begin with `1`, but for the sake of consistency
+ with existing docs, please number your lists sequentially in code.
+- Similar to the comment above for unordered lists, please keep all list
+ content beginning 4 characters in, which means a digit character, a period,
+ then two spaces, then content.
-````
-In the words of Abraham Lincoln:
-> Pardon my french
-````
+### Nested lists
-Lists
------
+List items must be indented 4 spaces:
-Unordered lists
----------------
+```md
+1. Item
+ 1. Item
+ 2. Item
+2. Item
+ * Item
+ * Item
+ * Item
+3. Item
+```
-You can make an unordered list by preceding list items with either a * or a -.
-````
-* Item
-* Item
-* Item
+Code
+----
-- Item
-- Item
-- Item
-````
+### Inline code
-Ordered lists
--------------
+Use backticks to create inline monospace text:
-You can make an ordered list by preceding list items with a number.
+```md
+Some `monospace text` amid a paragraph.
+```
-````
-1. Item 1
-2. Item 2
-3. Item 3
-````
+And if you need to put a backtick inside your monospace text, begin and end
+with two backticks:
+
+```md
+Some ``monospace text with `backticks` inside``, and all amid a paragraph.
+```
-Nested lists
-------------
+### Code blocks
-You can create nested lists by indenting list items by two spaces.
+A block of **"fenced code"** with three or more backticks on their own line.
-````
-1. Item 1
- 1. A corollary to the above item.
- 2. Yet another point to consider.
-2. Item 2
- * A corollary that does not need to be ordered.
- * This is indented four spaces, because it's two spaces further than the item above.
- * You might want to consider making a new list.
-3. Item 3
+````md
+```
+CODE
+BLOCK
+```
````
+*Fenced code can use more backticks when necessary to represent code with
+3 backticks (which is what you'd see in the source for this page).*
+***Unapproved variants:*** For fenced code, the tilde `~` character also works
+in place of the backtick character but should be avoided for consistency.
-Inline code block
------------------
-### Inline formats
+A block of **"indented code"** with four spaces at the start of each line:
-Use single backticks (`) to format text in a special monospace format. Everything within the backticks appear as-is, with no other special formatting.
+```md
+ CODE
+ BLOCK
+```
+
+
+### Syntax highlighting for code
+
+- For code blocks, most platforms (e.g. mkdocs, GitHub) will guess guess the
+ language of the code and automatically apply syntax highlighting to the
+ display.
+- To force a particular type of syntax highlighting, use fenced code with a
+ keyword (like `javascript` in this case) as follows:
+
+ ```javascript
+ var cj = CRM.$ = jQuery;
+ ```
+
+- Available language keywords for forced syntax highlighting differ slightly
+ by markdown platform, but here are some common ones:
+ `as`, `atom`, `bas`, `bash`, `boot`, `c`, `c++`, `cake`, `cc`, `cjsx`,
+ `cl2`, `clj`, `cljc`, `cljs`, `cljsc`, `cljs.hl`, `cljx`, `clojure`,
+ `coffee`, `_coffee`, `coffeescript`, `cpp`, `cs`, `csharp`, `cson`, `css`,
+ `d`, `dart`, `delphi`, `dfm`, `di`, `diff`, `django`, `docker`,
+ `dockerfile`, `dpr`, `erl`, `erlang`, `f90`, `f95`, `freepascal`, `fs`,
+ `fsharp`, `gcode`, `gemspec`, `go`, `groovy`, `gyp`, `h`, `h++`,
+ `handlebars`, `haskell`, `haxe`, `hbs`, `hic`, `hpp`, `hs`, `html`,
+ `html.handlebars`, `html.hbs`, `hx`, `iced`, `irb`, `java`, `javascript`,
+ `jinja`, `jl`, `js`, `json`, `jsp`, `jsx`, `julia`, `kotlin`, `kt`, `ktm`,
+ `kts`, `lazarus`, `less`, `lfm`, `lisp`, `lpr`, `lua`, `m`, `mak`,
+ `makefile`, `markdown`, `matlab`, `md`, `mk`, `mkd`, `mkdown`, `ml`, `mm`,
+ `nc`, `objc`, `obj-c`, `objectivec`, `ocaml`, `osascript`, `pas`, `pascal`,
+ `perl`, `php`, `pl`, `plist`, `podspec`, `powershell`, `pp`, `ps`, `ps1`,
+ `puppet`, `py`, `python`, `r`, `rb`, `rs`, `rss`, `ruby`, `rust`, `scala`,
+ `scheme`, `scm`, `scpt`, `scss`, `sh`, `sld`, `smalltalk`, `sql`, `st`,
+ `swift`, `tex`, `thor`, `v`, `vb`, `vbnet`, `vbs`, `vbscript`, `veo`,
+ `xhtml`, `xml`, `xsl`, `yaml`, `zsh`
+- Syntax highlighting cannot be forced for indented code.
+- Syntax highlighting is not available for inline code.
+- [Stack Exchange syntax highlighting][stack exchange syntax highlighting] is
+ done differently.
+
+[stack exchange syntax highlighting]: http://stackoverflow.com/editing-help#syntax-highlighting
+
+### Code blocks within lists
+
+You can use **indented code within lists** by keeping a blank line
+above/below and indenting *4 spaces more than your list content*, like this:
+
+```md
+- First item
+- Look at this code:
+
+ CODE BLOCK WITHIN
+ TOP LEVEL LIST ITEM
+
+- More list items
+- A nested list is here:
+ 1. Alpha
+ 2. Beta, with some code
+
+ CODE BLOCK WITHIN
+ SUB-LIST ITEM
+
+ 3. Gamma
+
+- Fun, right?
+```
+
+**Fenced code within lists** is shown below. It works on GitHub but **not
+mkdocs**:
+
+````md
+- First item
+- Look at this code:
+
+ ```md
+ code
+ block
+ ```
+
+- More list items
+````
-Here's an idea: why don't we take `SuperiorProject` and turn it into `**Reasonable**Project`.
-### Multiple lines
-You can use prepend and append triple backticks (```) to format text as its own distinct block.
+Images
+------
-Check out this neat program I wrote:
+Images function mostly the same as hyperlinks, but preceded by an exclamation
+point and with alt text in place of the link text.
+```md
+
```
-x = 0
-x = 2 + 2
-what is x
+
+or
+
+```md
+![Alt text][id]
+
+[id]: image.png
```
-Links
------
-You can create an inline link by wrapping link text in brackets ( [ ] ), and then wrapping the link in parentheses ( ( ) ).
+Other markdown syntax
+---------------------
+
+- [Tables] (to be avoided when possible)
+- [Emojis] (great for Mattermost)
+- Blockquotes
+
+ > This text is a blockquote, typically used
+ > to represent prose written by a person. It
+ > will be displayed slightly indented.
+
+[Emojis]: http://www.webpagefx.com/tools/emoji-cheat-sheet/
+[Tables]: https://help.github.com/articles/organizing-information-with-tables
+
+External references
+-------------------
+
+- [Mattermost markdown](https://docs.mattermost.com/help/messaging/formatting-text.html)
+- [Stack Exchange markdown](http://stackoverflow.com/editing-help)
+- [GitHub markdown](https://help.github.com/categories/writing-on-github/)
+- [Official markdown reference](https://daringfireball.net/projects/markdown/syntax)
+ (though somewhat difficult to read)
+
-````
-This is a [demo link](https://www.google.com)
-````
\ No newline at end of file
diff --git a/docs/requirements.md b/docs/requirements.md
index 0fb7d13b89ab224edb7c332d2f81b2dd9aa18fe7..58798f9f82f13d363fa3b33cbc907535a85dbede 100644
--- a/docs/requirements.md
+++ b/docs/requirements.md
@@ -1,14 +1,19 @@
-# Languages and Services
+Development requirements
+========================
- * Unix-like environment (Linux, OS X, or a virtual machine)
- * [PHP v5.3+](http://php.net/)
- * [MySQL v5.1+](http://mysql.com/)
- * [NodeJS](https://nodejs.org/)
- * [Git](https://git-scm.com/)
- * Recommended: Apache HTTPD v2.2+
- * Recommended: Ruby/Rake
+Languages and Services
+----------------------
-# Command Line
+- Unix-like environment (Linux, OS X, or a virtual machine)
+- [PHP v5.3+](http://php.net/)
+- [MySQL v5.1+](http://mysql.com/)
+- [NodeJS](https://nodejs.org/)
+- [Git](https://git-scm.com/)
+- Recommended: Apache HTTPD v2.2+
+- Recommended: Ruby/Rake
+
+Command Line
+------------
There are many ways to install MySQL, PHP, and other dependencies -- for
example, `apt-get` and `yum` can download packages automatically; `php.net`
@@ -28,7 +33,8 @@ for MAMP).
In subsequent steps, the download script will attempt to identify
misconfigurations and display an appropriate message.
-# Buildkit
+Buildkit
+--------
The developer docs reference a large number of developer tools, such as
`drush` (the Drupal command line), `civix` (the CiviCRM code-generator), and
@@ -41,10 +47,12 @@ but that takes a lot of work.
[civicrm-buildkit](https://github.com/civicrm/civicrm-buildkit) provides
a script which downloads the full collection.
-### - Option #1: Full Stack Ubuntu (Opinionated)
+### Installing buildkit on Ubuntu
-If you have a new installation of Ubuntu 12.04 or 14.04, then you can download everything -- buildkit and the system
-requirements (`git`, `php`, `apache`, `mysql`, etc) -- with one command. This command will install buildkit to `~/buildkit`:
+If you have a new installation of Ubuntu 12.04 or 14.04, then you can download
+everything -- buildkit and the system requirements (`git`, `php`, `apache`,
+`mysql`, etc) -- with one command. This command will install buildkit to
+`~/buildkit`:
```bash
curl -Ls https://civicrm.org/get-buildkit.sh | bash -s -- --full --dir ~/buildkit
@@ -52,15 +60,19 @@ curl -Ls https://civicrm.org/get-buildkit.sh | bash -s -- --full --dir ~/buildki
Note:
- * When executing the above command, you must ***NOT*** run as `root`. (Doing so will produce incorrect permissions.)
- Instead, you must have `sudo` permissions.
- * The `--full` option is opinionated; it specifically installs `php`, `apache`, and `mysql` (rather than `hvm`, `nginx`, `lighttpd`, or `percona`).
- If you try to mix `--full` with alternative systems, then expect conflicts.
+- When executing the above command, you must ***NOT*** run as `root`.
+ (Doing so will produce incorrect permissions.) Instead, you must have
+ `sudo` permissions.
+- The `--full` option is opinionated; it specifically installs `php`,
+ `apache`, and `mysql` (rather than `hvm`, `nginx`, `lighttpd`, or
+ `percona`). If you try to mix `--full` with alternative systems, then
+ expect conflicts.
-### - Option #2: Other Systems
+### Installing buildkit on other systems
-If you already installed the requirements (`git`, `php`, etc), then you can download buildkit to `~/buildkit` with these commands:
+If you already installed the requirements (`git`, `php`, etc), then you can
+download buildkit to `~/buildkit` with these commands:
```bash
git clone https://github.com/civicrm/civicrm-buildkit.git buildkit
@@ -69,7 +81,7 @@ cd buildkit/bin
export PATH="$PWD:$PATH"
```
-### - Option #3: Upgrade
+### Upgrading buildkit
If you have previously downloaded buildkit and want to update it, run:
diff --git a/docs/testing.md b/docs/testing.md
index b12cc68f9ac3776c991a0ab9c69a29130d117782..1a66454e83db405815dc4912e77062e6fbd9f1f2 100644
--- a/docs/testing.md
+++ b/docs/testing.md
@@ -1,67 +1,118 @@
Testing
=======
-Testing in CiviCRM is done by a combination of human code review and testing as well as automated testing. Testing is done based on pull requests (PRs) in [GitHub](https://github.com/civicrm/civicrm-core/pulls). Pull requests are code submitted in response to issues reported in [JIRA](https://issues.civicrm.org/), the issue tracking system for CiviCRM.
+
+Testing in CiviCRM is done by a combination of human code review and testing
+as well as automated testing. Testing is done based on pull requests (PRs)
+in [GitHub](https://github.com/civicrm/civicrm-core/pulls). Pull requests are
+code submitted in response to issues reported in
+[JIRA](https://issues.civicrm.org/), the issue tracking system for CiviCRM.
Automated tests
---------------
TO DO:
- * http://wiki.civicrm.org/confluence/display/CRMDOC/Testing
+- http://wiki.civicrm.org/confluence/display/CRMDOC/Testing
Manual testing
---------------
+
When testing the process you should use is:
-* Check if the PR is paired with an issue in JIRA
-* Read the JIRA ticket
-* Look at the bug in JIRA and ask yourself if you agree with the analysis of the bug
-* Check if the automated tests have passed
-* Attempt to replicate the bug
-* Comment on the Github PR if you managed to replicate the issue, and how.
-* Check that the bug has been fixed with the patch
+- Check if the PR is paired with an issue in JIRA
+- Read the JIRA ticket
+- Look at the bug in JIRA and ask yourself if you agree with the analysis
+ of the bug
+- Check if the automated tests have passed
+- Attempt to replicate the bug
+- Comment on the Github PR if you managed to replicate the issue, and how.
+- Check that the bug has been fixed with the patch
-In order to reproduce the bug you can reproduce the issue in the appropriate [CiviCRM Sandbox](https://civicrm.org/sandboxes). Enabling debugging can help to get more details.
+In order to reproduce the bug you can reproduce the issue in the appropriate
+[CiviCRM Sandbox](https://civicrm.org/sandboxes). Enabling debugging can help
+to get more details.
-CiviCRM uses a system called Jenkins to do automated testing. To get to Jenkins results for a specific PR click *Show all checks* and then *Details*.
+CiviCRM uses a system called Jenkins to do automated testing. To get to
+Jenkins results for a specific PR click *Show all checks* and then *Details*.
-When Jenkins runs the tests, it also setups a test site that will be available for aproximately one week. To find the link to the site click "Console Output" on the left hand menu. Click "Full Log" at the top of the page and then you can search for *CMS_URL* in the output.
+When Jenkins runs the tests, it also setups a test site that will be available
+for aproximately one week. To find the link to the site click "Console Output"
+on the left hand menu. Click "Full Log" at the top of the page and then you
+can search for *CMS_URL* in the output.
There are multiple times that CMS_URL is in the log output.
-If a PR is updated or re-tested, the initial test site will be deleted (since a new test site will have been created).
-
-If the tests have failed for something that we suspect is a random failure, we can ask Jenkins to run the tests again by commenting in the PR "Jenkins, test this please" (this is the [GitHub PR Builder plugin](https://wiki.jenkins-ci.org/display/JENKINS/GitHub+pull+request+builder+plugin)). For new (unrecognised by Jenkins) contributors, Jenkins will automatically respond "can an admin verify this patch?", and a Github user with admin permissions may approve running the tests by commenting on the PR "ok to test". If the user is trusted, CiviCRM administrators can add the person to the whitelist by commenting "add to whitelist".
-
-Jenkins only builds a Drupal site that is built against the branch that your PR is modifying. If you need to test a patch against another CMS than you will want to test the patch in your own environment.
-
-If you have an existing environment you can use *git* or *hub* to checkout the specific PR.
-
-Hub example where 8473 is the PR ID.
-
- hub checkout https://github.com/civicrm/civicrm-core/pull/8473
-
-Example Git command, where 8473 is the PR ID and 4.6 is the branch.
-
- git fetch origin pull/8473/head:4.6
-
-If you do not have an existing environment you can use Buildkit to create one quickly. [Buildkit](https://github.com/civicrm/civicrm-buildkit) is a powerful command line tool for CiviCRM that allows for rapidly creating CiviCRM environments. Buildkit can create installs for Drupal7, Drupal6, WordPress and Backdrop.
-
-Using Buildkit, you can create a CiviCRM environment with the PR applied. Example Buildkit command:
-
- civibuild create dmaster --url http://localhost:8001 --patch https://github.com/civicrm/civicrm-core/pull/8494 --admin-pass s3cr3t
-
-This will create a test environment with the Drupal, CiviCRM master branch and the patch in PR 8494. More detailed information is in the [Civibuild documentation](https://github.com/civicrm/civicrm-buildkit/blob/master/doc/civibuild.md)
-
-Every month, a release announcement message is sent to participants in the review process. The announcement is sent on the [civicrm-dev mailing-list](http://lists.civicrm.org/lists/info/civicrm-dev) and issue is posted on [github.com/civicrm](http://github.com/civicrm). The GitHub post mentions the account names of everyone who has submitted a PR recently (so that they get a notification).
-
-## Notifications
-
-* When opening a PR, submitter is pointed to the CiviCRM Core [contributing documentation](https://github.com/civicrm/civicrm-core/blob/master/.github/CONTRIBUTING.md)
-* At start of month @mentions is used to ping authors, e.g. [https://github.com/civicrm/release-management/issues/2](https://github.com/civicrm/release-management/issues/2)
-* The notice to authors contains the Release Planning spreadsheet. For [example](https://docs.google.com/spreadsheets/d/10EyNqm3-CbAwUjYzckrwSE7VjpZCfatzh-bES59XqA8/edit?usp=sharing).
-* You can also signup for the release week planning emails. For [example](https://gist.github.com/totten/0d05ca4bbe0e1727ee5895f6e588d068)
+If a PR is updated or re-tested, the initial test site will be deleted (since
+a new test site will have been created).
+
+If the tests have failed for something that we suspect is a random failure, we
+can ask Jenkins to run the tests again by commenting in the PR "Jenkins, test
+this please" (this is the
+[GitHub PR Builder plugin](https://wiki.jenkins-ci.org/display/JENKINS/GitHub+pull+request+builder+plugin)).
+For new (unrecognised by Jenkins) contributors, Jenkins will automatically
+respond "can an admin verify this patch?", and a Github user with admin
+permissions may approve running the tests by commenting on the PR "ok to test".
+If the user is trusted, CiviCRM administrators can add the person to the
+whitelist by commenting "add to whitelist".
+
+Jenkins only builds a Drupal site that is built against the branch that your
+PR is modifying. If you need to test a patch against another CMS than you
+will want to test the patch in your own environment.
+
+If you have an existing environment you can use *git* or *hub* to checkout the
+specific PR.
+
+Hub example where `8473` is the PR ID.
+
+```bash
+hub checkout https://github.com/civicrm/civicrm-core/pull/8473
+```
+
+Example Git command, where `8473` is the PR ID and `4.6` is the branch.
+
+```bash
+git fetch origin pull/8473/head:4.6
+```
+
+If you do not have an existing environment you can use Buildkit to create one
+quickly. [Buildkit](https://github.com/civicrm/civicrm-buildkit) is a powerful
+command line tool for CiviCRM that allows for rapidly creating CiviCRM
+environments. Buildkit can create installs for Drupal7, Drupal6, WordPress
+and Backdrop.
+
+Using Buildkit, you can create a CiviCRM environment with the PR applied.
+Example Buildkit command:
+
+```bash
+civibuild create dmaster \
+ --url http://localhost:8001 \
+ --patch https://github.com/civicrm/civicrm-core/pull/8494 \
+ --admin-pass s3cr3t
+```
+
+This will create a test environment with the Drupal, CiviCRM master branch
+and the patch in PR 8494. More detailed information is in the
+[Civibuild documentation](https://github.com/civicrm/civicrm-buildkit/blob/master/doc/civibuild.md)
+
+Every month, a release announcement message is sent to participants in the
+review process. The announcement is sent on the
+[civicrm-dev mailing-list](http://lists.civicrm.org/lists/info/civicrm-dev)
+and issue is posted on [github.com/civicrm](http://github.com/civicrm).
+The GitHub post mentions the account names of everyone who has submitted a
+PR recently (so that they get a notification).
+
+Notifications
+-------------
+
+- When opening a PR, submitter is pointed to the CiviCRM Core
+ [contributing documentation](https://github.com/civicrm/civicrm-core/blob/master/.github/CONTRIBUTING.md)
+- At start of month @mentions is used to ping authors, e.g.
+ [https://github.com/civicrm/release-management/issues/2](https://github.com/civicrm/release-management/issues/2)
+- The notice to authors contains the Release Planning spreadsheet. For
+ [example](https://docs.google.com/spreadsheets/d/10EyNqm3-CbAwUjYzckrwSE7VjpZCfatzh-bES59XqA8/edit?usp=sharing).
+- You can also signup for the release week planning emails. For
+ [example](https://gist.github.com/totten/0d05ca4bbe0e1727ee5895f6e588d068)
diff --git a/mkdocs.yml b/mkdocs.yml
index 25fe2150df760a602029097efe10f6453fbbfda4..c587efd2fd44e01ca3d6bb7b89e5db485e1f9270 100644
--- a/mkdocs.yml
+++ b/mkdocs.yml
@@ -1,31 +1,30 @@
-site_name: CiviCRM Developer Documentation
+site_name: CiviCRM Developer Guide
repo_url: https://github.com/civicrm/civicrm-dev-docs
-site_description: 'A guide for CiviCRM developers.'
-site_author: 'The CiviCRM community'
+site_description: A guide for CiviCRM developers.
+site_author: The CiviCRM community
theme: readthedocs
pages:
- - Home: index.md
- - Guide:
- - Requirements: requirements.md
- - Build: build.md
- - Customize: customize.md
- - Extend: extend.md
- - Develop: develop.md
- - Git: git.md
- - Testing: testing.md
- - Writing Documentation: documentation.md
- - 'Reference: APIv3':
- - General: api/general.md
- - 'Usage': api/usage.md
- - Actions: api/actions.md
- - Parameters: api/params.md
- - Chaining: api/chaining.md
- - 'Reference: Hooks':
- - General: hook.md
- - Database: hooks-db.md
- - Miscellaneous:
- - 'Extension Lifecycle': extend-stages.md
+- Home: index.md
+- Basics:
+ - Requirements: requirements.md
+ - Build: build.md
+ - Customize: customize.md
+ - Extend: extend.md
+ - Develop: develop.md
+ - Testing: testing.md
+ - Writing Documentation: documentation.md
+- APIv3:
+ - API Intro: api/general.md
+ - API Usage: api/usage.md
+ - API Actions: api/actions.md
+ - API Parameters: api/params.md
+ - API Chaining: api/chaining.md
+- Hooks:
+ - How to Use Hooks: hook.md
+ - All Available Hooks: hooks-db.md
+- Miscellaneous:
+ - Extension Lifecycle: extend-stages.md
- Markdown: markdownrules.md
- hookref-old: hookref-old.md
- - Deprecated:
- - 'Building CiviCRM from source': develop-deprecated.md
+- Deprecated:
+ - Building CiviCRM from source: develop-deprecated.md