API de la recherche : Différence entre versions

De OviWiki
Aller à : navigation, rechercher
(→‎getFields())
(→‎bab_SearchRealmNotes)
Ligne 155 : Ligne 155 :
  
 
Recherche dans les notes personnelles de l'utilisateur
 
Recherche dans les notes personnelles de l'utilisateur
 +
 +
les champs fournis sont :
 +
 +
{|class="prettytable"
 +
|-
 +
|| 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 <code>getDefaultCriteria</code> retourne un critère qui filtre sur le champ id_user avec l'id de l'utilisateur connecté à Ovidentia.
  
 
=== bab_SearchRealmDirectories ===
 
=== bab_SearchRealmDirectories ===

Version du 9 février 2009 à 16:24

Critical.png 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>


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 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.


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

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

bab_SearchRealmForums

Recherche dans les contributions de forums

bab_SearchRealmForumFiles

Recherche dans les pièces jointes des contributions de forums

bab_SearchRealmFiles

Recherche dans les fichiers du gestionnaire de fichier


bab_SearchRealmArticles

Recherche dans les articles


bab_SearchRealmArticlesFiles

Recherche dans les pièces jointes aux articles


bab_SearchRealmArticlesComments

Recherche dans les commentaires d'articles


bab_SearchRealmFaqs

Recherche des les questions/réponses des FAQs


bab_SearchRealmContacts

Recherche dans les contacts personnels de l'utilisateur


bab_SearchRealmCalendars

Recherche dans les agendas

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 suivantes :

  • greaterThan()
  • greaterThanOrEqual()
  • lessThan()
  • lessThanOrEqual()
  • is()
  • in() : prend en paramètre une variable tableau
  • like() : prend en paramètre une chaine de caractères, les valeur serons comparées sans tenir compte de la casse
  • contain()
  • startWith()
  • endWith()


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

Récupérée de « https://wiki.ovidentia.fr/index.php?title=API_de_la_recherche&oldid=3611 »