API de la recherche

Un article de OviWiki.


Image:warning.png Cette API est disponible à partir de Ovidentia 7.1.0

Sommaire

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 :

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


Image:information.png 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 :

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

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 :

if ($event->isRequested('bab_SearchRealmNotes')) {
	$event->addRealm(new bab_SearchRealmNotes);
}

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

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')
		);
	}


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

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')
		);
	}

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

Libellé Description
protocole ovidentia://
emplacement chaine vide pour le site local ou l'url d'un site externe.
module nom de l'addon d'ovidentia ou de la fonctionnalité du noyau
type d'objet chaine de caractère
identifiant identifiant de l'objet (pour un type donné). Nombre entier ou chaine de caractère


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.


Image:warning.png 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 :


Image:Search_objets.svg


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.


Image:warning.png 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 :

echo $record->content;
 
echo $record->date;

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 :

Nom du champ Description
ov_reference référence vers l'objet Ovidentia
id identifiant numérique
id_user id de l'utilisateur propriétaire de la note
content contenu de la note en HTML
date date de publication


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 :

Nom du champ Description
ov_reference référence vers la fiche d'annuaire
id id de la fiche d'annuaire
id_user Si la fiche d'annuaire est lié à un utilisateur d'Ovidentia, ce champ contiens l'ID de l'utilisateur lié.
id_directory si la fiche d'annuaire est liée à un annuaire de base de donnés, le champ id_directory contient l'identifiant numérique de l'annuaire
... Les champs fournis sont les champs non désactivés des annuaires recherchés


Image:warning.png 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 :

Nom du champ Description
ov_reference référence vers l'objet Ovidentia
id identifiant numérique
id_thread identifiant numérique du sujet
id_forum identifiant numérique du forum
forum_name nom du forum
subject sujet de la contribution
message contenu de la contribution
author nom et prénom de l'auteur de la contribution
date date de publication de la contribution
confirmed statut d'approbation de la contribution la valeur peut être Y ou N


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 :

Nom du champ Description
ov_reference référence vers le fichier
file chemin complet vers le fichier
filename nom du fichier
title Titre du document trouvé dans les méta-donnés pas l'indexation swish-e
relevance Pertinence du résultat de recherche, nombre entier de 0 à 1000, 1000 étant le résultat à présenter en premier
id identifiant numérique du fichier
id_post identifiant numérique de la contribution
id_thread identifiant numérique du sujet
id_forum identifiant numérique du forum


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 :

Nom du champ Description
ov_reference référence vers le fichier
id identifiant numérique
name nom du fichier
id_owner identifiant numérique du propriétaire du fichier, ce champ peut contenir l'ID du répertoire collectif dans lequel se trouve le fichier ou l'ID de l'utilisateur si le fichier se trouve dans un répertoire personnel.
description description du fichier
created date de création
modified date de la dernière modification
path chemin relatif vers le fichier
collective statut répertoire collectif, la valeur peut être Y ou N, si la valeur est N le fichier est dans un répertoire personnel.
author identifiant numérique de l'auteur
confirmed statut d'approbation la valeur peut être Y ou N
state statut de suppression du fichier, la valeur peut être une chaine vide ou D, si la valeur est D le fichier se trouve dans la corbeille.
relevance Pertinence de la recherche
search Ce champ n'est pas remonté dans les résultat, il permet d'effectuer des recherches sur le contenu des fichiers et dans les méta-données


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 :

$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);

Dans cet exemple, on recherche les fichiers publiés après le 1er 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 :

Nom du champ Description
ov_reference référence vers l'article
id identifiant numérique de l'article
id_topic identifiant numérique du thème
id_author identifiant numérique de l'auteur
title Titre de l'article
head Introduction de l'article
body Corps de l'article
date_publication date de publication
archive statut de l'archivage, la valeur peut être Y ou N

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 :

Nom du champ Description
ov_reference référence vers l'objet Ovidentia
file Chemin complet vers le fichier
filename Nom du fichier
description Description de la pièce jointe
title Titre du document trouvé dans les méta-donnés par le moteur d'indexation
relevance Pertinance du résultat de recherche
id identifiant numérique du fichier
id_article identifiant numérique de l'article
id_topic identifiant numérique du thème d'articles

bab_SearchRealmArticlesComments

Recherche dans les commentaires d'articles

les champs fournis sont :

Nom du champ Description
ov_reference référence vers le commentaire
id identifiant numérique du commentaire
id_author id de l'utilisateur qui a créer le commentaire ou 0 si le commentaire à été créé par un utilisateur non connecté
name nom de l'auteur
id_topic identifiant numérique du thème
id_article identifiant numérique de l'article
subject sujet du commentaire
message contenu du commentaire en HTML
confirmed statut d'approbation du commentaire, la valeur peut être Y ou N
date_publication Date et heure de publication du commentaire au format ISO

bab_SearchRealmFaqs

Recherche des les questions/réponses des FAQs

Les champs disponibles pour cette recherche sont :

Nom du champ Description
ov_reference référence vers la question
id identifiant numérique de la question/réponse
idcat Identifiant numérique de la catégorie
question Texte de la question
response Texte de la réponse en HTML
date_modification Date de publication

bab_SearchRealmContacts

Recherche dans les contacts personnels de l'utilisateur

Les champs disponibles pour cette recherche sont :

Nom du champ Description
ov_reference référence vers la fiche de contact
id identifiant numérique de fiche
owner ID Utilisateur du propriétaire de la fiche
firstname Prénom
lastname Nom
email Email
compagny Nom de la société
hometel Numéro de téléphone personnel
mobiletel Numéro de téléphone mobile
businesstel Numéro de téléphone professionnel
businessfax Numéro de fax professionnel
jobtitle Poste
businessaddress Adresse professionnelle
homeaddress Adresse personnelle

bab_SearchRealmCalendars

Recherche dans les agendas


Image:warning.png L'API de recherche sur les agenda n'est valable qu'a partir d'Ovidentia 7.4.0

les champs fournis sont :

Nom du champ Description
ov_reference référence vers l'événement
summary titre
description description en HTML
location Lieu
dtstart date et heure de début au format iCalendar
dtend date et heure de fin au format iCalendar
start_date date et heure de début au format ISO : 0000-00-00 00:00:00
end_date date et heure de fin au format ISO : 0000-00-00 00:00:00
categories nom de la catégorie de l'événement
calendar identifiant de l'agenda utilisé dans l'url
class statut privé/public de l'événement, la valeur peut être PUBLIC, PRIVATE ou CONFIDENTIAL


Image:warning.png 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 :

Nom du champ Description
ov_reference référence vers l'événement
title titre de l'objet
description description de l'objet
url Url vers l'objet
type Type de l'objet, par exemple (Article, Fichier ...)

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 :

$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;
}


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

public function displayInSearchEngine() {
        return false;
    }


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 :

public function getSearchFormHtml() {
 
        $html = parent::getSearchFormHtml();
 
        $template = new bab_SearchRealmCalendar_SearchTemplate();
        $html .= bab_printTemplate($template, 'search.html', 'calendar_form');
 
        return $html;
    }


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 :

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;
    }

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 :

/**
 * 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 <code>bab_SearchResult</code> 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');
    }
 
}