API de la recherche : Différence entre versions

Version actuelle en date du 11 juillet 2014 à 15:22

Cette API est disponible à partir de Ovidentia 7.1.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ée au travers d'un événement dans l'API et sera appelé "realm" (environnement de recherche).

Interroger l'API

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

exemple :

<source lang="php"> include_once $babInstallPath."utilit/searchapi.php"; $arr = 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 environnement de recherche :

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

Effectuer une recherche :

Pour effectuer une recherche, il faut créer un objet critère. Pour plus d'informations sur les objets critères, consultez le chapitre API de la recherche#Les_critères

ensuite, la méthode search($criteria) permet d'obtenir les résultats, par exemple :

<source lang="php">

$contacts = bab_Search::getRealm('bab_SearchRealmContacts'); $criteria = $contacts->getDefaultCriteria(); $results = $contacts->search($criteria);

</source>

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écessaires, 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 optionnelle, 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 clés du tableau sont des chaîne de caractères qui permettent d'identifier la méthode utilisée au sein de l'environnement de recherche. Les valeurs du tableau sont des chaînes de caractères internationalisées utilisées pour décrire chaque méthode 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és par une recherche peuvent être ordonnés de plusieurs façons, 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 être proposés en option. Les clés du tableau sont des chaîne de caractères qui permettent d'identifier l'emplacement. Les valeurs du tableau sont des chaînes 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 fichiers au travers de l'indexation, dans le contenu des anciennes versions des fichiers, dans les données des fichiers stockés dans la base et dans les méta-données attachées à chaque fichier.

getFields()

Cette méthode doit retourner un tableau contenant la liste des champs des résultats de recherche, les clés du tableau doivent être numériques et les valeurs doivent être 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.

Pour tout les environnements de recherche fournis par le noyau d'Ovidentia, un champ ov_reference est disponible, c'est un champ virtuel qui contient la référence vers l'objet. Par exemple : ovidentia:///articles/article/12

Ci dessous la constitution d'une référence

Ci dessous un exemple de références pour chaque type d'objet qu'OVIDENTIA gère

ovidentia:///files/file/2 (2 étant l'identifiant du fichier)

ovidentia:///articles/article/12 (12 étant l'identifiant de l'article)

ovidentia:///articles/draft/52 (52 étant l'identifiant du brouillon de l'article)

Il est possible d'utiliser la fonction bab_buildReference pour créer une référence.

isAccessValid()

Cette méthode doit retourner TRUE ou FALSE suivant si l'utilisateur connecté a 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 bab_SearchResult respectant les interfaces suivants :

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

Objets de l'API

Exemple avec la recherche dans les notes :

bab_SearchTestable

bab_SearchTestable est une classe abstraite qui permet d'effectuer les tests de recherche et d'obtenir le critère correspondant. la classe bab_SearchRealm et bab_SearchField hérite de bab_SearchTestable.

Les méthodes qui permettent la création de critères sont :

• greaterThan($mixedValue) : permet d'effectuer un test "plus grand que" sur une date ou un nombre
• greaterThanOrEqual($mixedValue) : permet d'effectuer un test "plus grand que ou égal" sur une date ou un nombre
• lessThan($mixedValue) : permet d'effectuer un test "plus petit que" sur une date ou un nombre
• lessThanOrEqual($mixedValue) : permet d'effectuer un test "plus petit ou égal" sur une date ou un nombre
• is($mixedValue) : permet d'effectuer un test sur la valeur exacte
• in($mixedValue) : permet d'effectuer un test de plusieurs valeurs sur la valeur exacte
• like($mixedValue) : permet d'effectuer un test approximatif, la casse n'est pas prise en compte
• startWith($mixedValue) : permet de tester si une chaine commence par la valeur, la casse n'est pas prise en compte
• endWith($mixedValue) : permet de tester si une chaine se termine par la valeur, la casse n'est pas prise en compte

bab_SearchRealm

bab_SearchRealm est une classe abstraite qui est le parent de toutes les classes qui décrivent les environnements de recherche.

Les méthodes communes à tout les environnements de recherche sont :

• setSortMethod($method) Permet de définir le choix la méthode pour ordonner les résultats.
• getSearchLocations() Retourne un tableau qui contient les emplacements de recherche choisis par l'utilisateur.
• addSearchLocation($location) Permet d'ajouter un emplacement de recherche
• createField($name, $description) Permet de créer un objet bab_SearchField
• getBackend($backendName) Permet de créer un objet bab_SearchMySqlBackEnd ou bab_SearchSwishBackEnd

bab_SearchBackEnd

bab_SearchBackEnd est une classe abstraite qui définie la structure des objets backend. Les objets backend sont utilisés pour convertir les différents critères en un requête exploitable par un seul outil de recherche.

Pour le moment 2 backend existent :

bab_SearchMySqlBackEnd

la classe bab_SearchMySqlBackEnd permet de créer des requète SQL pour la recherche dans les tables

bab_SearchSwishBackEnd

la classe bab_SearchSwishBackEnd permet de créer des requète recherche dédiées à l'executable swish-e, pour effectuer des recherches sur le contenu des documents indexés.

Les recherches swish-e ne portent pas sur des champs. Les méthodes supportées par ce backend sont donc très limitées, seul in() et contain() peuvent être utilisés

bab_SearchSqlResult ou bab_searchArrayResult

La liste des résultats est contenu dans un objet bab_SearchSqlResult ou bab_searchArrayResult qui implémente au minimum les interfaces SeekableIterator et Countable

bab_SearchResultCollection

Certains environnements de recherche renvoient des résultats provenant d'autres environnements, dans ce cas c'est un objet bab_SearchResultCollection

bab_SearchRecord

L'objet record contient les valeurs de l'objet retourné, il existe sur cet objet des propriétés correspondantes au nom de chaque champ de l'environnement de recherche associé.

par exemple pour afficher le contenu d'un objet bab_SearchRecord issu d'une recherche dans les notes, il faut utiliser :

<source lang="php">

echo $record->content;

echo $record->date;

</source>

ceci affichera le contenu de la note et la date de publication.

Les environnements de recherche

bab_SearchRealmNotes

Recherche dans les notes personnelles de l'utilisateur

les champs fournis sont :

La méthode getDefaultCriteria retourne un critère qui filtre sur le champ id_user avec l'id de l'utilisateur connecté à Ovidentia.

bab_SearchRealmDirectories

Recherche dans les fiches d'annuaires

la méthode setDirectory($id_directory) permet d'effectuer la recherche sur un seul annuaire

Les champs disponibles pour cette recherche sont :

le champ id_directory ne permet pas d'effectuer un filtre de recherche en utilisant les critères car il contient une valeur uniquement dans le cas d'un annuaire de base de donnés (les fiches ne sont pas reliées à des utilisateurs). A la place, il faut utiliser la méthode setDirectory()

bab_SearchRealmForums

Recherche dans les contributions de forum et les pièces jointes aux contributions

bab_SearchRealmForumPosts

Recherche dans les contributions de forums

les champs fournis sont :

La méthode getDefaultCriteria() créer un critère qui filtre sur les forums accessibles en lecture par l'utilisateur et sur les contribution approuvées.

bab_SearchRealmForumFiles

Recherche dans les pièces jointes des contributions de forums

Cette recherche porte sur le contenu des fichiers uniquement, il n'est pas possible d'utiliser les champs pour créer des critères.

les champs fournis sont :

Les résultats de cette recherche tiennent toujours compte des droits d'accès en visualisation au forums.

bab_SearchRealmFiles

Recherche dans les fichiers du gestionnaire de fichier

les champs fournis sont :

la méthode setFieldLessCriteria permet de définir le critère qui sera utilisé pour la recherche dans le contenu des fichiers et dans les méta-donnés.

Exemple d'utilisation :

<source lang="php">

$files = bab_Search::getRealm('bab_SearchRealmFiles'); $primaryCriteria = $files->search->contain('Ovidentia'); $primaryCriteria = $primaryCriteria->_AND_($files->search->contain('Webservices')); $files->setFieldLessCriteria($primaryCriteria);

$criteria = $files->getDefaultCriteria(); $criteria = $criteria->_AND_($files->created->greaterThan('2009-01-01'));

$results = $files->search($criteria);

</source>

Dans cet exemple, on recherche les fichiers publiés après le 1^er janvier 2009 qui contiennent Ovidentia et Webservices dans le contenu du fichier et dans les méta-données

bab_SearchRealmPublication

Recherche dans le contenu des articles, les commentaires d'articles, les pièces jointes aux articles.

bab_SearchRealmArticles

Recherche dans les articles

les champs fournis sont :

bab_SearchRealmArticlesFiles

Recherche dans les pièces jointes aux articles.

Cette recherche porte sur le contenu des fichiers uniquement, il n'est pas possible d'utiliser les champs pour créer des critères.

les champs fournis sont :

bab_SearchRealmArticlesComments

Recherche dans les commentaires d'articles

les champs fournis sont :

bab_SearchRealmFaqs

Recherche des les questions/réponses des FAQs

Les champs disponibles pour cette recherche sont :

bab_SearchRealmContacts

Recherche dans les contacts personnels de l'utilisateur

Les champs disponibles pour cette recherche sont :

bab_SearchRealmCalendars

Recherche dans les agendas

L'API de recherche sur les agenda n'est valable qu'a partir d'Ovidentia 7.4.0

les champs fournis sont :

La recherche ne remonte pas un résultat par événement mais autant de résultats qu'il y a d'agendas associés à l'événement

bab_SearchRealmTags

Recherche dans les mots clés du thésaurus.

les champs fournis sont :

Cet environnement de recherche utilise l'API des tags pour trouver les résultats

Les critères

un objet bab_SearchCriteria est un ensemble de règles qui portent sur des champs ou des environnements de recherche. Chaque critère peut en contenir un autre. Au moment de d'effectuer la recherche, l'objet critère principal est décomposé et utilisé pour créer soit une requête SQL soit une requête vers le moteur de recherche swish-e.

Les méthodes possibles pour obtenir un objet critères sont :

Critère de droits d'accès

la méthode getDefaultCriteria() sur l'environnement de recherche permet d'obtenir le critère par défaut pour tenir compte des droits

Critères sur les champs

sur chaque champ de l'environnement de recherche, il est possible d'appeler les méthodes de la classe bab_SearchTestable.

Liste des méthodes possibles : API de la recherche#bab_SearchTestable

Critère sur l'environnement de recherche

Il est possible d'effectuer une recherche sur tout les champs de l'environnement, en appelant directement les méthodes sur l'objet bab_SearchRealm. Les critères serons appliqués sur chaque champ ayant la propriété searchable avec pour valeur TRUE

exemple de recherche dans les notes :

<source lang="php">

$notes = bab_Search::getRealm('bab_SearchRealmNotes');

// chercher toutes les notes respectant les droits d'accès : $criteria = $notes->getDefaultCriteria();

// et chercher toutes les notes qui contienent le mot Ovidentia : $criteria = $criteria->_AND_($notes->contain('Ovidentia'));

// parcourir les résultats foreach($notes->search($criteria) as $record) {

    echo $record->content;

}

</source>

Liste des méthodes possibles pour créer un critère à partir d'un objet bab_searchRealm : API de la recherche#bab_SearchTestable

Comment chainer des critères

Sur un objet critère, il existe deux opérateurs qui permettent de d'attacher un nouveau critère, les opérateurs sont des méthodes de l'objet :

$criteria1->_AND_($criteria2) : le critère sera ajouté avec l'opérateur AND lors de la création de la requête SQL ou de la recherche dans les fichiers d'indexation.

$criteria1->_OR_($criteria2) : le critère sera ajouté avec l'opérateur OR lors de la création de la requête SQL ou de la recherche dans les fichiers d'indexation.

Pour inverser l'effet d'un critère,il faut utiliser l'opérateur NOT : $criteria->_NOT_();

Personnaliser l'interface de recherche

Le moteur de recherche d'Ovidentia utilise les environnements de recherche enregistrés pour toutes recherches.

Ne pas afficher dans Ovidentia

Pour désactiver l'utilisation d'un environnement, il faut que la méthode displayInSearchEngine() retourne false

<source lang="php">

   public function displayInSearchEngine() {
       return false;
   }

</source>

Formulaire de recherche

Pour personnaliser l'interface de recherche d'un environnement donné, il faut utiliser la méthode getSearchFormHtml().

Par exemple, pour ajouter les champs de formulaire nécessaire à la recherche dans les événements d'agenda :

<source lang="php">

   public function getSearchFormHtml() {

       $html = parent::getSearchFormHtml();

       $template = new bab_SearchRealmCalendar_SearchTemplate();
       $html .= bab_printTemplate($template, 'search.html', 'calendar_form');

       return $html;
   }

</source>

Avant d'appeler la méthode search(), la méthode getSearchFormCriteria() sera appelé pour récupérer le critère de recherche, cette méthode retourne un critère dépendant uniquement du formulaire par défaut de la recherche, en la surchargeant, il est possible d'ajouter de nouveaux critères à partir du formulaire personnalisé avec la méthode getSearchFormHtml()

exemple :

<source lang="php">

   public function getSearchFormCriteria() {
       // default search fields
       $criteria = bab_SearchDefaultForm::getCriteria($this);

       $h_calendar = (int) bab_rp('h_calendar');
       if ($h_calendar) {
           $criteria = $criteria->_AND_($this->id_cal->is($h_calendar));
       }

       include_once $GLOBALS['babInstallPath'].'utilit/dateTime.php';
       if ($after = BAB_DateTime::fromUserInput(bab_rp('after'))) {
           $criteria = $criteria->_AND_($this->end_date->greaterThanOrEqual($after->getIsoDateTime()));
       }

       if ($before = BAB_DateTime::fromUserInput(bab_rp('before'))) {
           $before->add(1, BAB_DATETIME_DAY);
           $criteria = $criteria->_AND_($this->start_date->lessThan($before->getIsoDateTime()));
       }

       return $criteria;
   }

</source>

Présentation des résultats

Pour personnaliser l'affichage des résultats d'une recherche, il faut que l'environnement utilise une classe personnalisée pour retourner la liste des résultats. La classe doit être héritée de bab_SearchSqlResult ou bab_searchArrayResult.

Lors de l'affichage, c'est la méthode getHtml() qui devra retourner le code HTML nécessaire à l'affichage du nombre d'éléments demandés en paramètre.

exemple pour les résultats des fichiers du gestionnaire de fichier :

<source lang="php">

/**

* Custom result object
* @package search
*/

class bab_SearchFilesResult extends bab_SearchSqlResult {

   /**
    * @return bab_SearchRecord | false
    */
   public function current() {
       $record = parent::current();

       if ($record instanceOf bab_SearchRecord) {
           $record->ov_reference = bab_buildReference('filemanager', 'file', $record->id);
       }

       return $record;
   }

   /**
    * Get a view of search results as HTML string
    * The items to display are extracted from the bab_SearchResult object,
    * the display start at the iterator current position and stop after $count elements
    *
    * @param    int                    $count        number of items to display
    *
    * @return string
    */
   public function getHtml($count) {
       $template = new bab_SearchRealmFiles_ResultTemplate($this, $count);
       return bab_printTemplate($template, 'search.html', 'files_results');
   }

}

</source>