[commits] [Wiki] changed: CustomizeApis

[Wiki Guest]

guest [178.27.134.51]  Tue, 20 Dec 2016 07:59:14 +0000

Modified page: https://wiki.horde.org/CustomizeApis
New Revision:  8
Change log:  adjusted to H5+ where prototypes are no longer used

@@ -11,11 +11,11 @@
  horde/crm/config/conf.php
  horde/crm/lib/api.php
  </code>

-The {{registry.d/}} directory exists since Horde 3.2. For earlier  
versions, add the code from {{crm.php}} directly to  
{{horde/config/registry.php}}. The directory in newer versions is more  
flexible since you can update the {{registry.php}} configuration file  
more easily when upgrading to newer Horde versions if you didn't  
customize it.
+The {{registry.d/}} directory exists since Horde 3.2. For earlier  
versions, add the code from {{crm.php}} directly to  
{{horde/config/registry.php}}. The directory in newer versions is more  
flexible since you can update the {{registry.php}} configuration file  
more easily when upgrading to newer Horde versions if you didn't  
customize it. The name of the file in registry.d is arbitrary. For  
changes to a file in {{registry.d/}} to take effect, a user must log  
out and in again. Amendments to {{registry.php}} or  
{{registry.local.php}} are effective immediately.

-The {{conf.php}} can be empty. The {{crm.php}} file looks like:
+The {{conf.php}} can be empty. The {{registry.d/crm.php}} file looks like:

  <code type="php">
  <?php
  $this->applications['crm'] = array(
@@ -34,9 +34,9 @@
  </code>

  This tells the Registry that your are only providing the "search"  
and "show" methods of the "contacts" API. The other methods may be  
provided by other modules, by Turba, or not at all. {{'provides'}}  
entries with method names take precedence over generic entries, i.e.  
if for Turba you have {{'provides' => array('contacts')}} in the  
registry configuration and {{'provides' => array('contacts/search',  
'contacts/show')}} for your own module, than these two method will be  
routed to your module, all other "contacts/" calls will be delegated  
to Turba.

-The {{Api.php}} file finally provides the actual method definitions.  
At the top of the file, you list all methods that your are going to  
provide in this file, including the method signatures:
+The {{Api.php}} file finally provides the actual method definitions.  
At least for Horde5+ it is no longer necessary to include method  
signatures. The file implements a class that offers the registered  
services:

  <code type="php">
  <?php
  /**
@@ -45,51 +45,30 @@
   * This file defines CRM's external Horde API interface. Other Horde
   * applications will interact with CRM through this API.
   */

-$_services['search'] = array(
-    'args' => array('names' => '{urn:horde}stringArray',
-                    'sources' => '{urn:horde}stringArray',
-                    'fields' => '{urn:horde}stringArray',
-                    'matchBegin' => 'boolean'),
-    'type' => '{urn:horde}stringArray',
-);
+class CRM_Api extends Horde_Registry_Api
+{
+        public function search($args = array(), $type)
+        {
+                // do something
+        }
+        public function show($args = array())
+        {
+                // do something
+        }

-$_services['show'] = array(
-    'link' =>  
'%application%/contact.php?source=|source|&key=|key|&uid=|uid|',
-);
-</code>
+}

-The method signatures are only important for informational purposes  
and for providing WSDL services through Horde's SOAP interface. The  
"show" method is a special case because it is not really a method, but  
provides a link prototype, i.e. it will be used to provide URL links  
to certain pages inside the application. ##red|This has to be  
explained further.##
-
-Next comes a function definition for each method propagated in the  
API. The naming convention for these functions is  
{{_modulename_methodname}}:
-
-<code type="php">
-/**
- * Returns a contact search result.
- *
- * @param array $names          The search filter values
- * @param array $sources        The sources to serach in
- * @param array $fields         The fields to serach on
- * @param boolean $matchBegin	Match word boundries only
- *
- * @return array  Hash containing the search results.
- */
-function _crm_search($names = array(), $sources = array(), $fields = array(),
-                     $matchBegin = false)
-{
-    // Do some nice things like searching your own application, or routing
-    // to an API of a third-party application.
-    ...
-    return $contacts;
-}
  </code>

  It's a good idea to start with the function definitions already  
provided through existing Horde modules, to get some impression which  
functionality exactly is expected, how returned or incoming data  
structures look like, and how to deal with errors.

  ++ API methods called from the several applications

  This section is going to build a list of all Horde applications and  
the API methods they call. With this list you could easily see which  
methods you might have to implement if want your application to work  
with a certain set of Horde modules. Please remember, you don't **have  
to** implement all methods. If a method doesn't exist, the  
functionality simply isn't available in the Horde module that would  
call it.
+
+Of course, you can provide additional API services or functions that  
may be used outside the Horde framework, i.e. by another Horde  
application.

  +++ Horde

  '*/browse'