A partir de Ametys 4.2, ce nouveau service doit remplacer tous les services de recherche existants auparavant

  1. Structure
  2. Code HTML
    1. Critères de recherche
    2. Résultats de recherche
      1. Formulaire caché
      2. Aucun résultat
      3. Hits
      4. Pagination: Voir plus de résultats / Scroll infini
      5. Tris
      6. Facettes
    3. Exemple
  3. Chargement AJAX
  4. Helpers

Structure

Le service de Recherche se compose de plusieurs parties :

  • Critères de recherche
    Formulaire de recherche en fonction des paramètres du service avec les valeurs à saisir et le bouton pour soumettre le formulaires
  • Résultats de recherche
    • hits
           Contient les valeurs trouvées qui peuvent être de différents type selon le paramétrage : Contenus, Pages, Documents...
    • pagination
           Le service gère une pagination des résultats en fonction des paramètres.
           2 sortes de paginations sont supportées : la pagination classique par numéros, ou le chargement des pages les unes sous les autres via un bouton "Voir plus de résultats" ou un scroll infini
    • tri
           Le visiteur peut choisir les tris possibles en fonction des paramètres
    • facettes
           Le service gère les facettes

Le service gère de nombreux paramètres mais une vue donnée peut choisir de n'implémenter que certains d'entre eux.
Par exemple, une remontée de contenu, peut faire l'impasse sur la partie critères de recherche mais devra quand même implémenter les éléments techniques minimum décrit ci-dessous

Le paramètre qui gère l'emplacement des résultats de recherche (sous les critères, à la place des critères, sur une autre page) est appliqué en javascript, ce qui nécessite de prévoir dans le HTML certains code HTML.

Code HTML

Le service de recherche vient avec un fichier javascript qui permet de gérer notamment la soumission du formulaire, la pagination ajax... Cela implique les contraintes suivantes sur le code.

Critères de recherche

Les critères doivent être positionnés dans le code suivant :

<form data-ametys-search-role="form"> 

Résultats de recherche

La partie "résultats" (hits, pagination, tri et facette) doit être regroupée au sein d'un tag html (par exemple un <div>) qui sera la partie mise à jour dynamiquement en AJAX lors de la recherche ou des paginations.

<div data-ametys-search-role="search-results"> 

Dans cet élément, doivent se trouver les éléments suivants (qui ne doivent pas être inclus les uns dans les autres) :

Formulaire caché

Afin que la pagination, le tri et les facettes garde les derniers critères de recherche, un formulaire masqué doit être inséré

<form data-ametys-search-role="form-criteria-hidden"> 

Ce formulaire est inséré par un helper.

Aucun résultat

Lorsque la recherche ne renvoie rien, le code pour afficher à l'utilisateur que la recherche n'a rien renvoyé doit être inséré dans une balise portant un attribut spécial (par exemple un <div>)

<div data-ametys-search-role="no-result"> 

Hits

Les réponses trouvées à la recherche doivent être encapsulés dans un seul élément parent portant un attribut spécial (par exemple un <div> ou un <ul>). Cela servira pour le chargement des pages suivants dans le cadre d'un scroll infini par exemple.

<ul data-ametys-search-role="hits"> 

Pagination: Voir plus de résultats / Scroll infini

La section de code qui lance le chargement de plus de résultats (bouton "voir plus de résultat" ou zone de "chargement infini") doit être englobée dans une balise portant un attribut spécial

<div data-ametys-search-role="show-more"> 

Cette zone ne doit pas faire partie de la zone des hits. Cet attribut spécial permettra de masquer ce <div> lorsque les derniers résultats auront été affichés.

Tris

Le tri actuellement utilisé doit être indiqué dans un champ caché et porté un attribut spécial.

<input type="hidden" data-ametys-search-role="current-sort"> 

Ce champ est inséré par un helper.

Facettes

Les différentes valeurs d'une facette doivent être englobés par un élément HTML portant un attribut spécial (par exemple un <div>) ainsi qu'un deuxième attribut portant le nom de la facette.

<div data-ametys-search-role="facet-filter" data-ametys-search-facet-name="XXX"> 

Chaque valeur de facette doit ensuite porté un attribut spécial indiquant si la facette est sélectionnée ou non

<input type="checkbox" data-ametys-search-role="facet-selected|facet-unselected"> 

Ce champ peut être inséré par un helper.

Exemple

Voici un exemple de fichier de rendu de ce service : Télécharger le fichier «sample.xsl» (15.4 KB)

Il peut servir de base à tout nouveau rendu et gère tous les paramètres du service.

Chargement AJAX

Le chargement des résultats se fait en AJAX (sauf la première page de résultats si la recherche est déclenchée au chargement de la page).

Que ce soit en chargement initial ou en chargement AJAX, les résultats de recherches sont traités par la XSL de service de manière transparente pour l'intégrateur : Toute la zone de résultat de la page voulue est générée.
Par contre, en ajax elle n'est pas intégrée dans la zone par le template de la skin : c'est le code javascript qui l'insère à l'endroit des résultats. (Le XPath /search/@ajax permet de savoir dans quel cadre on se trouve si jamais des différences doivent être faites)

Pendant le chargement des résultats la classe "ametys-loading" est ajoutée sur les résultats et permet par exemple de griser la zone et/ou d'afficher un  indicateur de chargement.

En cas de chargement des pages en mode chargement infini (bouton "plus de résultats" ou scroll infini) c'est seulement la zone des hits qui sera rechargée en ajax pour le traitement de la pagination.

Helpers

Les helpers se découpent en deux catégories : ceux qui génèrent un code nécéssaire et ceux qui sont une aide facultative.

Il se trouvent dans le dossier : plugin:web://pages/services/search/helpers.

Fichier

Helper 

Description

js/script.xsl

 

Contient des helpers qui génère des balises <script>

 

search-service-head-js

Obligatoire

 

 

Position : <head>

Paramètres : aucun

 

Insère le javascript du service si le paramétrage le nécessite

 

js-autocompletion

Facultatif

 

 

Position : toutes

Paramètres :
field-id (Obligatoire, String) Identifiant de l'<input>

url (Facultatif, String) Url renvoyant les information de complétion

 

Le critère de recherche dispose d'une auto-complétion après 500ms si 2 caractères au moins ont été saisis.

Par défaut, le helper criteria.xsl active l'auto-complétion sur certains champs.

 

js-sumit-bo

Obligatoire

 

 

Position : toutes

Paramètres : aucun

 

Selon son paramétrage, il arrive que le moteur de recherche ne puisse pas être utilisé dans le back-office. Cette fonction insère le code qui affiche le message d'alerte au moment de la soumission.

js/js.xsl

 

Contient des helpers qui génère du code javascript
 

search-js-submit-button

Facultatif

  

Position : attribut javascript (onclick...)

Paramètres :

callback-function (Faculatif, Function javascript) Fonction appelée à la recherche. La valeur par défaut est le contenu de la variable globale $callback-function

 

Génère le code pour lancer la recherche à partir du formulaire 

Il existe un helper "submit-inputs-button" qui vérifie qu'il est nécessaire puis génère le bouton de soumission

 

search-js-facet

Facultatif

 

 

Position : attribut javascript (onclick...)

Paramètres :

callback-function (Faculatif, Function javascript) Fonction appelée à la recherche. La valeur par défaut est le contenu de la variable globale $callback-function

 

Génère le code pour appliquer une facette

Il existe un helper "facet-filter-element-checkbox" qui génère directement les facettes sous forme de checkbox.

 

search-js-page

Facultatif

 

 

Position : attribut javascript (onclick...)

Paramètres :

callback-function (Faculatif, Function javascript) Fonction appelée à la recherche. La valeur par défaut est le contenu de la variable globale $callback-function

original-context-node (Facultatif, Node) Si cette fonction est appelée via le AmetysXSLTHelper#pagination, le contexte courant doit être transmis par cette fonction. Voir l'exemple de pagination.

page (Obligatoire, String) Numéro de la page à charger

 

Génère le code pour charger une autre page de résultat

 

search-js-next-page

Facultatif

 

 

Position : attribut javascript (onclick...)

Paramètres :

callback-function (Faculatif, Function javascript) Fonction appelée à la recherche. La valeur par défaut est le contenu de la variable globale $callback-function

 

Génère le code pour charger "Plus de résultats" sous les résultats actuels

 

search-js-sort

Facultatif

 

 

Position : attribut javascript (onclick...). Doit être appelé lors d'une boucle sur le XML d'entrée des tris /search/form/sorts/sort sans l'attribut selected

Paramètres :

callback-function (Faculatif, Function javascript) Fonction appelée à la recherche. La valeur par défaut est le contenu de la variable globale $callback-function

 

Génère le code pour changer le tri des résultats actuels

Il existe un helper "sort-element-unselected" qui génère directement un bouton via le helper commun common-utils-input-submit

 

search-json-sort-value

Obligatoire

 

 

Position : attribut value d'un <input type="hidden">. Doit être appelé lors d'une boucle sur le XML d'entrée des tris /search/form/sorts/sort avec l'attribut selected

Paramètres : aucun

 

Génère la valeur du tri actuel (afin qu'il soit conservé lors du changement de page par exemple).

Il existe un helper "sort-hidden-input-for-selected" qui génère directement l'<input> nécessaire

html/all.xsl 

 

L'import de ce helper, permet d'importer directement tous les autres helpers html/*.xsl 

html/criteria.xsl

 

 

 

 

Contient des helpers liés à la création du formulaire de recherche.

Cette XSL contient des matchers, ce qui permet de surcharger le comportement par défaut ponctuellement (par type de champs, pour les libellés, pour un champ donné, etc...)
Voir l'exemple pour comprendre comment les utiliser.

 

criterion-id

Facultatif

 

 

Position : Doit être appelé lors d'une boucle sur le XML d'entrée des critères /search/form/fields/criterion

Paramètres : aucun

 

Renvoie un identifiant unique calculé pour le champ courant 

 

submit-inputs

Facultatif

 

 

Position : Dans le formulaire de recherche

Paramètres : aucun

 

Détermine si un bouton de soumission du formulaire est nécessaire et selon les cas insère un champ caché puis appelle le helper "submit-inputs-button"

 

submit-inputs-button

Facultatif

  

Position : Dans le formulaire de recherche

Paramètres : aucun

 

Génère le code du bouton de soumission puis appelle le helper "search-js-submit-button"

Il est recommandé de ne pas appeler directement ce helper mais d'appeler "submit-inputs" et de surcharger "submit-inputs-button" pour faire un rendu personnalisé.

html/facets.xsl  

 

 

 Contient un helper pour générer des facettes sous forme de cases à cocher

 facet-filter-element-checkbox

 Facultatif

 

 

Position : Dans le div des résultats de recherche. Doit être appelé lors d'une boucle sur le XML d'entrée des facettes

Paramètres :

id (Facultatif, string) Identifiant de la case à cocher

 

Génère une case à cocher pour la facette en ajoutant l'attribut spécial, l'appel au helper "search-js-facet" et l'attribut "data-ametys-search-role".

html/hits.xsl (html/hits/*.xsl)  

 

 

Traitement par matcher des "hit" de type Contenu, Page et Resource.

Un matcher principal "hit", relance un apply-templates avec les modes suivants :

  • class-attribute : ajouter des attributs sur le balise parente
  • image : afficher l'image du résultat
  • title-link : génère le lien avec le titre
  • abstract : génère le résumé du résultat
  • data : génère la date du résultat
  • others : génère des informations complémentaires
 

hit-resource-title-link-href

Facultatif

 

 

Position : Attribut href d'un lien. Dans la boucle de traitement des hits.

Paramètres : aucun

 

Renvoi l'url de la ressouce

 hit-page-title-href

Facultatif

  

Position : Attribut href d'un lien. Dans la boucle de traitement des hits.

Paramètres : aucun

 

Renvoi l'url de la page

html/links.xsl 

 

Contient des helpers pour générer le lien que l'utilisateur peut positionner dans les paramètres

 

link-tag

Facultatif

  

Position : Tag html

Paramètres : aucun

 

Génère le lien <a> configuré par l'utilisateur. Doit être protégé par un test sur /search/link/page

Utilise "link-href", "link-attribute" et "link-title"

 link-href 

Facultatif

  

Position : Attribut href du <a>

Paramètres : aucun

 

Génère l'emplacement href de la page sélectionnée par l'utilisateur. Doit être protégé par un test sur /search/link/page

 link-attribute  

Facultatif

 

 

Position : Attributs du <a>

Paramètres : aucun

 

Génère des attributs supplémentaires sur la balise <a>. Ne fait rien par défaut mais peut être surchargé pour ajouter des classes CSS par exemple.

 

link-title

Facultatif

 

 

Position : contenu du <a>

Paramètres : aucun

 

Génère le texte du lien en prenant la valeur saisie par l'utilisateur et à défaut appelle "link-default-title"

 

link-default-title

Facultatif

 

 

Position : contenu du <a>

Paramètres : aucun

 

Texte du lien par défaut si l'utilisateur n'en fourni pas. Par défaut, affiche le titre de la page selectionnée.

html/results.xsl 

 

Contient un helper pour générer le formulaire caché nécessaire à la modification de la recherche via les résultats : tri, pagination et facettes.

 

form-criteria-hidden

 Obligatoire
  

Position : Dans la partie "resultats" de la page

Paramètres : aucun

 

Génère un <form> caché contenant toutes les valeurs des critères de la recherche actuelle.

html/rss.xsl   

 

Contient des helpers pour générer le lien RSS du moteur de recherche si le paramètre a été sélectionné

 rss-link-tag

Facultatif

 

 

Position : N'importe où.

Paramètres : aucun

 

Génère le lien du flux RSS. Appelle "rss-attribute" et "rss-title" .

 

rss-attribute

Facultatif

 

 

Position : Attribut d'une balise.

Paramètres : aucun

 

Génère des attributs sur le lien de "rss-link-tag". Ne fais rien par défaut : peut être surchargé.

 

rss-title

Facultatif

 

 

Position : N'importe où.

Paramètres : aucun

 

Génère un texte par défaut pour le lien de flux rss de "rss-link-tag". Peut être surchargé.

html/sorts.xsl 

 

Contient des helpers liés à la gestion du tri

 sort-hidden-input-for-selected

Facultatif

 

 

Position : Dans la partie "resultats", lors d'une boucle sur les tris sélectionnés

Paramètres : aucun

 

Génère un <input> caché pour indiqué le tri actuel en cas de modification des résultats : facette ou pagination. Appelé par "sort-element-selected"

 

sort-element-selected

Facultatif

 

 

Position : Dans la partie "resultats", lors d'une boucle sur les tris sélectionnés

Paramètres : aucun

 

Génère un <span class="current"> avec le libellé du tri. Puis appelle "sort-hidden-input-for-selected"

 

sort-element-unselected

Facultatif

 

 

Position : Dans la partie "resultats", lors d'une boucle sur les tris non-sélectionnés

Paramètres : aucun

 

Génère un bouton via "common-utils-input-submit" (avec class="sort") en position le onclick à "search-js-sort"

 

 

Retour en haut