Objet contenant une zone de texte modifiable et fournissant une aide à la saisie en proposant une liste de résultats en correspondance avec ce qui est saisi par l'utilisateur en temps réel.
L'objet se compose de deux composants graphiques :
- un champ de saisie,
une liste de valeurs résultat qui s'affiche dynamiquement en-dessous du champ de saisie, à la manière d'une liste déroulante. Les valeurs résultat sont affichées verticalement, l'une sous l'autre.
La saisie en temps réel signifie que la liste de résultats est "affinée" au fur et à mesure que l'utilisateur saisit du texte.
La correspondance entre chaîne saisie et ensemble de valeurs résultat est établie en fonction d'un critère de sélection.
Il existe par défaut trois critères prédéfinis :
- "commence par" : la chaîne saisie correspond au début de toutes les valeurs résultat de la liste,
- "finit par" : la chaîne saisie correspond à la fin de toutes les valeurs résultat de la liste,
- "contient" : la chaîne saisie est une sous-chaîne de toutes les valeurs résultat de la liste.
L'ensemble des valeurs résultat est défini par une liste (ensemble ordonné de valeurs) : Au sens Adélia, l'objet est associé à une LISTE.
L'objet propose deux modes d'association :
- le mode Liste déroulante : La liste associée est visuellement une liste mono-colonne. Cette liste n'est pas maquettable directement dans Dreamweaver (à la manière de l'objet LISTE DEROULANTE). Au niveau L4G, l'objet Autosuggestion fournit les propriétés VALEUR, VALEUR_COURANTE et LISTE : Il est manipulable comme un objet LISTE DEROULANTE.
- le mode Table liste : L'objet est associé à un objet TABLE LISTE. Le rendu des résultats est lié au rendu de cet objet (table avec en-tête, rendu des cellules en fonction de la nature des objets Adélia constituant les colonnes de la liste, etc.). Visuellement, la liste de résultats affichée peut être multi-colonne. Au niveau L4G, l'objet Autosuggestion ne fournit que la propriété VALEUR. La propriété LISTE n'existe pas dans ce mode, car l'objet s'appuie sur la liste de l'objet TABLE LISTE associé. Pour connaître les valeurs associées à la propriété VALEUR, l'utilisateur doit choisir une colonne "valeur" parmi les colonnes constituant l'objet TABLE LISTE.
Le premier mode est destiné à un maquettage rapide d'informations peu complexes. A contrario, le second permet de maquetter des informations à afficher plus complexes (à la manière d'un guide).
Dans ces deux modes, le texte saisi dans le champ de saisie correspond à la valeur de l'objet Autosuggestion. Le fait de sélectionner un élément dans la liste associée ramène sa valeur dans le champ de saisie et, de ce fait, modifie la valeur de l'objet.
Cliquer ci-dessous pour plus de détails sur :
La corrélation entre les propriétés VALEUR et VALEUR_LIBELLE
L'utilisation de l'objet Autosuggestion via les raccourcis clavier
Gestion de libellé
A la manière de la fonctionnalité "libellé explicite" de l'objet LISTE DEROULANTE, il est possible de gérer des couples libellé / valeur dans la liste associée.
Dans ce cas, la liste de résultats est calculée en appliquant le critère de sélection aux libellés des éléments de la liste.
De plus, ce qui est saisi par l'utilisateur dans le champ de saisie doit être un libellé (et non plus une valeur). Si ce qui est saisi correspond à un libellé présent dans la liste associée, alors la valeur de l'objet Autosuggestion est issue du couple libellé / valeur correspondant.
En mode Liste déroulante, l'activation de la gestion des libellés fait que seule l'information "libellé" est affichée dans la liste (l'information "valeur" est cachée à l'utilisateur).
En mode Table liste, l'activation de la gestion des libellés doit se faire par le choix d'une colonne "libellé" parmi les colonnes constituant l'objet TABLE LISTE (la visibilité de la colonne "valeur" est laissée à l'appréciation de l'utilisateur).
Si cette gestion est activée, alors dans ces deux modes l'objet propose la propriété VALEUR_LIBELLE qui permet de récupérer le texte saisi par l'utilisateur.
De plus, dans le mode Liste déroulante, l'objet propose la propriété LIBELLE_COURANT qui permet d'associer un libellé spécifique à un élément de la liste.
Typage de l'objet
L'objet Autosuggestion est associé à un type Adélia.
Dans le cas où l'objet gère un libellé, alors il gère deux types Adélia :
- un type pour le libellé : l'utilisateur ne pourra saisir dans le champ de saisie qu'une valeur correspondant à ce type Adélia (via le contrôle de saisie),
- un type pour la valeur retournée : le type de cette valeur peut être différent du premier.
Ci-après deux tableaux récapitulatifs des types Adélia supportés en fonction du mode de fonctionnement de l'objet Autosuggestion :
|
||||
|
VALEUR |
VALEUR_COURANTE |
LIBELLE_COURANT |
VALEUR_LIBELLE |
Avec libellé |
ALPHA NUM_BIN_2 NUM_BIN_4 NUM_BIN_8 NUM_E NUM_P TIME DATE TIMESTAMP |
ALPHA NUM_BIN_2 NUM_BIN_4 NUM_BIN_8 NUM_E NUM_P TIME DATE TIMESTAMP |
ALPHA |
ALPHA |
Sans libellé |
ALPHA |
ALPHA |
N/A |
N/A |
|
||
|
VALEUR |
VALEUR_LIBELLE |
Avec libellé |
ALPHA NUM_BIN_2 NUM_BIN_4 NUM_BIN_8 NUM_E NUM_P TIME DATE TIMESTAMP |
ALPHA |
Sans libellé |
ALPHA |
N/A |
Valeurs dans les cas limites
Lorsque l'objet Autosuggestion gère un libellé, quelle valeur cet objet doit-il affecter à sa propriété VALEUR lorsque :
- la liste de résultats est vide ?
- aucun élément n'est sélectionné dans la liste de résultats ?
- le champ de saisie est vide ?
- l'utilisateur a saisi une valeur dans le champ de saisie avant l'apparition de la liste de résultats ?
Dans ces différents cas, l'utilisateur peut spécifier une valeur à utiliser en fonction du type Adélia de la propriété VALEUR de l'objet Autosuggestion :
Type Adélia |
Valeur |
ALPHA |
*LOVAL ou *HIVAL ou *BLANK ou une chaîne de texte à définir. |
NUM_BIN_2 (ou 4 ou 8) |
*LOVAL ou *HIVAL ou un numérique au format ISO à définir. |
NUM_E (ou NUM_P) |
*LOVAL ou *HIVAL ou un numérique au format ISO à définir. |
DATE (ou TIME ou TIMESTAMP) |
*LOVAL ou *HIVAL ou un numérique au format ISO à définir. |
Corrélation entre les propriétés VALEUR et VALEUR_LIBELLE
Dans le cas où l'objet Autosuggestion gère un libellé, les valeurs de ces deux propriétés sont liées :
- Si l'utilisateur saisit un libellé présent dans la liste de résultats, alors la valeur de l'objet est celle du couple valeur / libellé,
- Si l'utilisateur saisit un libellé non présent dans la liste de résultats, alors la valeur de l'objet a une valeur particulière.
Dans un contexte de manipulation de ces deux propriétés dans le L4G, la mise à jour d'une de ces propriétés déclenche la mise à jour de l'autre :
Instruction L4G |
Conséquence |
ASG_1:VALEUR_LIBELLE = 'texte' |
Mise à jour de la propriété VALEUR par la valeur correspondante dans la liste de résultats ou la valeur dans les cas limites. |
ASG_1 = '123' |
L'affectation est autorisée seulement si la valeur fait partie de la liste associée. Dans ce cas, la propriété VALEUR_LIBELLE est mise à jour. |
Calcul de la liste de résultats
La liste de résultats est calculée par application du critère de sélection sur l'objet LISTE associé à l'objet Autosuggestion. Ce traitement est déclenché au moment où l'utilisateur saisit du texte dans le champ de saisie.
Le calcul peut se faire soit de façon automatique, soit de façon manuelle :
- automatique : L'objet prend en charge le calcul du résultat de manière totalement transparente pour l'utilisateur. La liste est entièrement parcourue et si un élément de l'objet LISTE satisfait le critère, alors il est sélectionné (au sens *SELECT).
- manuel : L'utilisateur est chargé de choisir les éléments qui doivent faire partie de la liste de résultats en alimentant la liste associée. Il peut ainsi implémenter son propre critère de sélection. A la fin de ce traitement, tous les éléments présents dans l'objet LISTE associé font partie de la liste de résultats.
Le calcul de la liste de résultats est effectué dans le traitant de l'événement Ajax ONSUGGEST de l'objet Autosuggestion.
Le mode Automatique est le mode par défaut. L'activation du mode Manuel se fait par programmation, en fixant la propriété MODE_AUTOMATIQUE à *FAUX. Si cette propriété est à *VRAI, alors le code L4G saisi dans le bloc ONSUGGEST n'est pas exécuté.
Notion de performance
Pour des raisons de performance, la liste de résultats est calculée lorsque l'utilisateur a fini de modifier le texte saisi (c'est-à-dire après un certain laps de temps après l'appui de la dernière touche clavier) et non pas à chaque fois que l'utilisateur appuie sur une touche.
Il est possible d'agir sur le temps d'affichage de la liste de résultats via plusieurs actions :
- Fixer le nombre minimum de caractères saisis à partir duquel le traitant d'événement ONSUGGEST sera déclenché (par défaut ce nombre est égal à 1).
- Limiter le nombre de valeurs résultat à afficher en définissant un nombre maximum d'éléments de la liste de résultats à retourner. Par défaut, tous les éléments de la liste de résultats sont affichés.
- En mode manuel, optimiser l'algorithme de recherche des valeurs résultat en travaillant sur une liste triée si cela est possible.
- Utiliser la gestion du cache dans l'objet Autosuggestion : l'objet est capable de mémoriser les précédentes listes de résultats pour ne pas avoir à lancer une nouvelle requête à chaque demande.
- Activer les fonctionnalités "sensible à la casse" et "sensible aux accents" lorsque cela est possible (si le contrôle de saisie lié au champ Autosuggestion est "Tout en majuscules" ou "Numérique" par exemple).
Utilisation de l'objet Autosuggestion via les raccourcis clavier
En termes de manipulation de l'objet au clavier, les actions suivantes sont possibles :
- Fermer la liste de résultats via la touche d'échappement. De même, si l'utilisateur vide le champ de saisie, alors la liste de résultats se ferme.
- Changer l'élément sélectionné via les touches Haut / Bas ou Pagination Avant / Arrière (de même qu'avec le curseur de la souris en le déplaçant sur le texte de l'élément).
- Récupérer l'élément sélectionné dans le champ de saisie via les touches Entrée, Tabulation ou flèche droite (de même qu'en cliquant sur l'élément). La liste de résultats se ferme.
- Positionner le curseur dans le champ de saisie lorsqu'on est en sélection sur un élément via la touche Home. La liste de résultats reste visible.
L'objet Autosuggestion possède un certain nombre de caractéristiques permettant de définir son fonctionnement :
Caractéristique |
Description |
Mode |
Définit le mode d'association de la liste. Les valeurs possibles sont :
Dans le mode Table liste, l'utilisateur doit choisir un objet TABLE LISTE présent dans la page. Sont exclus les objets :
Cette fonctionnalité est à définir au maquettage de l'objet Autosuggestion. |
Nombre de caractères minimum |
Définit le nombre minimum de caractères saisis par l'utilisateur à partir duquel l'objet déclenche une requête de demande de valeurs résultat. Cette fonctionnalité est à définir au maquettage de l'objet Autosuggestion ou par programmation. |
Nombre maximum de résultats |
Définit le nombre maximum de valeurs résultat retou rnées. Cette propriété permet de limiter le nombre de résultats si celui-ci est trop grand. Si ce nombre vaut -1, on renvoie toutes les valeurs possibles. Si ce nombre est positif, alors visuellement un texte indiquant qu'il existe d'autres valeurs est affiché au bas de la liste de résultats. Un clic sur ce texte permet d'afficher les autres résultats en déclenchant un événement ONSUGGEST. Ce texte peut être internationalisé : pour cela, il faut définir une valeur aux clés MORE_ELT_SHORT_TEXT et MORE_ELT_TOOLTIP dans un fichier nommé 'AWSTagLibAutosuggestBundle_XX.properties' (voir l'attribut " Sensible aux accents " de l'objet Autosuggestion).
Cette fonctionnalité n'est supportée qu'en mode automatique du calcul de la liste de résultats. En mode manuel, c'est à l'utilisateur que revient la charge de limiter le nombre d'éléments présents dans la liste de résultats en fonction de cette valeur. De plus, il doit gérer le clic sur le texte indiquant qu'il existe d'autres valeurs via les propriétés AUTRES_ELEMENTS et CLE_DERNIER_ELEMENT.
Cette fonctionnalité est à définir au maquettage de l'objet Autosuggestion ou par programmation. |
Gestion du cache |
Le but de cette fonctionnalité est de permettre d'augmenter les performances d'affichage de la liste de résultats. En effet, cette gestion peut être utile dans les cas suivants :
Attention : Le cas 2 peut provoquer une requête au serveur si la fonctionnalité "Nombre maximum de résultats" est différente de -1 et que le résultat de la recherche pour "A" est incomplète.
Cette fonctionnalité est à définir au maquettage de l'objet Autosuggestion ou par programmation.
Le cache a une durée de vie liée à l'objet Autosuggestion. Lorsque celui-ci est recréé (cas d'un chargement de page via un événement non Ajax ou lorsqu'on cache puis rend visible l'objet dans des traitants d'événements Ajax consécutifs) alors le cache est vidé. |
Surlignage du premier élément |
Surligne le premier élément de la liste de résultats lorsque celle-ci est affichée. Par défaut, l'élément surligné a une couleur de fond et une couleur de texte prédéfinies (valeur définies dans la classe CSS AWSAutosuggestHighlight). Il est possible de spécifier une autre classe CSS.
Cette fonctionnalité est à définir au maquettage de l'objet Autosuggestion. |
Proposer saisie |
Affiche, dans le champ de saisie, le premier élément de la liste de résultats en sélectionnant la sous-chaîne de texte qui reste à saisir. Cette fonctionnalité n'est autorisée que si le surlignage du premier élément est activé.
Elle est à définir au maquettage de l'objet Autosuggestion. |
Critère de sélection |
Définit un critère de sélection à appliquer pour calculer la liste de résultats. L'objet Autosuggestion offre plusieurs critères prédéfinis :
Le choix du critère influence la performance de la gestion du cache : celui-ci sera moins performant avec le critère "finit par", car l'affinage de la recherche au fil des caractères saisis ne permettra pas d'utiliser les résultats des recherches précédentes. Remarque : Si l'utilisateur veut définir son propre critère de sélection, il lui suffit de paramétrer l'objet en mode de calcul manuel de la liste de résultats et d'implémenter son propre algorithme de recherche.
Cette fonctionnalité est à définir au maquettage de l'objet Autosuggestion ou par programmation. |
Sensible à la casse |
Définit si le critère de sélection est sensible à la casse, c'est-à-dire si on distingue les majuscules des minuscules dans le calcul de la liste de résultats.
Cette fonctionnalité est à définir au maquettage de l'objet Autosuggestion. |
Sensible aux accents |
Définit si le critère de sélection est sensible aux accents, c'est-à-dire si on distingue les caractères accentués des caractères non accentués dans le calcul de la liste de résultats.
Cette fonctionnalité est à définir au maquettage de l'objet Autosuggestion.
Remarque sur l'internationalisation : Lorsque l'objet n'est pas sensible aux accents, il convertit les caractères accentués en caractères non accentués équivalents. Cette équivalence est supportée pour les langues française (code langue ISO-639 'fr'), italienne (code langue ISO-639 'it'), espagnole (code langue ISO-639 'es') et allemande (code langue ISO-639 'de'). Pour le support d'une autre langue, il est nécessaire de décrire cette équivalence dans un fichier nommé 'AWSTagLibAutosuggestBundle_XX.properties' où XX représente le code langue ISO-639. Ce fichier doit être placé dans le sous-répertoire AWSResources du répertoire contenant l'application Web. De plus, il doit être encodé au format ISO-8859-1 (ou Latin-1). Chaque correspondance (sous la forme CLE = VALEUR) entre un caractère et les caractères accentués associés doit être définie comme suit (une correspondance par ligne dans le fichier) : DIACRITIC_CAR_<INCR>=<CHAR_WHITOUT_ACCENT>-<CHAR_WITH_ACCENT_1>-<CHAR_WITH_ACCENT_2>-....-<CHAR_WITH_ACCENT_N> Où : - <INCR> est un numéro commençant à 1 et à incrémenter pour chaque ligne, - <CHAR_WITHOUT_ACCENT> est le caractère sans accent en minuscule, - <CHAR_WITH_ACCENT_N> sont les caractères accentués en minuscule en correspondance avec <CHAR_WITHOUT_ACCENT>. Si un caractère n'existe pas dans la table d'encodage ISO-8859-1 alors il doit être écrit en utilisant sa valeur dans la table d'encodage Unicode comme suit : '\uXXXX' où XXXX correspond à la valeur hexadécimale du caractère dans la table d'encodage Unicode (Exemple : le caractère € est converti en '\u20AC'). |
Effet visuel |
Définit l'effet visuel d'apparition de la liste de résultats. Cette propriété n'est supportée que par Internet Explorer.
Cette fonctionnalité est à définir au maquettage de l'objet Autosuggestion. |
Ombre |
Définit une ombre autour de la liste de résultats.
Cette fonctionnalité est à définir au maquettage de l'objet Autosuggestion. |
Sélection forcée |
Force l'utilisateur à sélectionner un élément dans la liste de résultats. Si l'utilisateur saisit une chaîne qui ne correspond à aucune valeur, alors le champ de saisie est vidé à la perte de focus de celui-ci.
Cette fonctionnalité est à définir au maquettage de l'objet Autosuggestion. |
Activité |
Définit l'activité du champ de saisie.
Cette fonctionnalité est à définir au maquettage de l'objet Autosuggestion ou par programmation. |
Lecture seule |
Définit si le champ de saisie autorise la saisie de caractères.
Cette fonctionnalité est à définir au maquettage de l'objet Autosuggestion ou par programmation. |
Obligatoire |
Permet de définir une zone obligatoire. Si le formulaire est soumis et qu'aucune valeur n'a été saisie, une erreur est détectée.
Cette fonctionnalité est à définir au maquettage de l'objet Autosuggestion ou par programmation. |
Classe CSS de la liste de r ésultats |
Définit une classe de style CSS pour la liste de résultats. Cette classe est affectée au conteneur (un tag HTML DIV) de la liste de résultats.
Cette fonctionnalité est à définir au maquettage de l'objet Autosuggestion ou par programmation. |
Classe CSS de surlignage |
Définit une classe de style CSS utilisée pour différencier l'élément à sélectionner dans la liste de résultats.
Cette fonctionnalité est à définir au maquettage de l'objet Autosuggestion ou par programmation. |
Classe CSS des éléments |
Définit une classe de style CSS pour l'affichage de chaque élément de la liste de résultats. Cette classe n'est utilisée que lorsque l'objet Autosuggestion est en mode Liste déroulante. Cette fonctionnalité est à définir au maquettage de l'objet Autosuggestion ou par programmation. |
En-tête |
Définit un libellé d'en-tête dans la liste de résultats. Cet en-tête peut être soit du texte, soit un fragment HTML. Il est affiché au-dessus du premier élément de la liste de résultats.
Cette fonctionnalité est à définir au maquettage de l'objet Autosuggestion. |
Pied de page |
Définit un libellé de pied de page dans la liste de résultats. Ce pied de page peut être soit du texte, soit un fragment HTML. Il est affiché au bas de la liste de résultats.
Cette fonctionnalité est à définir au maquettage de l'objet Autosuggestion. |
Largeur de la liste de résultats |
Définit une largeur pour l'affichage de la liste de résultats. Cette largeur doit être définie par une valeur suivie d'une unité (ex : "120px", "200em").
Cette fonctionnalité est à définir au maquettage de l'objet Autosuggestion ou par programmation. |
Hauteur de la liste de résultats |
Définit une hauteur maximum pour l'affichage de la liste de résultats. Cette hauteur doit être définie par une valeur suivie d'une unité (ex : "120px", "200em"). Lorsque la hauteur réelle de la liste est supérieure à sa hauteur maximum, alors un ascenseur vertical apparaît à droite des éléments de la liste. |
L'objet Autosuggestion utilise, en plus des propriétés graphiques, un certain nombre de classes de style CSS prédéfinies (dans la feuille de styles AWSGUIControls.jsp du répertoire AWSResources).
Lorsqu'on a plusieurs objets Autosuggestion (dans une même page ou dans plusieurs parties d'un même canevas), il est possible de surcharger les classes générales en leur affectant des valeurs d'attributs différentes pour chaque objet.
Suivant la balise à laquelle la classe est affectée, il faut procéder comme suit :
Pour chaque classe dont on connaît la valeur de l'attribut ID de la balise, il faut utiliser la classe nommée correspondant à la valeur de l'ID.
Classe |
ID de la balise |
Classe nommée |
AWSAutosuggestDiv |
divAsg<NOM_OBJET_AUTOSUGGEST> |
#divAsg<NOM_OBJET_AUTOSUGGEST> |
AWSAutosuggestHeader |
divHdAsg<NOM_OBJET_AUTOSUGGEST> |
#divHdAsg<NOM_OBJET_AUTOSUGGEST> |
AWSAutosuggestFooter |
divFtAsg<NOM_OBJET_AUTOSUGGEST> |
#divFtAsg<NOM_OBJET_AUTOSUGGEST> |
AWSAutosuggestBody |
divBdAsg<NOM_OBJET_AUTOSUGGEST> |
#divBdAsg<NOM_OBJET_AUTOSUGGEST> |
Si la classe nommée surcharge un attribut déjà défini dans la classe générale, il faut caractériser cet attribut avec !important.
Exemple :
.AWSAutosuggestDiv { /* classe utilisée par tous les objets Autosuggestion de la page */
background-color:#0A0B0C;
}
#divAsgASG_2 { /* classe utilisée seulement par l'objet Autosuggestion ASG_2 */
background-color:#334455 !important;
}
Pour une meilleure compréhension des fonctionnalités graphiques de cet objet, il est conseillé d'étudier les exemples fournis dans la base de connaissances Adélia (dans le domaine EXEMPLE_WEB de l'environnement BDCADEL).
Cliquez ci-dessous pour plus de détails sur :