From 163a643ea906869d8d45b93979228a10e4945a7f Mon Sep 17 00:00:00 2001
From: Seamus Lee <seamuslee001@gmail.com>
Date: Thu, 10 Aug 2017 13:54:23 +1000
Subject: [PATCH] Issue 92 Rename API Paramaters to API Options and also port
in Custom Data Documentation to help with Issue 92
---
docs/api/custom-data.md | 63 ++++++++++++++++++++++++++++++
docs/api/{params.md => options.md} | 52 +-----------------------
mkdocs.yml | 3 +-
redirects/wiki-crmdoc.txt | 1 +
4 files changed, 68 insertions(+), 51 deletions(-)
create mode 100644 docs/api/custom-data.md
rename docs/api/{params.md => options.md} (66%)
diff --git a/docs/api/custom-data.md b/docs/api/custom-data.md
new file mode 100644
index 00000000..3857232d
--- /dev/null
+++ b/docs/api/custom-data.md
@@ -0,0 +1,63 @@
+# 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 perticular 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 entites 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 deteremines what the `entity_table` variable should be when it is not supplied. If developers are finding that the implicity is not working out exactly then developers should spcifiy the `entity_table` key.
diff --git a/docs/api/params.md b/docs/api/options.md
similarity index 66%
rename from docs/api/params.md
rename to docs/api/options.md
index 4d5519b9..4a25faff 100644
--- a/docs/api/params.md
+++ b/docs/api/options.md
@@ -1,11 +1,6 @@
-# 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 paramaters to the resulting Query that is run against the databasae. E.g. Limit, Sort. You can explore these options using the 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).
## 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).
diff --git a/mkdocs.yml b/mkdocs.yml
index 31b455c2..b444c601 100644
--- a/mkdocs.yml
+++ b/mkdocs.yml
@@ -96,10 +96,11 @@ pages:
- APIv3 Intro: api/index.md
- APIv3 Usage: api/usage.md
- APIv3 Actions: api/actions.md
- - APIv3 Parameters: api/params.md
+ - APIv3 Options: api/options.md
# APIv3 Permissions: api/permissions.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
diff --git a/redirects/wiki-crmdoc.txt b/redirects/wiki-crmdoc.txt
index 9334152a..a3cc7b25 100644
--- a/redirects/wiki-crmdoc.txt
+++ b/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
--
GitLab