API de la recherche

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 bab_Search

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.

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

les références aux objets sont constituées de :

protocole	ovidentia://
emplacement	local/ ou /
module	nom de l'addon d'ovidentia ou de la fonctionnalité du noyau
type d'objet	chaine de caractère
identifiant de l'objet (pour un type donné)	nombre entier ou chaine de caractère

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 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 environements 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 contiens 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

Les environnements de recherche

bab_SearchRealmNotes

Recherche dans les notes personnelles de l'utilisateur

les champs fournis sont :

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 :

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

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 forums

les champs fournis sont :

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 :

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 :

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éertoire 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	Pertinance 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és

la méthode setPrimaryCriteria 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_SearchRealmFile'); $primaryCriteria = $files->search->contain('Ovidentia'); $primaryCriteria = $primaryCriteria->_AND_($files->search->contain('Webservices')); $files->setPrimaryCriteria($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és

bab_SearchRealmArticles

Recherche dans les articles

les champs fournis sont :

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 :

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 :

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 :

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 :

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

les champs fournis sont :

ov_reference	référence vers l'événement
id	identifiant numérique
title	titre
description	description en HTML
location	Lieu
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
category	nom de la catégorie de l'événement
id_cat	identifiant numérique de la catégorie
id_cal	identifiant numérique de l'agenda
owner	identifiant numérique du propriétaire de l'agenda, la valeur peut être un ID d'utilisateur ou un ID d'agenda de ressource ou un ID d'agenda collectif
type	3 constantes possibles : BAB_CAL_USER_TYPE : agenda personel BAB_CAL_PUB_TYPE : agenda collectif BAB_CAL_RES_TYPE : agenda de ressource
date_modification	la date de dernière modification de l'événement
bprivate	statut privé/public de l'événement, la valeur peut être Y ou N

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

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'appeller les méthodes de la classe 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>

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_();