A partir de Ametys 4.2, ce nouveau service doit remplacer tous les services de recherche existants auparavant
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
Partie "dynamique" qui affiche- hits
Contient les résultats 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 - formulaire caché
Renvoie les critères de recherche actuels lors d'une facette, d'un tri ou d'une pagination - aucun résultat
Affiche un message quand la recherche ne renvoie rien
- hits
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>).
<div data-ametys-search-role="search-results">
Cette partie du code sera remplacée dynamiquement en AJAX lors de la recherche, de la pagination, d'un tri...
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 le helper "form-criteria-hidden" (voir plus bas).
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">
Attention, comme indiqué plus haut, cette zone ne doit pas faire partie d'une autre zone et en particulier de la zone des hits.
L'affichage/masquage de cet élément est automatiquement réalisé en javascript.
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.
Exemple de tri via une liste déroulante :
<xsl:template name="sorts-list">
<select class="ametys-results-sort__control" name="sort">
<xsl:attribute name="onchange">eval("function a(){" + this.options[this.selectedIndex].getAttribute('onselect') + "}"); try { a.call(this); } catch(e) { }; return true;</xsl:attribute>
<xsl:for-each select="/search/form/sorts/sort">
<option value="{@name}">
<xsl:attribute name="onselect"><xsl:call-template name="search-js-sort"/></xsl:attribute>
<xsl:call-template name="sort-element-selected-or-not"/>
</option>
</xsl:for-each>
</select>
</xsl:template>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 "search-js-facet".
Exemples
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 : 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...) | ||
|
|
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 :
| ||
|
|
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"
| |
Console
A partir de Ametys 4.5.3, un message d'erreur dans la console peut vous signaler si la structure HTML du service est incorrecte :
The HTML structure of the search engines has issues. See documentation. You can relaunch the check by calling 'SearchService.checkStructure();'
En effet la fonction checkStructure de SearchService va vérifier la présence et/ou l'imbrication de certains éléments conformément à ce qui est décrit dans cette page.
Retour en haut