6.0.0-git
2019-11-19

Diff for CustomizeApis between 7 and 8

+ Replacing APIs with your own solutions

Horde applications are loosely coupled with each other through the application APIs. Each application provides a set of external API methods that can be called from other Horde applications through the Horde Registry, or even externally through the Horde RPC interfaces. See the ((Doc/Dev/Registry|Registry wiki page)) for details.

If you want to provide some functionality through your own or some external code, all you need to do it to register you own code in the Horde Registry and provide the required API methods. For example, if you have your own address book or CRM solution, you could replace Horde's address book module Turba with that program.

Here is a real world example. Say we have a CRM system that is providing contacts. First create a small application stub, a Horde mini-application. We call it "crm" and need the following 3 files to become a working Horde module:

<code>
horde/config/registry.d/crm.php
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 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}}{{registry.d/crm.php}} file looks like:

<code type="php">
<?php
$this->applications['crm'] = array(
    'fileroot' => dirname(__FILE__) . '/../../crm',
    'webroot' => $this->applications['horde']['webroot'] . '/crm',
    'name' => 'CRM',
    'status' => 'notoolbar',
    'provides' => array('contacts'),
);
</code>

This entry registers an application called "crm" at the Horde Registry, hides it from the toolbar (we only want to use it internally, i.e. it doesn't have a UI), and propagates the "contacts" API. This means that all methods calls to the contacts API will be delegated to the crm module. Turba provides a **lot** of methods through the contacts API, just take a look at {{turba/lib/api.php}} to get an impression. You don't have to implement all these methods in your crm module though, because a) not all methods are used in all Horde modules (see below), and b) you can also tell the registry to only provide certain methods of the contacts API. To achieve that, change the {{'provides'}} entry to a less generic value:

<code type="php">
'provides' => array('contacts/search', 'contacts/show'),
</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 methodsleast for Horde5+ it is no longer necessary to include method signatures. The file implements a class that your are going to provide in this file, includingoffers the method signatures:registered services:

<code type="php">
<?php
/**
 * CRM external API interface.
 *
 * 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',
);

$_services['show']class CRM_Api extends Horde_Registry_Api
{
        public function search($args = 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 aarray(), $type)
        {
                // do something
        }
        public function definition for each method propagated in the API. The naming convention for these functions is {{_modulename_methodname}}:show($args = array())
        {
                // do something
        }

<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'
'*/changeLanguage'
'*/delete'
'*/getActionTimestamp'
'*/import'
'*/list'
'*/listAlarms'
'*/listBy'
'*/listTagInfo'
'*/removeUserData'
'*/replace'
'*/shareHelp'
'clients/clientFields'
'clients/fields'
'clients/getClientSource'
'contacts/import'
'contacts/sources'
'forwards/summary'
'horde/admin_list'
'images/listGalleries'
'images/listImages'
'images/searchTags'
'mail/compose'
'news/searchTags'
'sms/compose'
'telephony/dial'
'tickets/addTicket'
'vacation/summary'

+++ Chora

+++ DIMP

+++ Forwards

+++ IMP

'calendar/delete'
'calendar/eventFromGUID'
'calendar/getFreeBusy'
'calendar/import'
'calendar/import_vfreebusy'
'calendar/show'
'calendar/updateAttendee'
'contacts/add'
'contacts/fields'
'contacts/getField'
'contacts/import'
'contacts/search'
'contacts/show'
'contacts/sources'
'files/returnFromSelectlist'
'files/selectlistResults'
'images/saveImage'
'images/selectGalleries'
'mail/canApplyFilters'
'mail/showBlacklist'
'mail/showFilters'
'mail/showWhitelist'
'notes/import'
'notes/listNotepads'
'notes/show'
'tasks/import'
'tasks/listTasklists'
'tasks/show'

+++ Ingo

+++ Jeta

+++ Kronolith

+++ MIMP

+++ Mnemo

+++ Nag

+++ Passwd

+++ Turba

+++ Vacation