API de la recherche : Différence entre versions

Version du 9 février 2009 à 14:27

Cette API est disponible à partir de Ovidentia 7.0.0

Utilisation de l'API

L'API de recherche est un ensemble de classes avec des interfaces communes pour interroger les différentes parties d'Ovidentia. Chaque partie d'Ovidentia proposant une interface de recherche sera enregistré au travers d'un événement dans l'API et sera appelé "realm" (environement de recherche).

Interroger l'API

Il faut inclure le fichier utilit/searchapi.php et utiliser la classe </code>bab_Search</code>

exemple :

<source lang="php">

include_once $babInstallPath."utilit/searchapi.php";
bab_Search::getRealms();

</source>

toutes les méthode de la classe bab_Search sont statiques.

Obtenir la liste des environnements de recherche :

bab_Search::getRealms(); retourne un tableau d'objets qui héritent tous de la classe bab_SearchRealm

Obtenir un environement de recherche :

bab_Search::getRealm('bab_SearchRealmContacts'); permet d'obtenir l'objet qui permet d'effectuer une recherche dans les contacts.

Enregistrer un nouvel environnement

Pour créer un environnement de recherche, il faut créer une classe qui hérite de la classe abstraite bab_searchRealm. Pour que l'objet puisse être utilisé par l'API, il faut s'enregistrer sur l'événement bab_eventSearchRealms.

Dans la fonction enregistrée sur l'événement, il faut ajouter les informations nécessaire, voici un exemple avec la recherche dans les notes :

<source lang="php"> if ($event->isRequested('bab_SearchRealmNotes')) { $event->addRealm(new bab_SearchRealmNotes); } </source>

Les classes héritées doivent contenir les méthodes suivantes :

getLink()

Cette méthode est optionelle, elle permet de retourner un lien http vers l'ensemble des ressources recherchées.

getSortMethods()

Cette méthode doit retourner un tableau contenant la liste des méthodes d'ordonnancement des résultats possibles dans cet environnement. Les clefs du tableau sont des chaine de caractères qui permettent d'identifier la méthode utilisée au sein de l'environnement de recherche. Les Valeurs du tableaux sont des chaines de caractères internationalisées utilisées pour décrire chaque méthodes de recherche.

Par exemple, voici la méthode getSortMethods() de la classe bab_SearchRealmFiles

<source lang="php">

public function getSortMethods() {

return array( 'relevance' => bab_translate('Relevance'), 'name' => bab_translate('File name'), 'modified' => bab_translate('Modification date'), 'modifieddesc' => bab_translate('Modification date descending') ); }

</source>

Dans cet exemple, les fichiers retournées par une recherche peuvent êtres ordonnés de plusieurs façon, par pertinence, en ordre alphabétique par le nom ou par dates croissantes ou décroissantes.

getAllSearchLocations()

Cette méthode doit retourner un tableau contenant la liste des emplacements de recherche qui peuvent êtres proposer en option. Les clefs du tableau sont des chaine de caractères qui permettent d'identifier l'emplacement. Les Valeurs du tableaux sont des chaines de caractères internationalisées utilisées pour décrire chaque emplacement de recherche.

Par exemple, voici la méthode getAllSearchLocations() de la classe bab_SearchRealmFiles

<source lang="php">

public function getAllSearchLocations() {

return array( 'files_content' => bab_translate('Content'), 'files_content_versions' => bab_translate('Content of old versions'), 'files' => bab_translate('Folders, names and descriptions'), 'metadata' => bab_translate('Aditionnal metadata') ); }

</source>

Dans cet exemple, la recherche peut être effectuée dans le contenu des fichier au travers le l'indexation, dans le contenu des anciennes versions des fichiers, dans les donnés des fichiers stockés dans la base et dans les méta-donnés attachés a chaque fichiers.

getFields()

Cette méthode doit retourner un tableau contenant la liste des champs des résultats de recherche, les clefs du tableau doivent êtres numériques et les valeurs doivent êtres des objets bab_SearchField. Pour simplifier la création de la liste des champs, il existe une méthode createField() qui prend en paramètre le nom et la description du champ pour créer l'objet.

Un objet bab_SearchField peut avoir plusieurs états :

• virtuel : on ne peut effectuer de recherche sur ce champ mais il existe dans les résultats
• recherche active ou inactive : si la recherche est activée, un critère portant sur tout l'environnement de recherche sera reporté sur ce champ (c'est le comportement par défaut). Dans l'autre cas, le champ ne sera pas recherché.

pour rendre un champ virtuel, il faut utiliser la méthode $field->virtual(true); et pour désactiver la recherche sur un champ, il faut utiliser la méthode $field->searchable(false);.

Deux autres méthodes sont utilisées dans le cas d'une recherche sur des tables MySQL :

• setRealName('sqlname') : si la méthode est utilisée, c'est le nom passé en paramètre qui sera utilisé pour créer la requête SQL.
• setTableAlias('t') : si un alias de table est fourni, il sera utilisé lors de la création de la requête SQL.

isAccessValid()

Cette méthode doit retourner TRUE ou FALSE suivant si l'utilisateur connecté à accès ou non à cet environnement de recherche.

Il appartient à l'utilisateur de l'API de recherche de tester les droits, par défaut l'API permet d'effectuer des recherches sans en tenir compte

getDefaultCriteria()

Cette méthode est optionnelle, elle permet de fournir à l'utilisateur de l'API un objet bab_SearchCriteria tenant compte des droits d'accès.

search(bab_SearchCriteria $criteria)

Cette méthode prend en paramètre un objet bab_SearchCriteria, elle effectue la recherche demandée et retourne un objet respectant les interfaces suivants :

• Iterator : il est possible d'effectuer un foreach sur l'objet
• Seekable : il existe une méthode seek()
• Countable : il existe une méthode count()

Les environnements de recherche