Pleade Formulaire de Recherche

Introduction

Dans une application Pleade, on peut proposer aux utilisateurs des formulaires de recherche, qui permettent d'exprimer une requête et de lancer la recherche. Dans un projet d'intégration Pleade, la préparation de ces formulaires de recherche est en général une activité importante.

On peut afficher dans Pleade un formulaire de recherche avec une URL qui utilise le nom du fichier de formulaire. Par exemple, pour afficher le formulaire défini dans le fichier cadastre.xconf, il faut utiliser l'URL {{{1}}}. Donc dans le paramètre name, on indique le nom du fichier du formulaire, mais sans son extension. Tous les fichiers de configuration de formulaires sont dans le répertoire module-eadeac/conf/search-forms/.

Le formulaire nommé ead-default.xconf est un cas particulier, il peut être appelé directement par l'URL search-forms.html, sans paramètre name. Il s'agit du formulaire par défaut de Pleade.

Dans l'interface d'administration des menus, un formulaire est présenté comprenant autant d'onglets que de formulaires configurés dans l'application, plus un permettant d'ajouter un nouveau formulaire. [image:administration-search-form.png]

Structure générale

La structure générale du document XML qui décrit un formulaire est schématisée ainsi :

<form ...>
	<key.../>
	<key.../>
	...
</form>

Cette structure est donc très simple : un élément <form> qui matérialise le formulaire et ensuite une suite d'éléments <key> qui représentent chacun un critère de recherche.

On constate donc une caractéristique importante des formulaires Pleade : il s'agit nécessairement d'un formulaire de recherche « à plat », c'est-à-dire constitué d'une suite de critères, mais sans regroupement, sans sous-critères, etc.

Attributs du formulaire

L'élément racine form dans le fichier de définition du formulaire peut prendre ces différents attributs :

<form
	action=""
	max-chars=""
	documents=""
	auto-expand=""
>
	...
</form>

La signification des différents attributs est :

Attribut	Description
action	Obligatoire. L'URL qui doit être appelée par le formulaire lorsque l'utilisateur valide sa recherche. Pour l'instant, les seules valeurs supportées par Pleade doivent être de la forme *-results.html. La valeur par défaut est results.html. Les types d'affichage des résultats possibles sont : results.html : défaut. affichage selon le cadre declassement ; table-results.html : affichage sous forme de tableau ; list-results.html : affichage en liste sans hiérarchie ; mosaic-results.html : affichage sous forme d'apercu ; custom-results.html : affichage personnalisable.
max-chars	Optionnel. Dans les listes de valeurs, le nombre maximal de caractères à afficher en largeur, afin d'éviter des débordements (listes trop longues en largeur). Cette indication peut également être fournie dans la définition d'un critère de recherche.
documents	Obligatoire. La base de documents à rechercher, dans une installation standard de Pleade, les valeurs possibles sont : ead, eac ou tout autre bases définies. Plusieurs valeurs peuvent être indiquées séparées par une espace.
auto-expand	Optionnel. Les résultats de recherche étant affichés dans l'ordre du cadre de classement, on peut indiquer avec cet attribut comment les entrées du cadre de classement seront affichées, c'est-à-dire si elles seront automatiquement « ouvertes » ou non. Si cet attribut n'est pas renseigné, c'est le paramètre d'installation correspondant qui fait foi. Cet attribut peut prendre différentes valeurs : _all : tous les niveaux seront automatique ouverts ; n (un entier) : les entrées jusqu'au niveau indiqué seront automatiquement ouvertes ; docs:n (la mention « docs » suivie d'un nombre) :une entrée sera ouverte uniquement si elle contient au plus n documents résultats. units:n (la mention « units » suivie d'un nombre) : une entrée sera ouverte uniquement si elle contient au plus n unités de recherche résultats.

Les critères de recherche

Principales caractéristiques communes

Chaque critère de recherche est exprimé par un élément <key>. Cet élément peut prendre de nombreux attributs mais également des sous-éléments. Ces attributs ou sous-éléments sont parfois communs à l'ensemble des critères, soit spécifiques à un type de critère.

Nous allons dans un premier explorer les principales caractéristiques communes à tous les types de critères. La structure générale de l'élément <key> est la suivante :

<key
	id=""
	type=""
	field=""
	fieldh=""
	connector=""
	format=""
	max-chars=""
	terms-browse=""
	help=""
>
	...
</key>

Les attributs et leur définition sont :

Attribut	Description
id	Optionnel. L'identifiant unique du critère qui va permettre de pouvoir distinguer le critère d'un autre dans la mise en forme par feuille de style CSS.
type	Obligatoire. Le type de critère ; ce qui va déterminer comment il sera affiché (zone de saisie, liste, etc.) et aussi quels sont les autres attributs qui pourront lui être associés. Les valeurs possibles sont : cdc, text, suggest, list, hidden, date et boolean.
field	Obligatoire pour la plupart des types de critères. Le champ dans lequel s'effectue la recherche avec ce critère. Si l'attribut fieldh est spécifié, l'attribut field indique le champ utilisé lorsqu'un seul critère de recherche est renseigné par l'utilisateur. Pour connaître la liste des champs définis par défaut dans Pleade, se reporter au manuel Gestion de contenu.
fieldh	Optionnel, mais fortement conseillé pour la plupart des types de critères. Le champ dupliqué dans lequel s'effectue la recherche si au moins deux critères de recherche sont renseignés par l'utilisateur.
connector	Optionnel. Des informations sur l'opérateur booléen entre ce critère et le précédent dans le formulaire. La valeur de cet attribut est un nombre : 1 : l'opérateur est forcément le ET, il ne sera pas affiché. C'est également le comportement si l'attribut connector n'est pas renseigné. 2 : l'opérateur est forcément le OU, il ne sera pas affiché. 3 : l'opérateur peut être le ET ou le OU, et le choix sera laissé à l'utilisateur, par l'affichage d'une liste déroulante à gauche du critère. 4 : l'opérateur est forcément le SAUF, il ne sera pas affiché. Fichier:Search-form-connector.png
format	Optionnel. Le format accepté pour le critère, particulièrement utile pour les dates ou les zones de texte, dans certains cas ; il déclenche la validation par javascript du critère à la soumission du formulaire. Si l'utilisateur saisit une valeur non permise par le format, le formulaire ne sera pas validé et un message sera affiché. Le contenu de cet attribut doit être une expression régulière valide en Javascript.
max-chars	Optionnel. Dans les listes de valeurs, le nombre maximal de caractères à afficher en largeur, afin d'éviter des débordements (listes trop longues en largeur). Cette indication peut également être fournie dans la définition d'un critère de recherche. Si cet attribut n'est pas renseigné, c'est la valeur de l'attribut défini au niveau de l'élément form qui s'applique sauf dans le cas des dates, où la valeur est automatiquement fixée à quatre (recherche par année seulement).
help	Optionnel. Si sa valeur est true, un bouton d'aide est affiché à droite du critère. Fichier:Search-form-help-bubble.png Les critères peuvent prendre d'autres attributs, qui sont expliqués soit dans les explications sur les différents types de critères dans la section suivante soit dans les fonctions avancées un peu plus loin (#Fonctions avancées).

Types de critères

Un formulaire de test reprenant les types de critères courants et des commentaires explicatifs est livré par défaut. Il peut servir de modèle pour créer ou modifier un formulaire. Ce formulaire de test est visible à l'URL {{{1}}}.

Critère caché (hidden)

Les critères cachés permettent d'ajouter systématiquement un critère de recherche de manière transparente pour l'utilisateur. On doit utiliser la valeur hidden pour l'attribut type. Il supporte un attribut spécifique :

Attribut	Description
value	Obligatoire pour utiliser ce critère. Il s'agit de la valeur que doit avoir le champ indiqué dans l'attribut field. <key type="hidden" connector="2" field="unitid" value="2002W" />

Cadre de classement (cdc)

Ce critère se comporte de manière particulière : il permet d'afficher le cadre de classement à droite du formulaire, et l'utilisateur pourra choisir une ou plusieurs entrées du cadre de classement à l'aide de cases à cocher.

Fichier:Search-form-key-type-cdc.png

Il ne supporte aucun attribut spécifique.

<key type="cdc"/>

Pour un critère de ce type, les attributs field et fieldh ne sont pas utiles, car Pleade utilise toujours les mêmes champs de recherche. De même, l'attribut help n'a aucun impact.

Zone de texte (text)

Ce critère se présente sous la forme d'une zone de texte où l'utilisateur peut saisir librement des mots, expressions, etc. On l'utilise normalement pour des recherches sur des champs de type « mot ».

Fichier:Search-form-key-type-text.png

Pour un tel critère, on peut ajouter des attributs afin de permettre à l'utilisateur de choisir un autre champ de recherche, un champ « alternatif ». Cela est particulièrement utile pour proposer à l'utilisateur d'étendre la recherche aux documents associés, comme le fait le formulaire par défaut de la distribution standard de Pleade.

Quand est un champ alternatif est défini pour un critère, une boîte à cocher est affichée sous le critère offrant à l'utilisateur un choix.

<key
	type="text"
	field="fulltext" fieldh="hfulltext"
	help="true"
	alternate-field="extfulltext" alternate-fieldh="hextfulltext" alternate-field-checked="false"
/>

Pour réaliser cela, il faut ajouter les attributs suivants à l'élément <key> :

Attribut	Description
alternate-field	Obligatoire pour utiliser cette fonctionnalité. Le nom du champ à rechercher si l'utilisateur choisit cette option. Si l'attribut alternate-fieldh est également renseigné, ce champ sera utilisé uniquement s'il y a un seul critère de recherche.
alternate-fieldh	Optionnel mais fortement recommandé. Le nom du champ dupliqué alternatif à rechercher si l'utilisateur renseigne au moins deux critères de recherche.
alternate-field-checked	Optionnel, défaut: false. Si la valeur est true, l'option pour le champ alternatif sera déjà sélectionnée au moment d'afficher le formulaire.

Notice :

À noter que les champs alternatifs sont supportés uniquement pour les critères de type texte dans Pleade.

On peut également omettre l'attribut field et plutôt proposer à l'utilisateur de choisir un champ de recherche parmi une liste.

Fichier:Search-form-key-type-text-fields-list.png

Pour ce faire, il faut donc ne pas renseigner l'attribut field mais plutôt des sous-éléments field tel que dans cet exemple :

<key type="text" ...>
	<field name="scopecontent"/>
	<field name="unittitle" default="true"/>
	<field name="fulltext"/>
</key>

Dans cet exemple, trois champs seront proposés à l'utilisateur, avec une liste déroulante située à gauche de la zone de texte. La seconde valeur sera pré-sélectionnée, grâce à la présence de l'attribut default avec la valeur true.

Notice :

À noter que si vous utilisez cette possibilité de laisser à l'utilisateur le choix du champ, l'attribut fieldh n'est pas utilisé et il n'est actuellement pas possible de faire l'équivalent.

Listes (list)

Les listes sont destinées à présenter à l'utilisateur une liste de choix. Il peut alors sélectionner une ou plusieurs valeurs et effectuer une recherche sur ces valeurs. Les listes peuvent être présentées de différentes façons, et c'est la valeur de l'attribut variant qui va le déterminer :

Attribut	Description
combo	Une liste déroulante. Dans la liste, l'utilisateur ne peut sélectionner qu'une valeur, mais Pleade offre la possibilité d'ajouter d'autres valeurs. Fichier:Search-form-key-type-list-variant-combo.png
fixed	Une liste à hauteur fixe, c'est-à-dire avec un nombre prédéfini de valeurs affichées. On peut directement sélectionner plusieurs valeurs. Fichier:Search-form-key-type-list-variant-fixed.png
checkbox	Des cases à cocher, donc chaque item de la liste est accompagné d'une case à cocher. On peut sélectionner plusieurs valeurs. Fichier:Search-form-key-type-list-variant-checkbox.png
radio	Des boutons radio, donc chaque item de la liste est accompagné d'un bouton radio. On ne peut sélectionner qu'une seule valeur. Fichier:Search-form-key-type-list-variant-radio.png

En général, les valeurs de la liste seront automatiquement renseignées par Pleade à partir des valeurs que l'on trouve dans le champ indiqué par l'attribut field.

Remarques : On peut également contrôler l'opérateur intra-champ, voir la section #Choix de l'opérateur intra-champ.

Suggestions (suggest)

Les suggestions sont un cas particulier de liste : toutes les valeurs ne sont pas présentées directement à l'utilisateur, celui-ci va plutôt saisir quelques lettres et la liste sera filtrée automatiquement avec des entrées qui contiennent ces lettres, sans tenir compte des accents et des majuscules/minuscules.

Fichier:Search-form-key-type-suggest.png

Pour avoir un tel critère, il s'agit d'utiliser l'attribut type avec une valeur suggest. Par défaut, l'utilisateur peut sélectionner plusieurs valeurs, mais si l'on souhaite qu'il ne sélectionne qu'une seule valeur on peut ajouter un attribut multiple et lui assigner la valeur false :

<key type="suggest" field="fgeogname" help="true" multiple="false"/>

Remarques : On peut également contrôler l'opérateur intra-champ, voir la section #Choix de l'opérateur intra-champ.

Booléens (boolean)

Un critère booléen est un critère qui ne peut prendre que deux valeurs, vrai ou faux. Il se présente sous la forme d'une boîte à cocher. On utilise généralement ce critère pour filtrer la recherche sur un attribut particulier : par exemple, les documents illustrés, limiter la recherche aux articles, etc.

Fichier:Search-form-key-type-boolean.png

Pour un tel critère, on peut ajouter les attributs particuliers suivants :

Attribut	Description
value-on	Obligatoire pour utiliser ce critère. Il s'agit de la valeur que doit avoir le champ indiqué dans l'attribut field.
default	Si la valeur de cet attribut est on, la case sera cochée par défaut.

<key type="boolean" field="fgeogname" value-on="Afrique" default="on" connector="3" />

Dates (date)

La recherche par dates est traitée de manière particulière dans Pleade et fait l'objet d'un type de critère bien particulier. Il n'est pas nécessaire de préciser le champ de recherche car Pleade va toujours utiliser les mêmes champs associés aux dates extrêmes (bdate et edate). De plus, il n'est pas nécessaire d'utiliser le mécanisme des champs dupliqués et de l'attribut fieldh car les dates sont déjà héritées par défaut dans Pleade.

Fichier:Search-form-key-type-date.png

Donc pour effectuer une recherche par dates, on doit utiliser une syntaxe telle que celle-ci :

<key
	type="date"
	id="annee"
	variant="exact interval"
	max-chars="4"
	format="(\d)+"
	help="true"
/>

Les attributs type, format, max-chars et help ont déjà été évoqués, les autres attributs sont :

Attribut	Description
id	Obligatoire. L'identifiant du critère, utilisé pour le lier avec les clés i18n pour la génération des textes.
variant	Obligatoire. Des précisions sur les zones de texte à saisir. Si cet attribut contient exact, une recherche d'une date exacte sera proposée. Si cet attribut contient interval, une recherche par intervalle sera proposée. On peut bien sûr obtenir les deux en indiquant les deux mots, séparés par une espace comme dans l'exemple ci-dessus.

Fonctions avancées

Troncature implicite

Une troncature permet de faire une recherche sur une partie d'un mot. Par exemple, une troncature à droite sur le mot « bois » s'écrit « bois* ». La recherche s'effectue alors sur tous les mots commençant par « bois ». L'astérisque étant un méta-caractère, la chaine subi une expansion par la droite.

Une troncature implicite peut être ajoutée aux éléments de formulaire de type text. Pour ajouter la troncature automatiquement à la validation du formulaire, il suffit d'ajouter l'attribut truncate.

Attribut	Description
truncate	Permet de déterminer où sera ajoutée la troncature implicite. Cet attribut peut prendre les valeurs left, right ou both, respectivement expansion par la gauche, la droite ou les deux côté.

<key type="text" field="fulltext" truncate="left"/>
<key type="text" field="fulltext" truncate="right"/>
<key type="text" field="fulltext" truncate="both"/>

Choix de l'opérateur intra-champ

Par défaut, l'opérateur intra-champ pour tous les éléments de formulaire qui ne sont pas de type list ou suggest, est le ET logique. Pour les éléments de type list et suggest, l'opérateur intra-champ par défaut est le OU logique.

Il est possible de changer ces valeurs par défaut au moyen de l'attribut op dans les éléments key.

Attribut	Description
op	Cet attribut peut prendre les valeurs AND ou OR. Il permet de définir l'opérateur intra-champs.
op-display	Permet de gérer l'affichage de ces opérateurs dans l'interface. Il peut prendre les valeurs true ou false. Dans le cas des éléments de formulaire de type list avec les attributs variant=fixed et selection=multiple, ainsi que pour les éléments de type suggest multiples, les opérateurs s'afficheront lorsqu'il y a plus de deux sélections. Fichier:Search-form-advanced-feature-operator.png

Exemple :

<key type="suggest" field="fgeogname" style="background:#00CCFF" help="true" op-display="true"/>
<key type="suggest" field="fgeogname" style="background:coral" op-display="true" op="AND"/>
<key type="list" variant="combo" rows="5"
	selection="multiple" op-display="true"
	display-field="fatitle" field="root-id"
>
	<no-choice i18n-key="form-no-choice-choix"/>
</key>

Accès au index

Pour chaque critère, il est possible d'ajouter un bouton permettant de parcourir dans un panneau, la liste des termes indexés, associés au champ de la suggestion. Pour cela, il suffit d'ajouter :

Attribut	Description
terms-browse	Optionnel. Permet d'activer l'aide à la recherche de type « navigation d'index » ; c'est-à-dire une icône placée à droite du critère qui déclenche l'affichage d'un panneau listant tous les termes indexés dans un champ de recherche. Cet attribut peut avoir plusieurs valeurs : true ou 1 : cette aide est activée et l'index consulté est celui indiqué comme valeur de l'attribut field ; vide, false ou 0 : cette aide n'est pas activée. Même chose si cet attribut est absent. contient le nom d'un champ autre que celui indiqué comme valeur de l'attribut field : cette aide est activée et l'index consulté est celui indiqué comme valeur d'attribut.
terms-browse-hpp	Optionnel. Cet attribut permet de préciser le nombre d'entrées par page proposées dans la fenêtre de consultation de l'index.

Fichier:Search-form-advanced-feature-nav-index.png

Accès à un thesaurus

Notice :

Cette partie ne concerne que les applications Pleade disposant du module Thesaurus.

Pour chaque critère dont le champ de recherche est lié à un vocabulaire contrôlé, il est possible d'ajouter un bouton permettant de consulter ce vocabulaire s'il est géré par ThesX.

Fichier:Search-form-advanced-feature-thesaurus.png

Pour cela, il suffit d'ajouter :

Attribut	Description
thesx-browse	Optionnel. Permet d'activer l'aide à la recherche de type « consultation de thesaurus » dans un panneau ; c'est-à-dire une icône placée à droite du critère qui déclenche l'affichage d'un panneau permettant de naviguer dans le thesaurus. Cet attribut peut avoir plusieurs valeurs : true ou 1 : cette aide est activée et le thesaurus consulté est celui dont l'identifiant correspond à celui indiqué comme valeur de l'attribut thesx-id ; vide, false ou 0 : cette aide n'est pas activée. Même chose si cet attribut est absent.
thesx-id	Optionnel mais obligatoire si l'attribut thesx-browse active l'aide. Il s'agit de l'identifiant du thesaurus géré par ThesX que l'on veut consulter.
thesx-relations	Optionnel. Cet attribut permet de préciser selon quel type de relations on veut étendre la recherche. Par défaut la recherche est étendue au terme sélectionné et à tous ses spécifiques (relation TS).

Filtre

Il est possible à l'aide d'un critère ou plusieurs critères cachés de limiter la recherche à l'aide d'un formulaire de recherche à une rubrique (voir section suivante 5) Rubriques), à une liste d'instruments de recherche, à une valeur particulière pour un champ. Dans ce cas, si jamais le formulaire de recherche propose des listes ou des aides à la recherche comme un accès aux index, il faut que ces listes soient elles-aussi filtrées par les mêmes critères.

Important :

(est-ce toujours vrai en 2012 ?) Pour le moment, les filtres ne fonctionnent pas avec les critères de type suggestions.

Notice :

L'usage des filtres peut remplacer les rubriques.

Pour filtrer un critère de recherche, on doit utiliser une syntaxe telle que :

<key type="..." ...>
	<filters>
		<filter field="" value=""/>
	</filters>
</key>

L'élément <filters> permet de définir un ensemble de filtre. Il contient des éléments <filter> : chaque filtre est exprimé par un élément <filter>. Cet élément peut prendre deux attributs :

Attribut	Description
field	Obligatoire. Le champ qui permet de filtrer le critère. Remarques : Pour connaître la liste des champs définis par défaut dans Pleade, se reporter à la [[Doc/Gestion de contenu|documentation Gestion de contenu]].
value	Obligatoire. La valeur que doit avoir le champ pour le filtre.

Voilà l'exemple d'un filtre sur un type de documents :

<filters>
	<filter field="fgenreform" value="dessins"/>
</filters>

Listes dépendantes

Une liste peut dépendre d'une autre c'est-à-dire que son contenu peut changer en fonction de la valeur sélectionnée dans l'autre liste. Par exemple, dans un formulaire pour des documents d'état civil, on pourrait vouloir que la liste des types de registres se mette à jour en fonction de la commune sélectionnée.

Fichier:Search-form-advanced-feature-dependant-list.png

Pour obtenir ce fonctionnement, il faut utiliser l'attribut :

Attribut	Description
updateSelect	Placé au niveau du critère de type liste source (celle dont la sélection d'une entrée va mettre à jour la liste cible ou liste dépendante), sa valeur doit être le nom du champ (attribut field) de la liste cible (celle dont le contenu va changer).Dans notre exemple de formulaire d'état civil, sa valeur serait le nom du champ correspondant aux types de registres.

De plus, au chargement du formulaire, deux comportements sont possibles :

• le critère cible est rempli normalement, dans ce cas en général une indication invite l'utilisateur à choisir une entrée
• le critère cible est vide et ne contient qu'une indication invitant l'utilisateur à choisir une entrée dans la liste source.

<key type="list" field="insee" updateSelect="type" variant="combo" [...]>
	{champ source}
</key>
<key type="list" field="type" variant="combo" [...]>
	{champ cible}
	<!--
		Solution 1 : au chargement de la page, le critère est "rempli" normalement,
		son premier item invite l'utilisateur à sélectionner une valeur.
	-->
	<no-choice i18n-key="form-no-choice-choix"/>
	<!--
		Solution 2 : au chargement de la page, le critère est vide et ne contient
		qu'une unique valeur : un message invitant l'utilisateur à
		sélectionner une valeur dans le champ source.
	-->
	<items>
		<item value="" i18n-key="form-no-choice-since-insee-choix" />
	</items>
</key>

Activation conditionnelle

L'activation d'un champ peu être rendu conditionnelle à la saisi de valeur dans un autre, c'est-à-dire que la saisi dans le champ « A » activera les champs A-a, A-b et A-c. Par exemple, on peut rendre l'activation des champs date conditionnel à la saisi d'un nom de commune.

Ce méchanisme s'applique sur tout type de champs. Les champs à activer sont identifiés par la valeur de leur attribut field, hfield ou id (les dates non pas de (h)field).

<form ...>
	<key type="suggest" field="fsubject" help="true" terms-browse="true">
		<activates id="fsubject">
			<activateField>fulltext</activateField>
			<activateField>fgeogname</activateField>
			<activateDateField>fgeogname</activateDateField>
			<activateDate>annee</activateDate>
		</activates>
	</key>
	<key type="text" field="fulltext" ... />
	<key type="suggest" field="fgeogname" ... />
	<key type="date"  id="annee" ... />
</form>

Styles

Dans chaque élément <key> il est possible de définir un attribut style dont la valeur doit être valide par rapport au contenu du même attribut dans la norme XHTML, soit des règles CSS.

Fichier:Search-form-advanced-feature-css-style.png

Attribut	Description
style	Permet de surcharger le style CSS de l'élément de formulaire.

<key type="text" style="width:10em;" field="fulltext"/>