Personnalisation de la recherche avancée

De WIKI-BOKEH
Aller à : navigation, rechercher
ATTENTION
En l'état actuel cette fonctionnalité nécessite des connaissances en programmation PHP.

Bokeh propose un formulaire de recherche avancée par défaut.

Recherche avancee.png

Vous pouvez désormais personnaliser ce formulaire et proposer plusieurs formulaires de recherche eux-même personnalisé.

Activation[ ]

La personnalisation de la recherche avancée peut être activée par la variable "CUSTOM_SEARCH_FORM".

Suite à l'activation:

  • un nouveau menu apparait dans l'administration "Système" > "Formulaire de recherche", accessible uniquement aux administrateurs
  • une nouvelle option apparait dans la configuration de l'écran de recherche avancée

Admin menu system customform.png Custom form options.png

Choix des formulaires à afficher[ ]

En tant qu'administrateur, vous pouvez configurer les formulaires à afficher directement à partir de la clef à molette dans l'écran de recherche avancée. Custom form options.png

Le formulaire par défaut de Bokeh est affiché lorsqu'aucun formulaire n'est sélectionné ou si aucun formulaire sélectionné n'est valide.

Si vous êtes connecté en tant qu'administrateur Bokeh affichera toujours les formulaires sélectionnés pour vous permettre de les prévisualiser:

  • avec un message spécifiant que le formulaire n'est pas visible si c'est le cas
  • avec un message d'erreur si le fichier de description du formulaire n'est pas correct (cf. infra pour le format du fichier de description)

Propriétés des formulaires[ ]

Dans l'administration le menu "Système" > "Formulaires de recherche" vous permet d'accéder à la liste des formulaires personnalisés.

Admin searchform index.png

Vous pouvez ajouter et modifier vos formulaires à partir de cette liste.

Admin searchform edit.png

Un formulaire se compose d'un libellé obligatoire qui

  • permettra de le sélectionner dans la configuration de l'écran de recherche avancée
  • servira de libellé de l'onglet affichant le formulaire dans l'écran de recherche avancée

Il se compose aussi d'un fichier de définition obligatoire écrit en PHP et placé dans l'explorateur de fichier (cf. infra pour la description de ce fichier).

Il se compose enfin de la propriété "visible" vous permettant de publier ou dépublier le formulaire sur le site. Un formulaire non publié ne s'affiche que pour les administrateurs.

Format du fichier de description[ ]

ATTENTION: cette section nécessite des connaissances en programmations PHP

Le fichier de description d'un formulaire est au format PHP.

Un fichier de description valide reçoit une variable $form qui représente le formulaire à personnaliser.

Il s'agit d'un objet qui suit l'API de Zend_Form du Zend Framework 1.6 utilisé par Bokeh et lui ajoute des méthodes raccourcis pour faciliter la saisie.

Le script demande au formulaire d'ajouter ou retirer des éléments et des groupes d'éléments.

Exemple:

<?php
$form
  ->addElement('text', 'expression_recherche', ['label' => 'Chercher partout'])
  ->addElement('hidden', 'type_doc', ['value' => 10])
  ->addUniqDisplayGroup('default', ['legend' => 'Critères']);

Explication:

  • ajoute un élément de type text, de nom "expression_recherche" avec un libellé "Chercher partout"
  • ajoute un élément de type hidden, de nom "type_doc" avec une valeur de "10"
  • ajoute tous les éléments définis jusqu'ici dans un groupe d'élément dont la légende sera "Critères"

L'ajout d'un élément de formulaire se compose donc de 3 informations

  • le type d'élément à ajouter, doit exister dans bokeh
  • son nom, doit être compris par le moteur de recherche Bokeh
  • ses options qui varient selon le type

Les types d'éléments basiques[ ]

Tous les éléments basiques ont en commun les options:

  • label : libellé apparaissant à côté de l'élément
  • value : sa valeur lorsqu'on veut préremplir le champ

De plus, toute autre option inconnue de Bokeh sera rendue en tant qu'attribut html de l'élément de formulaire.

Ainsi, vous pouvez passer une option "maxlength" à un élément "text", Bokeh produira le html suivant:

<input type="text" maxlength="..."

text[ ]

Un simple champ de saisie de texte

select, radio[ ]

Un sélecteur, une suite de boutons radio ou de cases à cocher proposant de choisir dans une liste. La liste des choix possibles doit être passée en tant que tableau dans l'option "multiOptions". Pour chaque élément du tableau, la clé deviendra la valeur choisi, le contenu de la cellule deviendra le libellé visible. Par exemple:

<?php
$types = [
  '' => 'Tous',
  '1' => 'Livres',
  '2' => 'Périodiques'
];
$form->addElement('select', 'type_doc', ['label' => 'Type de document', 'multiOptions' => $types]);

Si vous passez l'option "value" avec une valeur faisant partie de la liste, elle sera préselectionnée.

checkbox[ ]

Une case à cocher. Par défaut la valeur non cochée est "0", la valeur cochée est "1". Vous pouvez modifier cela en utilisant les options "checkedValue" et "uncheckedValue".

Types d'éléments avancés[ ]

Il s'agit d'éléments spécifiques au moteur de recherche Bokeh.

searchAxe[ ]

Élément composite proposant à la fois le choix d'un opérateur et la saisie d'un texte. Cet élément n'accepte pas d'option particulière mais il faut noter que l'option "value" sera sans effet.

range[ ]

Élément composite proposant la saisie de 2 valeurs. Il accepte les options spécifiques suivantes:

  • "separator" : texte devant s'afficher entre les 2 champs de saisie
  • "from_suffix" : texte ajouté à la fin du nom de champ pour le premier champ de saisie
  • "to_suffix": texte ajouté à la fin du nom de champ pour le second champ de saisie

Par exemple, si le nom de champ est "annee" et "from_suffix" est "_debut" alors le nom du premier champ de saisie sera "annee_debut". Il faut noter que l'option "value" sera sans effet pour cet élément.

cochesSuggestion[ ]

Élément composite proposant une aide à la saisie sur un grand nombre de cases à cocher pour certains types de données de Bokeh. Il accepte l'option spécifique "rubrique" qui doit préciser quel type de données proposer. Les types possibles sont :

  • type_doc
  • section
  • genre
  • langue
  • emplacement
  • nature_doc
  • bibliotheque
  • annexe
  • profile

Les critères compris par le moteur de recherche[ ]

Tous les critères possibles sont inscrits dans un objet Bokeh Class_CriteresRecherche.

Si vous ajoutez des éléments à votre formulaire dont le "name" n'est pas dans la liste des paramètres compris par Class_CriteresRecherche ils seront simplement ignorés.

De plus, certains critères ont une liste finie de valeurs possibles comprises par le moteur de recherche. Par exemple le critère de tri de la liste de résultat ne peut avoir comme valeur que

  • SORT_RELEVANCE = '*',
  • SORT_TITLE = 'alpha_titre',
  • SORT_AUTHOR = 'alpha_auteur',
  • SORT_PUBLICATION = 'annee desc',
  • SORT_DOCTYPE = 'type_doc,alpha_titre',
  • SORT_NOVELTY = 'date_creation desc',
  • SORT_VIEWS = 'nb_visu desc',

expressionRecherche[ ]

Un texte tel que saisi dans la recherche simple.

rech_*, operateur_*[ ]

Texte dans les titres, auteurs, matieres, dewey, editeur, collection, correspond à un $form->addElement('searchAxe', 'titres') par exemple.

type_recherche[ ]

Précise comment traiter les termes saisis dans les champs de saisie textuels. Ne peut avoir comme valeur que:

  • fulltext : recherche fulltext mysql
  • commence : le champ commence par le texte saisi

Ceci ne s'applique que pour les axes de recherche "rech_*".

type_doc[ ]

Type de document, codification interne de Bokeh dont la liste s'obtient en appelant Class_TypeDoc::getMultiOptions()

nouveaute[ ]

Nombre de mois maximum depuis la date de nouveauté.

annee_debut, annee_fin[ ]

Année d'édition

annexe[ ]

Site du document, liste interne à Bokeh qui s'obtient en appelant Class_CodifAnnexe::getMultiOptions()

section[ ]

Section du document, liste interne à Bokeh qui s'obient en appelant Class_CodifSection::getMultiOptions()

genre[ ]

Genre du document, liste interne à Bokeh, correspond à $form->addElement('cochesSuggestion', 'genre', ['rubrique' => 'genre'])

tri[ ]

Tri de la liste de résultat, ne peut avoir comme valeur que

  • SORT_RELEVANCE = '*',
  • SORT_TITLE = 'alpha_titre',
  • SORT_AUTHOR = 'alpha_auteur',
  • SORT_PUBLICATION = 'annee desc',
  • SORT_DOCTYPE = 'type_doc,alpha_titre',
  • SORT_NOVELTY = 'date_creation desc',
  • SORT_VIEWS = 'nb_visu desc'

Cette liste s'obtient en appelant (new Class_CriteresRecherche)->getListeTris()

page[ ]

Page courante de la liste de résultat

page_size[ ]

Nombre de résultat par page

Reproduire le formulaire par défaut[ ]

Plutôt que de partir d'un formulaire vide vous pouvez décidé de partir du formulaire par défaut et de l'adapter. L'objet $form fourni dispose d'une methode loadDefaults() qui reproduit le comportement du formulaire de recherche avancée par défaut. Le détail de cette construction est disponible dans le code source.

Par exemple:

<?php
$form->loadDefaults();
$form->removeElement('type_doc');
$form->addElement('hidden', 'type_doc', ['value' => 1]);

Explication:

  • charge les éléments par défaut
  • supprime l'élément par défaut qui propose la sélection du type de document
  • ajoute un élément caché qui force le type de document à 1 (Livres)

Limitations[ ]

Dans le fichier de description vous n'avez pas accès à toutes les fonctionnalités de PHP mais seulement à un sous-ensemble nécessaire à la définition des formulaires.

Si votre fichier contient des appels non autorisés le formulaire ne s'affichera pas pour les personnes non connectées et un message d'erreur s'affichera si vous êtes connecté en tant qu'administrateur.

Searchform forbidden call.png

Il en sera de même si votre fichier contient des erreurs de syntaxe.

Searchform syntax error.png

La liste des fonctionnalités autorisées est tenue dans library/Class/SearchForm/Validator.php et peut être amenée à évoluer.

Elle comprend toutes les fonctionnalités de PHP vous permettant de lire des données en y ajoutant des fonctions propres à Bokeh.

Appels possibles sur l'objet formulaire[ ]

  • $form->loadDefaults() ajoute tous les éléments et groupes d'éléments du formulaire par défaut
  • $form->addElement(string type, string name, array options) ajoute un élément au formulaire
  • $form->addDisplayGroup(array names, string id, array options) ajoute un groupe d'élément au formulaire
  • $form->addUniqDisplayGroup(string id, array options) ajoute un groupe d'élément au formulaire qui contiendra tous les éléments ajoutés jusqu'ici
  • $form->removeElement(string name) retire un élément précédemment ajouté au formulaire
  • $form->removeDisplayGroup(string name) retire un groupe d'élément précédemment ajouté au formulaire, les éléments ne sont pas retirés seulement leur regroupement

Appels possibles sur des modèles Storm[ ]

Storm est la couche d'accès à la base de données dans Bokeh, consultez la documentation pour en connaitre les principes.

Par exemple pour l'objet représentant la liste des annexes

  • Class_CodifAnnexe::find(mixed id) retourne l'annexe dont la clé primaire est id ou null si elle n'existe pas en base
  • Class_CodifAnnexe::findAll() retourne la liste complète des annexes sous forme de tableau dans leur ordre d'insertion en base, s'il n'y a pas d'annexe le tableau sera vide
  • Class_CodifAnnexe::findAllBy(array criteres) retourne la liste des annexes correspondant aux critères sous forme de tableau, s'il n'y en a pas le tableau sera vide
  • Class_CodifAnnexe::findFirstBy(array criteres) retourne la première annexe correspondant aux critères ou null s'il n'en existe aucune
  • Class_CodifAnnexe::countBy(array criteres) retourne le nombre d'annexes correspondant aux critères ou 0 s'il n'en existe aucune

Appels possibles sur des collections Storm[ ]

Lorsque que vous obtenez une liste d'objets Storm en resultat d'un appel à findAll ou findAllBy vous pouvez la passer à une collection Storm qui fournira des facilités supplémentaires pour travailler avec cette liste. Vous pouvez à tout moment obtenir un tableau PHP simple correspondant à la collection en appelant $collection->getArrayCopy()

Par exemple : $annexes = new Storm_Model_Collection(Class_CodifAnnexe::findAll());

  • $annexes->collect('id') retourne une collection contenant uniquement les identifiants des annexes
  • $annexes->select('isVisible') retourne une collection contenant uniquement les annexes pour lesquels l'appel à isVisible() retourne true
  • $annexes->reject('isVisible') retourne une collection contenant uniquement les annexes pour lesquels l'appel à isVisible() retourne false
  • $annexes->isEmpty() retourne true si la liste est vide
  • $annexes->first() retourne le premier objet de la liste
  • $annexes->includes(objet) retourne true si objet est dans la liste
  • $annexes->getArrayCopy() retourne un tableau simple PHP contenant les éléments de la liste

Appels spécifiques Bokeh[ ]

  • (new Class_CriteresRecherche)->getListeTris() retourne un tableau d'options possibles pour le tri de la liste de résultats
  • Class_TypeDoc::getMultiOptions() retourne un tableau d'options possibles pour les types de documents
  • Class_CodifSection::getMultiOptions() retourne un tableau d'options possibles pour les sections

Fonctions standard php[ ]

  • count() retourne le nombre d'élément d'un tableau php

Quelques exemples d'éléments de recherche à copier coller[ ]

Rechercher sur les titres[ ]

<?php $form->addElement('searchAxe', 'titres', ['label' => $form->_("Titres")]); ?>

Rechercher sur les auteurs[ ]

<?php $form->addElement('searchAxe', 'auteurs', ['label' => $form->_("Auteurs")]); ?>

Rechercher sur les sujets[ ]

<?php $form->addElement('searchAxe', 'matieres', ['label' => $form->_("Sujets")]); ?>

Rechercher sur les centres d'intérêt[ ]

<?php $form->addElement('searchAxe', 'dewey', ['label' => $form->_("Centres d'intérêt")]); ?>

Rechercher sur les éditeurs[ ]

<?php $form->addElement('searchAxe', 'editeur', ['label' => $form->_("Editeurs")]); ?>

Rechercher sur les collections[ ]

<?php $form->addElement('searchAxe', 'collection', ['label' => $form->_("Collections")]); ?>

Comment afficher correctement mes éléments de recherche[ ]

Pour que le formulaire de recherche soit correctement aligné, vous devez impérativement ajouter cette ligne à la fin de votre fichier.

<?php $form->addUniqDisplayGroup('recherche_avancee'); ?>