As of Ametys 4.2, this new service will replace all existing search services.
Structure
The Research department consists of several parts:
- Search criteria
Search form based on service parameters with values to be entered and button to submit form - Search results
Dynamic" section displays- hits
Contains the results found, which can be of different types depending on the settings: Contents, Pages, Documents... - pagination
The service manages pagination of results according to parameters.
2 types of pagination are supported: classic pagination by number, or loading pages one under the other via a "See more results" button or an infinite scroll. - sorting
The visitor can choose the sorting options based on the following parameters - facets
The service manages facets - hidden form
Returns current search criteria when faceting, sorting or paging - no results
Displays a message when the search returns no results
- hits
The service manages many parameters, but a given view may choose to implement only some of them.
For example, a content feed may omit the search criteria part, but will still need to implement the minimum technical elements described below.
The parameter that manages the location of search results (under the criteria, instead of the criteria, on another page) is applied in javascript, which requires certain code to be included in HTML HTML .
Code HTML
The search service comes with a javascript file that manages form submission, ajax pagination, etc. This implies the following constraints on the code.
Search criteria
The criteria must be positioned in the following code:
<form data-ametys-search-role="form">
Search results
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">
This part of the code will be dynamically replaced in AJAX when searching, paging, sorting...
This element must contain the following elements(which do not have to be included within each other):
Hidden form
In order for pagination, sorting and faceting to retain the last search criteria, a hidden form must be inserted.
<form data-ametys-search-role="form-criteria-hidden">
This form is inserted by the "form-criteria-hidden" helper (see below).
No results
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: More results / Infinite scroll
The section of code that starts the loading of more results ("see more results" button or "infinite loading" zone) must be enclosed in a tag with a special attribute.
<div data-ametys-search-role="show-more">
Please note that, as mentioned above, this zone must not be part of any other zone, particularly the hits zone.
This element is automatically displayed/hidden at javascript.
Tris
The sort currently in use must be indicated in a hidden field and carried by a special attribute.
<input type="hidden" data-ametys-search-role="current-sort">
This field is inserted by a helper.
Example of sorting via a drop-down list:
<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>Veneers
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">
Each facet value must then carry a special attribute indicating whether or not the facet is selected.
<input type="checkbox" data-ametys-search-role="facet-selected|facet-unselected">
This field can be inserted by a "search-js-facet" helper.
Examples
Here's an example of a rendering file for this service: Download file "sample.xsl" (15.4 KB)
It can be used as the basis for any new rendering and manages all service parameters.
AJAX loading
Results are loaded using AJAX (except for the first results page if the search is triggered on page load).
Whether initial loading or AJAX loading, search results are processed by the XSL service in a way that is transparent to the integrator: the entire results area of the desired page is generated.
On the other hand, in ajax it is not integrated into the area by the skin template: it is the javascript code that inserts it in the results area. (The XPath /search/@ajax lets you know what frame you're in, should any differences need to be made).
When loading results, the "ametys-loading" class is added to the results, enabling the zone to be grayed out and/or a loading indicator to be displayed.
If pages are loaded in infinite loading mode ("more results" button or infinite scroll), only the hits zone will be reloaded in ajax for pagination processing.
Helpers
Helpers can be divided into two categories: those that generate necessary code and those that are optional.
They are located in the folder: plugin:web://pages/services/search/helpers.
|
File |
Helper |
Description | |
|---|---|---|---|
|
js/script.xsl | |||
|
|
Contient des helpers qui génère des balises <script> | ||
|
|
search-service-head-js |
Mandatory | |
|
|
|
Position : <head> Parameters : none
Inserts the service's javascript if the setting requires it | |
|
|
js-autocompletion |
Optional | |
|
|
|
Position: all Paramètres : url (Optional, String) Url returning completion information
The search criterion is auto-complete after 500ms if at least 2 characters have been entered. By default, the criteria helper.xsl enables auto-completion on certain fields. | |
|
|
js-sumit-bo |
Mandatory | |
|
|
|
Position: all Parameters : none
Depending on the settings, the search engine may not be available in the back office. This function inserts the code that displays the alert message at the time of submission. | |
|
js/js.xsl | |||
|
|
Contains helpers that generate code javascript | ||
|
|
search-js-submit-button |
Optional | |
|
|
|
Position: javascript attribute (onclick...) Parameters : callback-function (Faculative, Function javascript) Function called on search. The default value is the content of the global variable $callback-function
Generates the code to launch the search from the form There's a "submit-inputs-button" helper which checks that it's needed and then generates the submit button | |
|
|
search-js-facet |
Optional | |
|
|
|
Position: javascript attribute (onclick...) Parameters : callback-function (Faculative, Function javascript) Function called on search. The default value is the content of the global variable $callback-function
Generates code to apply a facet There's a "facet-filter-element-checkbox" helper that generates facets directly as checkboxes. | |
|
|
search-js-page |
Optional | |
|
|
|
Position: javascript attribute (onclick...) Parameters : callback-function (Faculative, Function javascript) Function called on search. The default value is the content of the global variable $callback-function original-context-node (Optional, Node) If this function is called via AmetysXSLTHelper#pagination, the current context must be passed by this function. See pagination example. page (Mandatory, String) Number of the page to load
Generates code to load another result page | |
|
|
search-js-next-page |
Optional | |
|
|
|
Position: javascript attribute (onclick...) Parameters : callback-function (Faculative, Function javascript) Function called on search. The default value is the content of the global variable $callback-function
Generates code to load "More results" below current results | |
|
|
search-js-sort |
Optional | |
|
|
|
Position: javascript attribute (onclick...). Must be called when looping on the XML sort input /search/form/sorts/sort without the selected attribute. Parameters : callback-function (Faculative, Function javascript) Function called on search. The default value is the content of the global variable $callback-function
Generates code to change sorting of current results There is a "sort-element-unselected" helper that directly generates a button via the common helper common-utils-input-submit | |
|
|
search-json-sort-value |
Mandatory | |
|
|
|
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 Parameters: none
Generates the value of the current sort (so that it is retained when the page is changed, for example). Il existe un helper "sort-hidden-input-for-selected" qui génère directement l'<input> nécessaire | |
|
html/all.xsl | |||
|
|
By importing this helper, you can directly import all other html/* helpers.xsl | ||
|
html/criteria.xsl |
|
|
|
|
|
Contains helpers related to the creation of the search form. This XSL contains matchers, which allow you to override the default behavior from time to time (by field type, for labels, for a given field, etc.) | ||
|
|
criterion-id |
Optional | |
|
|
|
Position: Must be called when looping over XML criteria input /search/form/fields/criterion Parameters: none
Returns a unique identifier calculated for the current field | |
|
|
submit-inputs |
Optional | |
|
|
|
Position: In the search form Parameters: none
Determines whether a form submit button is required and, if so, inserts a hidden field and calls the "submit-inputs-button" helper. | |
|
|
submit-inputs-button |
Optional | |
|
|
|
Position: In the search form Parameters: none
Generate the submit button code, then call the "search-js-submit-button" helper. It's recommended not to call this helper directly, but to call "submit-inputs" and override "submit-inputs-button" to render a custom function. | |
|
html/facets.xsl |
|
|
|
|
|
Contains a helper for generating facets in the form of checkboxes | ||
|
|
facet-filter-element-checkbox |
Optional | |
|
|
|
Position: In the search results div. Must be called when looping over XML facet input Parameters: id (Optional, string) Checkbox identifier
Generates a checkbox for the facet by adding the special attribute, the "search-js-facet" helper call and the "data-ametys-search-role" attribute. | |
|
html/hits.xsl (html/hits/*.xsl) |
|
|
|
|
|
Matcher processing of Content, Page and Resource hits. A main "hit" matcher, relaunches an apply-templates with the following modes:
| ||
|
|
hit-resource-title-link-href |
Optional | |
|
|
|
Position: href attribute of a link. In the hits processing loop. Parameters: none
Refer tourl for more information. | |
|
|
hit-page-title-href |
Optional | |
|
|
|
Position: href attribute of a link. In the hits processing loop. Parameters: none
Returnurl to the page | |
|
html/links.xsl | |||
|
|
Contains helpers to generate the link that the user can set in the parameters | ||
|
|
link-tag |
Optional | |
|
|
|
Position: Tag html Parameters: none
Génère le lien <a> configuré par l'utilisateur. Doit être protégé par un test sur /search/link/page Use "link-href", "link-attribute" and "link-title". | |
|
|
link-href |
Optional | |
|
|
|
Position : Attribut href du <a> Parameters: none
Generates the href location of the page selected by the user. Must be protected by a test on /search/link/page | |
|
|
link-attribute |
Optional | |
|
|
|
Position : Attributs du <a> Parameters: none
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 |
Optional | |
|
|
|
Position : contenu du <a> Parameters: none
Generates link text by taking the value entered by the user and, failing that, calls "link-default-title". | |
|
|
link-default-title |
Optional | |
|
|
|
Position : contenu du <a> Parameters: none
Default link text if user doesn't provide one. By default, displays the title of the selected page. | |
|
html/results.xsl | |||
|
|
Contains a helper to generate the hidden form needed to modify the search via results: sorting, pagination and facets. | ||
|
|
form-criteria-hidden |
Mandatory | |
|
|
|
Position: In the "results" section of the page Parameters: none
Génère un <form> caché contenant toutes les valeurs des critères de la recherche actuelle. | |
|
html/rss.xsl | |||
|
|
Contains helpers to generate the RSS search engine link if the parameter has been selected. | ||
|
|
rss-link-tag |
Optional | |
|
|
|
Position: Anywhere. Parameters: none
Generates the feed link RSS. Calls "rss-attribute" and "rss-title" . | |
|
|
rss-attribute |
Optional | |
|
|
|
Position: Tag attribute. Parameters: none
Generates attributes on the "rss-link-tag" link. Does nothing by default: can be overloaded. | |
|
|
rss-title |
Optional | |
|
|
|
Position: Anywhere. Parameters: none
Generates default text for feed link rss from "rss-link-tag". Can be overloaded. | |
|
html/sorts.xsl | |||
|
|
Contains helpers related to sorting management | ||
|
|
sort-hidden-input-for-selected |
Optional | |
|
|
|
Position: In the "results" section, when looping over selected sorts Parameters: none
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 |
Optional | |
|
|
|
Position: In the "results" section, when looping over selected sorts Parameters: none
Génère un <span class="current"> avec le libellé du tri. Puis appelle "sort-hidden-input-for-selected" | |
|
|
sort-element-unselected |
Optional | |
|
|
|
Position: In the "results" section, when looping over non-selected sorts Parameters: none
Generate a button via "common-utils-input-submit" (with class="sort") by setting the onclick to "search-js-sort".
| |
Console
Starting with Ametys 4.5.3, an error message may appear in the console if the HTML service structure is incorrect:
The HTML structure of the search engines has issues. See documentation. You can relaunch the check by calling 'SearchService.checkStructure();'
SearchService's checkStructure function will check the presence and/or nesting of certain elements as described on this page.
Back to top