Merge pull request #262 from seamuslee001/issue_92

Issue 92 Rename API Paramaters to API Options and also port in Custom…

docs/api/custom-data.md

+# APIv3 and Custom Data
+
+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
+$params['custom_N'] = 'value';
+```
+
+To return custom data for an entity, especially when using the CustomValue API, you typically pass a param like the following:
+
+```php
+$params['return.custom_N'] = 1;
+```
+
+*or (depending on which API entity you are querying)*
+
+```php
+$params['return'] = 'custom_N';
+```
+
+*or*
+
+```php
+$params['return'] = 'custom_N,custom_O,custom_P';
+```
+
+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.
+
+## Custom Value get
+
+If developers want to get all custom data related to a particular entity. The best method is to do a `CustomValue.get` API Call. 
+
+```php
+$result = civicrm_api3('CustomValue', 'get', array('entity_id' => 1));
+```
+
+A sample output would be like the following
+
+```php 
+{
+	"is_error":0,
+	"undefined_fields":["return_child:child_name"],
+	"version":3,
+	"count":1,
+	"id":2,
+	"values":[
+       {
+         "entity_id":"1",
+         "latest":"Bam Bam", 
+         "id":"2",
+         "308":"Pebbles Flintstone",
+         "309":"Bam Bam"
+ } 
+] }
+```
+
+For entities other than the Contact Entity you can use an alternate notation to the `custom_n` to specify the custom fields you wish to return. You can use `custom_group_name:custom_field_name`. Read carefully the documentation and parameters in `CustomValue.php` for more alternatives and details.
+
+!!! note 
+    When retrieving custom data for contact entity, it will only return one value in the case of a multiple custom group set whereas for other entities (e.g. Address, or using the `CustomValue.get` API) you will get all custom data records that relate to the relevant entity
+
+The CustomValue Entity implicitly determines what the `entity_table` variable should be when it is not supplied. If you find that the implicitly is not working out exactly, then specify the `entity_table` key. 

docs/api/params.md → docs/api/options.md

-# API Parameters
+# API Options
 
-There are many parameters accepted by the CiviCRM API. Most parameters
-depend on the entity – for current details in your see the [API Explorer](/api/index.md#api-explorer)
-and the [API examples](/api/index.md#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 interface](https://wiki.civicrm.org/confluence/display/CRMDOC/REST+interface#RESTinterface-optionsparameters).
+There are many API Options accepted by the CiviCRM API. These options allow the developer to add in more parameters to the resulting Query that is run against the database. E.g. Limit, Sort. You can explore these options using the the [API Explorer](/api/index.md#api-explorer) and the [API Examples](/api/examples.md) 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 interface](/api/interfaces.md#rest).
 
 
 ## sequential
@@ -198,46 +193,3 @@ civicrm_api('Contact', 'create', array(
   ),
 ));
 ```
-
-
-## Custom Data
-
-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
-$params['custom_N'] = 'value';
-```
-
-To return custom data for an entity, you typically pass a param like the
-following:
-
-```php
-$params['return.custom_N'] = 1;
-```
-
-*or (depending on which API entity you are querying)*
-```php
-$params['return'] = 'custom_N';
-```
-
-*or*
-```php
-$params['return'] = 'custom_N,custom_O,custom_P';
-```
-
-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.
-
-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).

mkdocs.yml

@@ -96,10 +96,10 @@ pages:
   - APIv3 Intro: api/index.md
   - APIv3 Usage: api/usage.md
   - APIv3 Actions: api/actions.md
-  - APIv3 Parameters: api/params.md
-  # APIv3 Permissions: api/permissions.md
+  - APIv3 Options: api/options.md
   - APIv3 Joins: api/joins.md
   - APIv3 Chaining: api/chaining.md
+  - APIv3 Custom Data: api/custom-data.md
   - APIv3 Examples: api/examples.md
   - APIv3 Interfaces: api/interfaces.md
   - APIv3 Changes: api/changes.md

redirects/internal.txt

@@ -6,3 +6,4 @@ extensions/basics extensions
 api/general api
 hooks/hook_civicrm_trigger_info hooks/hook_civicrm_triggerInfo
 framework/schema-definition framework/database/schema-definition
+api/params api/options

redirects/wiki-crmdoc.txt

@@ -166,3 +166,4 @@ In-Place+Field+Editing framework/ui
 Notifications+and+Confirmations framework/ui
 Section+elements framework/ui
 Database+layer standards/database
+Using+Custom+Data+with+the+API api/custom-data