Issuu on Google+

SPRY 1.4

GUIDE DE DÉVELOPPEMENT


© 2007 Adobe Systems Incorporated. Tous droits réservés. Copyright

Cadre applicatif Spry pour Ajax Guide de l'utilisateur pour Windows® et Mac OS Si le présent guide est fourni avec un logiciel régi par un contrat d'utilisateur final, ce guide, ainsi que le logiciel décrit, sont fournis sous licence et peuvent être utilisés ou copiés uniquement selon les clauses et conditions de la licence. A moins d’une autorisation expresse accordée par cette licence, aucune partie de ce guide ne peut être reproduite, stockée dans un système d’interrogation ou transmise, sous quelque forme ou par quelque moyen que ce soit (électronique, mécanique, par enregistrement ou autre) sans l’autorisation écrite préalable d’Adobe Systems Incorporated. Veuillez noter que le contenu du présent guide est protégé par la loi sur les droits d’auteur, même s’il n’est pas distribué avec un logiciel régi par un contrat de licence utilisateur. Les informations contenues dans ce guide sont fournies à titre purement informatif ; elles sont susceptibles d’être modifiées sans préavis et ne doivent pas être interprétées comme étant un engagement de la part d’Adobe Systems Incorporated. Adobe Systems Incorporated n’accepte aucune responsabilité quant aux erreurs ou inexactitudes pouvant être contenues dans le présent guide. Veuillez noter que les illustrations et images existantes que vous souhaiterez éventuellement inclure dans votre projet sont susceptibles d’être protégées par les lois sur les droits d’auteur. L’inclusion non autorisée de tels éléments dans vos nouveaux travaux peut constituer une violation des droits du propriétaire. Veuillez vous assurer que vous obtenez toute autorisation nécessaire auprès du détenteur du copyright. Toute référence à des noms de sociétés dans les modèles types n'est utilisée qu'à titre d'exemple et ne fait référence à aucune société réelle. Adobe, le logo Adobe, Dreamweaver et Flash sont des marques commerciales ou des marques déposées d'Adobe Systems Incorporated aux Etats-Unis et/ou dans d'autres pays. Microsoft et Windows sont des marques ou des marques déposées de Microsoft Corporation aux Etats-Unis et/ou dans d’autres pays. Apple et Mac OS sont des marques commerciales d'Apple Computer, Inc., déposées aux Etats-Unis et dans d'autres pays. Toutes les autres marques citées sont la propriété de leurs détenteurs respectifs. Adobe Systems Incorporated, 345 Park Avenue, San Jose, California 95110, USA. Avis aux utilisateurs du gouvernement des Etats-Unis. Le logiciel et la documentation sont des « articles commerciaux », conformément à la définition du terme « Commercial Items » dans l’article 48 C.F.R. §2.101 du Code de la réglementation fédérale (Code Of Federal Regulations), qui consistent en du « logiciel informatique commercial » et de la « documentation logicielle commerciale », tel qu’il est mentionné dans les articles 48 C.F.R. §12.212 et 48 C.F.R. §227.7202. Conformément aux articles 48 C.F.R. §12.212 et 48 C.F.R. §§227.7202-1 à 227.7202-4, le logiciel commercial et la documentation logicielle commerciale sont fournis sous licence aux utilisateurs du gouvernement des Etats-Unis (a) uniquement à titre d’articles commerciaux (b) et leur confèrent seulement les droits octroyés à tous les autres utilisateurs selon les conditions mentionnées aux présentes. Droits non publiés réservés dans le cadre des lois sur les droits d’auteur en vigueur aux Etats-Unis. Adobe Systems Incorporated, 345 Park Avenue, San Jose, CA 95110-2704, USA. A l'attention des utilisateurs finaux du gouvernement des Etats-Unis, Adobe s'engage à respecter toutes les lois sur l'égalité des chances, y compris, si approprié, les dispositions de l'Executive Order 11246, comme modifié, la section 402 de l'Acte d'assistance à la réhabilitation des vétérans du Vietnam (Vietnam Era Veterans Readjustment Assistance Act) de 1974 (38 USC 4212) et la section 503 de l'Acte de réhabilitation (Rehabilitation Act) de 1973, comme modifié, ainsi que les règlements de l'article 41 C.F.R., sections 60-1 à 6060, 60-250 et 60-741. Les règlements et la clause d'action affirmative contenus dans la phrase précédente doivent être inclus comme référence.


iii

Sommaire Chapitre 1 : Présentation de Spry 1.4 A propos du cadre applicatif Spry 1.4 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1 Chapitre 2 : Utilisation de widgets Spry A propos des widgets Spry . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2 Avant de commencer

......................................................................3

Utilisation du widget Accordéon

...........................................................4

Utilisation du widget Panneau réductible

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13

Utilisation du widget Panneaux à onglet

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21

Utilisation du widget Barre de menus

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30

Utilisation du widget Champ de texte de validation Utilisation du widget Zone de texte de validation Utilisation du widget Validation de la sélection Utilisation du widget Validation de case à cocher

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 74

Chapitre 3 : Utilisation des ensembles de données XML Spry A propos des ensembles de données XML Spry et des régions dynamiques Création de pages dynamiques avec Spry Obtention et manipulation de données Utilisation des régions dynamiques

. . . . . . . . . . . . . . . . 81

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 99 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .108

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .114

Chapitre 4 : Utilisation des effets Spry A propos des effets Spry . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .125 Avant de commencer Association d'effets Index

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .126 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .126

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .135


1

Chapitre 1 : Présentation de Spry 1.4 Le cadre applicatif Spry 1.4 pour Ajax est une bibliothèque JavaScript qui permet aux concepteurs de créer des pages Web enrichies, plus intéressantes et plus interactives.

A propos du cadre applicatif Spry 1.4 A propos du cadre applicatif Spry 1.4 Le cadre applicatif Spry 1.4 pour Ajax est une bibliothèque JavaScript qui permet aux concepteurs Web de créer des pages Web offrant une expérience enrichie aux visiteurs de leurs sites. Avec Spry, vous pouvez utiliser du code HTML et CSS, ainsi qu'une quantité minime de JavaScript, afin d'incorporer des données XML dans vos documents HTML, de créer des widgets tels que des accordéons et des barres de menus, ou encore ajouter différents effets à divers éléments de page. Le cadre applicatif Spry est conçu de telle sorte que le code soit simple et facile à utiliser pour toute personne possédant une connaissance de base du langage HTML, de CSS et de JavaScript. Le cadre applicatif Spry est principalement destiné aux professionnels de la conception Web ou aux concepteurs Web amateurs expérimentés. Il n'est pas destiné à servir de cadre d'applications Web à part entière pour le développement Web au niveau de l'entreprise, bien qu'il puisse être employé en combinaison avec d'autres pages au niveau de l'entreprise. Le cadre applicatif Spry 1.4 comprend trois composants principaux qui permettent de créer des pages dynamiques : les widgets, les ensembles de données XML et les effets. Les widgets sont des éléments de page, comme des accordéons et des panneaux à onglets, qui accroissent l'attrait et l'interactivité d'une page. Les ensembles de données XML permettent d'afficher sur la page Web des données provenant d'une source de données XML, un peu comme une application Web standard permet d'afficher des données à partir d'une base de données. Enfin, les effets Spry, tels que Fondu ou Ecraser, ajoutent du mouvement à la page, de manière à améliorer l'expérience de l'utilisateur. vous pouvez afficher des données XML à l'intérieur d'un widget et lui ajouter des effets afin de créer des pages plus riches que ce que permet le code HTML statique. Les sections qui suivent fournissent davantage d'informations sur l'emploi individuel de widgets, d'ensembles de données et d'effets. Vous trouverez des exemples d'utilisation du cadre applicatif Spry, dont des exemples combinant widgets, ensembles de données et effets, sur la page consacrée au cadre applicatif Spry du site Adobe Labs, à l'adresse http://labs.adobe.com/technologies/spry/. Cette page contient également les mises à jour les plus récentes de Spry.

A propos de Spry 1.4 et Dreamweaver Spry 1.4 est la version de Spry fournie avec Dreamweaver CS3. Cette documentation est dès lors adaptée aux actifs Spry inclus dans Dreamweaver. Toutefois, cette version de la documentation n'étudie pas les outils visuels permettant de créer des pages Spry dans Dreamweaver CS3. Pour plus d'informations sur l'emploi des outils Spry dans Dreamweaver, consultez l'aide de Dreamweaver. Pour obtenir la version la plus récente de l'aide du cadre applicatif Spry (c.-à-d. Spry 1.5 et les versions ultérieures), rendezvous à l'adresse www.adobe.com/go/learn_spry_fr. Il se peut que les versions futures de l'aide de Spry ne soient pas compatibles avec les actifs Spry actuellement fournis avec Dreamweaver. Si vous utilisez Dreamweaver CS3 et que vous voulez employer des versions ultérieures du cadre applicatif Spry, veillez à également télécharger les versions les plus récentes des actifs Spry depuis le site Adobe Labs.


2

Chapitre 2 : Utilisation de widgets Spry Un widget Spry est un élément de page qui combine des données HTML, CSS et JavaScript pour permettre l'interaction de l'utilisateur. Le cadre applicatif Spry pour Ajax prend en charge un ensemble de widgets réutilisables rédigés en code HTML, CSS et JavaScript standard.

A propos des widgets Spry A propos des widgets Spry Un widget Spry est un élément de page qui combine du code HTML, CSS et JavaScript pour permettre l'interaction de l'utilisateur. Le widget Spry se compose des éléments suivants : Structure du widget Bloc de code HTML qui définit la composition structurelle du widget. Comportement du widget Du code JavaScript qui détermine comment le widget répond aux événements provoqués par

l'utilisateur. Style du widget Du code CSS qui définit l'apparence du widget.

Le cadre applicatif Spry prend en charge un ensemble de widgets réutilisables rédigés en code HTML, CSS et JavaScript standard. Vous pouvez insérer aisément ces widgets, dont le code est du langage HTML et CSS extrêmement simple, puis définir le style du widget. Les comportements du cadre applicatif comprennent des fonctionnalités qui permettent aux utilisateurs d'afficher ou de masquer du contenu sur la page, de modifier l'apparence de la page (par exemple sa couleur), d'interagir avec des menus, et bien plus encore. Chaque widget du cadre applicatif Spry est associé à des fichiers CSS et JavaScript uniques, disponibles sur le site Adobe Labs. Le fichier CSS contient toutes les informations requises pour définir le style du widget, alors que le fichier JavaScript lui confère ses fonctionnalités. Les fichiers CSS et JavaScript associés à un widget sont nommés selon ce dernier. De la sorte, vous saurez aisément quels fichiers correspondent à chaque widget. Par exemple, les fichiers associés au widget Accordéon sont nommés SpryAccordion.css et SpryAccordion.js.

Accessibilité des widgets Spry et dégradation de JavaScript Il est essentiel, pour que le widget soit utilisable, qu'il soit accessible en respectant les conventions de navigations Web courantes ci-après. Comme vous ne pouvez pas supposer que l'utilisateur emploie une souris, Adobe a fait en sorte que tous les aspects des widgets actuellement disponibles soient accessibles via le clavier. Par exemple, dans le widget Accordéon, vous pouvez utiliser les touches portant une flèche vers le haut et vers le bas pour ouvrir les panneaux de contenu. Adobe encourage tous les développeurs de widgets à intégrer ce type de fonctionnalité. Il est également impossible de contrôler l'environnement de l'utilisateur final. Adobe développe ses widgets de sorte que, si JavaScript est désactivé, tout leur contenu soit toujours disponible à l'écran. Bien qu'il soit plus que probable que la mise en page s'en ressente, il importe davantage que le contenu du widget soit toujours disponible, en particulier dans le cas de widgets qui fonctionnent par révélation des données. Adobe a veillé à ce que les états CSS par défaut ne fixent pas la visibilité à hidden (masqué) et que le code HTML ne soit pas placé en dehors de l'écran.

Instructions de codage pour le développement de widgets Spry L'un des objectifs de Spry consiste à permettre à la communauté des utilisateurs de créer et de partager des widgets. Adobe a défini un ensemble d'instructions pour la création de widgets à distribution publique. Adobe fournit ces instructions dans le but que tous les widgets possèdent des fonctionnalités de base cohérentes.

• Employez du code HTML standard pour la structure. • N'exigez pas de code CSS si ce n'est pas nécessaire.


SPRY 3 Guide de l'utilisateur

• Si vos fonctionnalités exigent du code CSS, documentez précisément les conditions requises. • Utilisez (si possible) une seule ligne de code JavaScript pour définir les fonctionnalités du widget. • Insérez des options de navigation au clavier dans une fonction par défaut. • Si JavaScript est désactivé, le contenu doit toujours être visible sur la page • Les widgets doivent être autonomes. Tout ce dont le widget peut avoir besoin est fourni dans les fichiers HTML, JavaScript et CSS. Le respect de ces directives garantit la facilité de compréhension et d'utilisation des widgets. En outre, leur cohérence renforce le cadre applicatif pour tous ses utilisateurs. L'emploi de code standard est important, car il exige moins d'apprentissage de la part de l'utilisateur non spécialisé. Il facilite en outre l'emploi de ces widgets dans un éditeur WYSIWYG. Le code CSS est utilisé dans certains widgets pour afficher et masquer le contenu, en permutant la règle de visibilité dans le code CSS. Voici un exemple d'utilisation obligatoire de CSS. Une telle utilisation est acceptable, car le code CSS est le mécanisme le plus évident pour afficher et masquer le contenu. Toutefois, il est déconseillé d'employer du code CSS à des seules fins de définition de style. Le widget doit toujours fonctionner sans définition de style. Documentez les règles CSS obligatoires en insérant des commentaires dans le fichier CSS. Si vous fournissez un complément de documentation, ajoutez-y également ces commentaires. La plupart des widgets sont activés au moyen d'une seule ligne de code JavaScript qui suit directement le code du widget proprement dit. Tentez d'employer un nombre minimal d'arguments JavaScript. La largeur et la hauteur des widgets doit être définie en code CSS, et non en JavaScript, sauf s'il est impossible de faire autrement. La navigation au clavier et l'accessibilité sont des caractéristiques importantes pour les utilisateurs et pour Spry. Insérez des fonctionnalités de navigation au clavier, de façon à permettre aux utilisateurs d'employer les touches de productivité courantes (touches fléchées, barre d'espace) pour accéder à toutes les parties du widget. Employez si nécessaire des fonctionnalités telles que l'ordre de tabulation. Il est essentiel que le contenu ne soit pas masqué dans des environnements qui ne prennent pas en charge les scripts. Assurez-vous que, lorsque JavaScript est désactivé, le contenu ne soit pas masqué en raison de la désactivation de la visibilité CSS ou du placement du contenu en dehors de l'écran.

Avant de commencer Préparation des fichiers Avant d'ajouter des widgets Spry à vos pages Web, téléchargez et liez les fichiers appropriés. 1 Recherchez le fichier ZIP de Spry sur le site Adobe® Labs. 2 Téléchargez ce fichier ZIP et décompressez-le sur votre disque dur. 3 Ouvrez le dossier Spry décompressé et recherchez-y le dossier "widgets". Ce dossier contient tous les fichiers nécessaires pour l'ajout de widget Spry et leur mise en forme. 4 Ajoutez les fichiers de widget à votre site Web en procédant d'une des manières suivantes :

• Copiez le dossier "widgets" et collez-en une copie (ou faites-la glisser) dans le répertoire racine de votre site Web. Vous disposerez ainsi de tous les fichiers nécessaires pour les widgets pris en charge par Spry.

• Créez un dossier dans votre site Web (par exemple, un dossier nommé SpryAssets), ouvrez le dossier widgets et copiez uniquement les fichiers ou les dossiers relatifs aux widgets que vous voulez ajouter. Par exemple, pour n'ajouter qu'un widget accordéon à vos pages Web, copiez le dossier "accordion" ou les fichiers SpryAccordion.js et SpryAccordion.css . Remarque : Si vous faites glisser le dossier "widgets" d'origine ou des fichiers spécifiques à partir du dossier Spry non décompressé, les démos du dossier Spry ne fonctionneront pas correctement. Veillez à copier et coller ces éléments dans votre site Web au lieu de les manipuler par glisser-déplacer.


SPRY 4 Guide de l'utilisateur

5 Lorsque les fichiers JavaScript et CSS corrects pour votre widget font partie du site Web, vous pouvez les lier et ajouter des widgets Spry à vos pages. Pour plus d'informations sur l'ajout d'un widget spécifique à une page, reportez-vous aux section relatives à chacun d'eux.

Utilisation du widget Accordéon Présentation et structure du widget Accordéon Un widget Accordéon est un ensemble de panneaux réductibles pouvant stocker une grande quantité de contenu tout en restant compact. Les visiteurs du site affichent ou masquent le contenu stocké dans l'accordéon en cliquant sur l'onglet du panneau. Les panneaux de l'accordéon se développent ou se réduisent à mesure que le visiteur clique sur les différents onglets. Dans un accordéon, un seul panneau de contenu est ouvert et visible à tout moment. L'exemple suivant montre un widget Accordéon dont le deuxième panneau est développé : A

B

C

A. Onglet du panneau accordéon B. Contenu du panneau accordéon C. Panneau accordéon (ouvert)

Le code HTML par défaut du widget Accordéon comprend une balise div extérieure contenant tous les panneaux, une balise div pour chaque panneau, ainsi qu'une balise div d'en-tête et une balise div de contenu à l'intérieur de la balise pour chaque panneau. Un widget Accordéon peut contenir n'importe quel nombre de panneaux distincts. Le code HTML du widget Accordéon comprend également des balises script dans l'en-tête du document et après le code HTML de l'accordéon. La balise script dans l'en-tête du document définit toutes les fonctions JavaScript relatives au widget Accordéon. La balise script qui suit le code du widget Accordéon crée un objet JavaScript qui rend l'accordéon interactif. Voici le code HTML

d'un widget Accordéon :


SPRY 5 Guide de l'utilisateur

<head> ... <!--Link the CSS style sheet that styles the accordion--> <link href="SpryAssets/SpryAccordion.css" rel="stylesheet" type="text/css" /> <!--Link the Spry Accordion JavaScript library--> <script src="SpryAssets/SpryAccordion.js" type="text/javascript"></script> </head> <body> <!--Create the Accordion widget and assign classes to each element--> <div id="Accordion1" class="Accordion"> <div class="AccordionPanel"> <div class="AccordionPanelTab">Panel 1</div> <div class="AccordionPanelContent"> Panel 1 Content<br/> Panel 1 Content<br/> Panel 1 Content<br/> </div> </div> <div class="AccordionPanel"> <div class="AccordionPanelTab">Panel 2</div> <div class="AccordionPanelContent"> Panel 2 Content<br/> Panel 2 Content<br/> Panel 2 Content<br/> </div> </div> <div class="AccordionPanel"> <div class="AccordionPanelTab">Panel 3</div> <div class="AccordionPanelContent"> Panel 3 Content<br/> Panel 3 Content<br/> Panel 3 Content<br/> </div> </div> <div class="AccordionPanel"> <div class="AccordionPanelTab">Panel 4</div> <div class="AccordionPanelContent"> Panel 4 Content<br/> Panel 4 Content<br/> Panel 4 Content<br/> </div> </div> </div> <script type="text/javascript"> var Accordion1 = new Spry.Widget.Accordion("Accordion1"); </script> </body>

Dans le code, l'opérateur JavaScript new initialise l'objet widget Accordéon et transforme le contenu div possédant l'ID Accordion1, qui était un code HTML statique, en un élément de page interactif. La méthode Spry.Widget.Accordion est un constructeur du cadre applicatif Spry qui crée des objets Accordéon. Les informations nécessaires pour initialiser l'objet figurent dans la bibliothèque JavaScript SpryAccordion.js que vous avez liée dans l'en-tête du document. Chaque balise div du widget Accordéon contient une classe CSS. Ces classes contrôlent le style du widget Accordéon et se trouvent dans le fichier SpryAccordion.css qui l'accompagne. Vous pouvez modifier l'apparence de n'importe quelle partie du widget Accordéon en modifiant le code CSS qui correspond aux noms des classes qui lui sont attribués dans le code HTML. Par exemple, pour modifier la couleur d'arrière-plan des onglets de l'accordéon, modifiez la règle AccordionPanelTab dans le fichier CSS. N'oubliez pas que la modification du code CSS dans le fichier SpryAccordion.css influera sur tous les accordéons liés à ce fichier.


SPRY 6 Guide de l'utilisateur

Outre les classes figurant dans le code HTML, le widget Accordéon comprend des comportements par défaut qui sont associés au widget. Ces comportements font partie intégrante du cadre applicatif Spry et se trouvent dans le fichier de bibliothèque JavaScript SpryAccordion.js. La bibliothèque Accordion contient des comportements relatifs au survol par le pointeur de souris, au clic sur les onglets (pour ouvrir des panneaux), à la définition du panneau actif et à la navigation au clavier. Vous pouvez modifier l'apparence de l'accordéon, par rapport à ces comportements, en modifiant les classes appropriées dans le fichier SpryAccordion.css. Si vous souhaitez, à un moment donné, supprimer un comportement, vous pouvez supprimer les règles CSS qui y correspondent. Remarque : S'il est possible de modifier l'apparence de l'accordéon par rapport à un comportement précis, il est par contre impossible de modifier les comportements intégrés. Par exemple, Spry placera toujours une classe AccordionFocused sur un accordéon actif, même si aucune propriété n'est définie pour la classe AccordionFocused dans le fichier SpryAccordion.css. Variation des balises utilisées pour la structure du widget Accordéon

Dans l'exemple précédent, les balises div créent une structure de balises imbriquées pour le widget : Container div Panel div Tab div Content div

Cette structure à 3 niveaux et 4 conteneurs est essentielle au bon fonctionnement du widget Accordéon. La structure est toutefois plus importante que les balises que vous décidez d'employer. Spry lit la structure (pas nécessairement les balises div) et construit le widget sur sa base. Tant que la structure à 3 niveaux et 4 conteneurs est en place, vous pouvez utiliser n'importe quel élément de niveau bloc pour créer le widget : Container div Panel div H3 tag P tag

Les balises div dans l'exemple se caractérisent par une souplesse qui leur permet de contenir d'autres éléments de niveau bloc. Une balise p (ou toute autre balise intégrée) ne peut toutefois pas contenir d'autres éléments de niveau bloc. Il est dès lors impossible de l'utiliser comme conteneur ou comme balise de panneau pour l'accordéon.

Code CSS du widget Accordéon Le fichier SpryAccordion.css contient les règles qui définissent le style du widget Accordéon. Vous pouvez modifier ces règles afin de modifier l'apparence et le fonctionnement de l'accordéon. Les noms des règles dans le fichier CSS correspondent directement aux noms des classes définies dans le code HTML du widget Accordéon. Remarque : Vous pouvez remplacer les noms de classes relatives au style, dans le fichier SpryAccordion.css et dans le code HTML, par les noms de classes de votre choix. Vous n'influerez en rien sur les fonctionnalités du widget, car le code CSS n'est pas requis pour celles-ci. Les fonctionnalités par défaut des classes des comportements, à la fin de la feuille de style, sont définies dans le fichier de bibliothèque JavaScript SpryAccordion.js. Vous pouvez modifier les fonctionnalités par défaut en ajoutant des propriétés et des valeurs aux règles de comportement de la feuille de style. Le code CSS du fichier SpryAccordion.css est le suivant :


SPRY 7 Guide de l'utilisateur

/*Accordion styling classes*/ .Accordion { border-left: solid 1px gray; border-right: solid 1px black; border-bottom: solid 1px gray; overflow: hidden; } .AccordionPanel { margin: 0px; padding: 0px; } .AccordionPanelTab { background-color: #CCCCCC; border-top: solid 1px black; border-bottom: solid 1px gray; margin: 0px; padding: 2px; cursor: pointer; } .AccordionPanelContent { overflow: auto; margin: 0px; padding: 0px; height: 200px; } .AccordionPanelOpen .AccordionPanelTab { background-color: #EEEEEE; } .AccordionPanelClosed .AccordionPanelTab { } /*Accordion behaviors classes*/ .AccordionPanelTabHover { color: #555555; } .AccordionPanelOpen .AccordionPanelTabHover { color: #555555; } .AccordionFocused .AccordionPanelTab { background-color: #3399FF; } .AccordionFocused .AccordionPanelOpen .AccordionPanelTab { background-color: #33CCFF; }

Le fichier SpryAccordion.css contient de nombreux commentaires qui expliquent le code et le rôle de certaines règles. Pour plus d'informations, consultez les commentaires dans le fichier.

Insertion du widget Accordéon 1 Recherchez le fichier SpryAccordion.js et ajoutez-le à votre site Web. Le fichier SpryAccordion.js se trouve dans le répertoire widgets/accordion qui figure dans le répertoire Spry téléchargé depuis le site Adobe Labs. Pour plus d'informations, consultez la section « Préparation des fichiers » à la page 3. Par exemple, créez un dossier nommé SpryAssets dans le dossier racine de votre site Web, puis déplacez-y le fichier SpryAccordion.js. Le fichier SpryAccordion.js contient toutes les informations qui rendent l'accordéon interactif. 2 Recherchez le fichier SpryAccordion.css et ajoutez-le à votre site Web. Vous pouvez l'ajouter dans le répertoire principal, dans un répertoire SpryAssets ou dans un répertoire CSS, si vous en avez créé un. 3 Ouvrez la page Web à laquelle ajouter le widget Accordéon et liez le fichier SpryAccordion.js à la page en insérant la balise script suivante dans la balise "head" de la page : <script src="SpryAssets/SpryAccordion.js" type="text/javascript"></script>

Assurez-vous que le chemin d'accès au fichier SpryAccordion.js est bien correct. Ce chemin d'accès varie selon l'endroit où vous avez placé le fichier dans votre site Web.


SPRY 8 Guide de l'utilisateur

4 Liez le fichier SpryAccordion.css à votre page Web en insérant la balise link suivante dans la balise "head" de la page : <link href="SpryAssets/SpryAccordion.css" rel="stylesheet" type="text/css" />

Assurez-vous que le chemin d'accès au fichier SpryAccordion.css est bien correct. Ce chemin d'accès varie selon l'endroit où vous avez placé le fichier dans votre site Web. 5 Ajoutez l'accordéon à la page Web en insérant la balise div suivante à l'endroit de la page où l'accordéon doit apparaître : <div id="Accordion1" class="Accordion"> </div>

6 Ajoutez des panneaux à l'accordéon en insérant des balises <div id="Accordion1"...>, comme suit :

class="AccordionPanel"> à l'intérieur de la balise<div

<div id="Accordion1" class="Accordion"> <div class="AccordionPanel"> </div> <div class="AccordionPanel"> </div> </div>

Le code précédent ajoute deux panneaux à l'accordéon. Vous pouvez ajouter autant de panneaux que vous le souhaitez. 7 Pour ajouter des onglets aux panneaux, insérez des balises div balisediv class="AccordionPanel", comme suit :

class="AccordionPanelTab" à l'intérieur de chaque

<div class="AccordionPanel"> <div class="AccordionPanelTab">Panel 1 Title</div> </div>

8 Pour ajouter une zone de contenu aux panneaux, insérez des balises div balisediv class="AccordionPanel", comme suit :

class="AccordionPanelContent" dans chaque

<div class="AccordionPanel"> <div class="AccordionPanelTab">Panel 1 Title</div> <div class="AccordionPanelContent">Panel 1 Content</div> </div>

Insérez le contenu entre les balises AccordionPanelContent d'ouverture et de fermeture. Par exemple, Panel 1 Content, comme dans l'exemple précédent. Le contenu peut être n'importe quel code HTML, y compris des éléments de formulaire HTML. 9 Pour initialiser l'objet Accordéon Spry, insérez le bloc de script suivant après le code HTML du widget Accordéon : <div id="Accordion1" class="Accordion"> . . . </div> <script type="text/javascript"> var Accordion1 = new Spry.Widget.Accordion("Accordion1"); </script>

L'opérateur JavaScript new initialise l'objet widget Accordéon et transforme le contenu div possédant l'ID Accordion1, qui était un code HTML statique, en un objet Accordéon interactif. La méthode Spry.Widget.Accordion est un constructeur du cadre applicatif Spry qui crée des objets Accordéon. Les informations requises pour l'initialisation de l'objet figurent dans la bibliothèque JavaScript SpryAccordion.js que vous avez liée au début de cette procédure. Assurez-vous que l'ID de la balise div de l'accordéon corresponde au paramètre ID spécifié dans la méthode Spry.Widgets.Accordion. Assurez-vous que l'appel JavaScript se trouve bien après le code HTML du widget.

10 Enregistrez la page. Le code complet ressemble à ce qui suit :


SPRY 9 Guide de l'utilisateur

<head> ... <link href="SpryAssets/SpryAccordion.css" rel="stylesheet" type="text/css" /> <script src="SpryAssets/SpryAccordion.js" type="text/javascript"></script> </head> <body> <div id="Accordion1" class="Accordion"> <div class="AccordionPanel"> <div class="AccordionPanelTab">Panel 1</div> <div class="AccordionPanelContent"> Panel 1 Content<br/> Panel 1 Content<br/> Panel 1 Content<br/> </div> </div> <div class="AccordionPanel"> <div class="AccordionPanelTab">Panel 2</div> <div class="AccordionPanelContent"> Panel 2 Content<br/> Panel 2 Content<br/> Panel 2 Content<br/> </div> </div> <div class="AccordionPanel"> <div class="AccordionPanelTab">Panel 3</div> <div class="AccordionPanelContent"> Panel 3 Content<br/> Panel 3 Content<br/> Panel 3 Content<br/> </div> </div> <div class="AccordionPanel"> <div class="AccordionPanelTab">Panel 4</div> <div class="AccordionPanelContent"> Panel 4 Content<br/> Panel 4 Content<br/> Panel 4 Content<br/> </div> </div> </div> <script type="text/javascript"> var Accordion1 = new Spry.Widget.Accordion("Accordion1"); </script> </body>

Ajout d'un panneau à un widget Accordéon ❖ Insérez une balise div class="AccordionPanel" (ainsi que les balises d'un onglet de panneau et d'une zone de contenu

de panneau) à l'intérieur de la balise div conteneur de l'accordéon. Lorsque vous ajoutez le code, n'oubliez pas d'ajouter la balise </div> de fermeture. Par exemple : <div id="Accordion1" class="Accordion"> <div class="AccordionPanel"> <div class="AccordionPanelTab"></div> <div class="AccordionPanelContent"></div> </div> </div>

Le code précédent ajoute un panneau au widget Accordéon. Vous pouvez ajouter autant de panneaux que vous le souhaitez.

Suppression d'un panneau d'un widget Accordéon ❖ Supprimez la balise div class="AccordionPanel" désirée (ainsi que ses balises de contenu ou enfants) de la balisediv

conteneur de l'accordéon. Lorsque vous supprimez le code, n'oubliez pas de supprimer la balise /div de fermeture.


SPRY 10 Guide de l'utilisateur

Activation de la navigation au clavier Il importe que chaque widget soit rendu accessible pour la navigation au clavier. La navigation au clavier permet à l'utilisateur de contrôler le widget à l'aide des touches fléchées et de touches personnalisées. La base de la navigation au clavier consiste en l'attribut tabIndex. Cet attribut indique au navigateur comment naviguer dans le document. ❖ Pour permettre la navigation au clavier dans l'accordéon, ajoutez une valeur TabIndex à la balise conteneur de l'accordéon, comme suit : <div id="Acc1" class="Accordion" tabIndex="0">

Si l'attribut tabIndex possède la valeur zéro (0), c'est le navigateur qui détermine l'ordre. Si l'attribut tabIndex possède une valeur entière positive, c'est cette valeur qui détermine l'ordre. Remarque : L'application de tabIndex à une balise div n'est pas conforme à la norme XHTML 1.0. Vous pouvez également définir des touches personnalisées pour la navigation au clavier. Les touches personnalisées sont définies comme des arguments du script constructeur de l'accordéon : <script type="text/javascript"> var acc3= new Spry.Widget.Accordion("Acc3", { nextPanelKeyCode: 78 /* n key */, previousPanelKeyCode: 80 /* p key */ }); </script>

Définition du panneau ouvert par défaut Vous pouvez stipuler qu'un panneau précis sera ouvert lorsque la page contenant les widgets Accordéon est chargée dans un navigateur. ❖ Définissez l'option defaultPanel dans le constructeur de la manière suivante : <script type="text/javascript"> var acc8 = new Spry.Widget.Accordion("Accordion1", { defaultPanel: 2 }); </script>

Remarque : Les panneaux de l'accordéon emploient un système de comptage en base zéro. Si la valeur est fixée à 2, c'est dès lors le troisième panneau qui s'ouvre.

Ouverture de panneaux par voie de programmation Vous pouvez ouvrir différents panneaux, par voie de programmation, en utilisant des fonctions JavaScript. Par exemple, vous pouvez placer sur votre page un bouton qui ouvre un panneau d'accordéon précis lorsque l'utilisateur clique dessus. ❖ Utilisez les fonctions JavaScript suivantes pour ouvrir des panneaux d'accordéon : <input type="button" onclick="acc10.openFirstPanel()" >open first panel</input> <input type="button" onclick="acc10.openNextPanel()" >open next panel</input> <input type="button" onclick="acc10.openPreviousPanel()" >open previous panel</input> <input type="button" onclick="acc10.openLastPanel()" >open last panel</input> <script type="text/javascript"> var acc10 = new Spry.Widget.Accordion("Accordion1"); </script>

Personnalisation du widget Accordéon Le fichier SpryAccordion.css fournit le style par défaut du widget Accordéon. Vous pouvez toutefois personnaliser aisément ce widget en modifiant le code CSS approprié. Les règles CSS du fichier SpryAccordion.css utilisent les mêmes noms de classes que les éléments apparentés dans le code HTML de l'accordéon. Vous pouvez ainsi déterminer aisément quelles règles correspondent aux différentes sections du widget Accordéon. En outre, le fichier SpryAccordion.css contient des noms de classes pour les comportements associés au widget (par exemple, les comportements relatifs au survol du pointeur de souris et au clic). Le fichier SpryAccordion.css doit déjà être placé sur votre site Web avant que vous entamiez des activités de personnalisation. Pour plus d'informations, consultez la section « Préparation des fichiers » à la page 3.


SPRY 11 Guide de l'utilisateur

Remarque : Internet Explorer, jusqu'à sa version 6, ne prend pas en charge les sélecteurs contextuels d'apparentement et d'enfants (par exemple .AccordionPanel + .AccordionPanel ou .Accordion > .AccordionPanel). Définition du style du widget Accordéon (instructions générales)

Vous pouvez définir des propriétés pour le conteneur du widget Accordéon entier ou en définir pour des composants spécifiques du widget. 1 Ouvrez le fichier SpryAccordion.css. 2 Accédez à la règle CSS pour la partie de l'accordéon à modifier. Par exemple, pour modifier la couleur d'arrière-plan des onglets de l'accordéon, modifiez la règle AccordionPanelTab dans le fichier CSS. 3 Apportez les modifications désirées au code CSS puis enregistrez le fichier. Vous pouvez remplacer les noms de classes relatives au style, dans le fichier SpryAccordion.css et dans le code HTML, par les noms de classes de votre choix. Vous n'influerez en rien sur les fonctionnalités du widget. Le fichier SpryAccordion.css contient de nombreux commentaires qui expliquent le code et le rôle de certaines règles. Pour plus d'informations, consultez les commentaires dans le fichier. Définition du style du widget Accordéon

Vous pouvez définir des propriétés pour le conteneur du widget Accordéon entier ou en définir pour des composants spécifiques du widget. ❖ Pour modifier le style du texte d'un widget Accordéon, recherchez la règle CSS appropriée dans le fichier SpryAccordion.css, en vous aidant du tableau suivant, puis ajoutez vos propriétés et valeurs de style du texte. Texte à modifier

Règle CSS pertinente

Exemple de propriétés et de valeurs à ajouter

Texte dans l'accordéon entier (onglet et panneau de contenu)

.Accordion ou .AccordionPanel

font: Arial; font-size:medium;

Texte dans les onglets du panneau accordéon uniquement

.AccordionPanelTab

font: Arial; font-size:medium;

Texte dans les panneaux de contenu de l'accordéon uniquement

.AccordionPanelContent

font: Arial; font-size:medium;

Modification des couleurs d'arrière-plan du widget Accordéon ❖ Recherchez la règle CSS appropriée dans le fichier SpryAccordion.css en vous aidant du tableau suivant, puis ajoutez ou modifiez les propriétés et les valeurs de couleur d'arrière-plan. Partie du widget à modifier

Règle CSS pertinente

Exemple de propriété et de valeur à ajouter ou modifier

Couleur d'arrière-plan des onglets du panneau accordéon

.AccordionPanelTab

background-color: #CCCCCC; (Valeur par défaut)

Couleur d'arrière-plan des panneaux de .AccordionPanelContent contenu de l'accordéon

background-color: #CCCCCC;

Couleur d'arrière-plan du panneau accordéon ouvert

.AccordionPanelOpen .AccordionPanelTab

background-color: #EEEEEE; (Valeur par défaut)

Couleur d'arrière-plan des onglets de panneau lorsque le pointeur de la souris passe au-dessus

.AccordionPanelTabHover

color: #555555; (Valeur par défaut)

Couleur d'arrière-plan de l'onglet de panneau ouvert lorsque le pointeur de la souris passe au-dessus

.AccordionPanelOpen .AccordionPanelTabHover

color: #555555; (Valeur par défaut)


SPRY 12 Guide de l'utilisateur

Limitation de la largeur d'un accordéon

Par défaut, le widget Accordéon se développe pour occuper l'espace disponible. Pour limiter la largeur d'un widget Accordéon, définissez une propriété « width » pour le conteneur. 1 Repérez la règle CSS .Accordion dans le fichier SpryAccordion.css. Cette règle définit les propriétés de l'élément conteneur principal du widget Accordéon. 2 Ajoutez une propriété et une valeur de largeur (width) à la règle, par exemple width:

300px;.

Modification de la hauteur d'un panneau accordéon

Par défaut, la hauteur des panneaux du widget Accordion est fixée à 200 pixels. Pour modifier la hauteur des panneaux, modifiez la propriété "height" dans la règle .AccordionPanelContent. 1 Repérez la règle CSS .AccordionPanelContent dans le fichier SpryAccordion.css. 2 Donnez à la propriété "height" la valeur de votre choix. Remarque : Veillez à toujours définir cette valeur, pour garantir que tous les panneaux seront de la même taille. Modification des comportements d'un panneau accordéon

Le widget Accordéon comprend quelques comportements prédéfinis. Ces comportements servent à modifier les classes CSS lorsqu'un événement précis se produit. Par exemple, lorsque le pointeur de la souris survole l'onglet d'un panneau accordéon, Spry applique la classe AccordionPanelTabHover au widget. Ce comportement est similaire à a:hover pour les liens. Les comportements sont vides par défaut. Pour les modifier, ajoutez des propriétés et des valeurs aux règles. 1 Ouvrez le fichier SpryAccordion.css et accédez à la règle CSS correspondant au comportement d'accordéon à modifier. Le widget Accordéon comprend quatre règles intégrées pour les comportements. Comportement

Description

.AccordionPanelTabHover

Activé en cas de survol de l'onglet du panneau.

.AccordionPanelOpen

Activé sur l'onglet du panneau ouvert.

.AccordionPanelClosed

Activé sur les panneaux fermés.

.AccordionFocused

Activé lorsque l'accordéon entier est actif.

Vous trouverez des exemples dans le fichier exemple Accordion qui se trouve dans le répertoire "samples" du répertoire Spry téléchargé depuis le site Adobe Labs. Pour plus d'informations, consultez la section « Préparation des fichiers » à la page 3. 2 Ajoutez des règles CSS aux comportements que vous voulez activer. Remarque : Vous ne pouvez pas remplacer des noms de classes associées à des comportements dans le fichier SpryAccordion.css par des noms de classes de votre choix, car les comportements sont incorporés au cadre applicatif Spry. Pour donner un nom personnalisé à une classe par défaut, envoyez la nouvelle valeur en tant qu'argument au constructeur de l'accordéon, comme le montre l'exemple suivant : <script type="text/javascript"> var acc2 = new Spry.Widget.Accordion("Acc2", { hoverClass: "hover", openClass: "open", closedClass: "closed", focusedClass: "focused" }); </script>

Désactivation de l'animation des panneaux

Par défaut, les panneaux accordéon emploient une animation pour s'ouvrir et se fermer progressivement. Vous pouvez toutefois désactiver cette animation de manière à ce que les panneaux s'ouvrent et se ferment instantanément. ❖ Pour désactiver l'animation, envoyez un argument au constructeur de l'accordéon, comme suit : <script type="text/javascript"> var acc5 = new Spry.Widget.Accordion("Acc5", { enableAnimation: false }); </script>


SPRY 13 Guide de l'utilisateur

Définition de la durée de l'animation

Vous pouvez modifier la durée requise pour qu'un panneau s'ouvre. Cette durée est définie en millisecondes (1000 = 1 seconde). Par défaut, Spry utilise un délai de 500 millisecondes. ❖ Vous pouvez ajouter l'option de durée au constructeur : <script type="text/javascript"> var acc9 = new Spry.Widget.Accordion("Acc9", { duration: 100 }); </script>

Définition de hauteurs de panneau variables

Par défaut, lorsque l'animation est activée, Spry force tous les panneaux de contenu de l'accordéon à avoir la même hauteur. Spry dérive cette hauteur de celle du panneau ouvert par défaut dans l'accordéon, qui est déterminée par du code CSS ou par la hauteur du contenu dans le panneau. L'accordéon accepte également les panneaux à hauteur variable. Pour activer cette prise en charge, transmettez une option useFixedPanelHeights: false au constructeur de l'accordéon. ❖ Pour transmettre une option useFixedPanelHeights:false, procédez comme suit : <script type="text/javascript"> var acc7 = new Spry.Widget.Accordion("Acc7", { useFixedPanelHeights: false }); </script>

Vous trouverez un exemple dans le fichier exemple Accordion qui se trouve dans le répertoire "samples" du répertoire Spry téléchargé depuis le site Adobe Labs. Pour plus d'informations, consultez la section « Préparation des fichiers » à la page 3. Pour forcer Spry à fixer la hauteur du panneau à une valeur précise à l'aide de JavaScript (au lieu de code CSS), transmettez l'option fixedPanelHeight qui définit les hauteurs des panneaux de contenu par voie de programmation. Cette option emploie les pixels comme unité de mesure. <script type="text/javascript"> var acc7 = new Spry.Widget.Accordion("Acc7", { fixedPanelHeight: "300px" }); </script>

Utilisation du widget Panneau réductible Présentation et structure du widget Panneau réductible Un widget Panneau réductible est un panneau qui peut stocker du contenu en n'occupant que peu de place. Les utilisateurs affichent ou masquent le contenu stocké dans le panneau réductible en cliquant sur l'onglet du widget. L'exemple suivant montre un widget Panneau réductible développé et réduit.

A

B

A. Développé B. Réduit

Le code HTML du widget Panneau réductible se compose d'une balise div extérieure qui comprend la balise de contenu div et de la balise conteneur d'ongletdiv. Le code HTML du widget Panneau réductible comprend également des balises script dans l'en-tête du document et après le code HTML du panneau réductible. La balise script dans l'en-tête du document définit toutes les fonctions JavaScript relatives au widget Panneau réductible. La balise script qui suit le code du widget Panneau réductible crée un objet JavaScript qui rend le panneau réductible interactif. Voici le code HTML d'un widget Panneau réductible :


SPRY 14 Guide de l'utilisateur

<head> ... <!--Link the CSS style sheet that styles the Collapsible Panel--> <link href="SpryAssets/SpryCollapsiblePanel.css" rel="stylesheet" type="text/css" /> <!--Link the Spry Collapsible Panel JavaScript library--> <script src="SpryAssets/SpryCollapsiblePanel.js" type="text/javascript"></script> </head> <body> <!--Create the Collapsible Panel widget and assign classes to each element--> <div id="CollapsiblePanel1" class="CollapsiblePanel"> <div class="CollapsiblePanelTab">Tab</div> <div class="CollapsiblePanelContent">Content</div> </div> <!--Initialize the Collapsible Panel widget object--> <script type="text/javascript"> var CollapsiblePanel1 = new Spry.Widget.CollapsiblePanel("CollapsiblePanel1"); </script> </body>

Dans le code, l'opérateur JavaScript new initialise l'objet widget Panneau réductible et transforme le contenu div possédant l'ID CollapsiblePanel1, qui était un code HTML statique, en un élément de page interactif. La méthode Spry.Widget.CollapsiblePanel est un constructeur du cadre applicatif Spry qui crée des objets panneau réductible. Les informations nécessaires pour initialiser l'objet figurent dans la bibliothèque JavaScript SpryCollapsiblePanel.js que vous avez liée dans l'en-tête du document. Chaque élément du widget Panneau réductible contient une classe CSS. Ces classes contrôlent le style du widget Panneau réductible et se trouvent dans le fichier SpryCollapsiblePanel.css qui l'accompagne. Vous pouvez modifier l'apparence de n'importe quelle partie du widget Panneau réductible en modifiant le code CSS qui correspond aux noms des classes qui lui sont attribués dans le code HTML. Par exemple, pour modifier la couleur d'arrièreplan des onglets du panneau réductible, modifiez la règle CollapsiblePanelTab dans le fichier CSS. N'oubliez pas que la modification du code CSS dans le fichier SpryCollapsiblePanel.css influera sur tous les panneaux réductibles liés à ce fichier. Outre les classes figurant dans le code HTML, le widget Panneau réductible comprend des comportements par défaut qui sont associés au widget. Ces comportements font partie intégrante du cadre applicatif Spry et se trouvent dans le fichier de bibliothèque JavaScript SpryCollapsiblePanel.js. La bibliothèque Collapsible Panel contient des comportements relatifs au survol par le pointeur de souris, au clic sur les onglets (pour ouvrir et fermer le panneau), à l'activation du panneau et à la navigation au clavier. Vous pouvez modifier l'apparence du panneau réductible, par rapport à ces comportements, en modifiant les classes appropriées dans le fichier SpryCollapsiblePanel.css. Si vous souhaitez, à un moment donné, supprimer un comportement, vous pouvez supprimer les règles CSS qui y correspondent. Remarque : S'il est possible de modifier l'apparence du panneau réductible par rapport à un comportement précis, il est par contre impossible de modifier les comportements intégrés. Par exemple, Spry applique toujours une classe CollapsiblePanelFocused au panneau actuellement ouvert, même si aucune propriété n'est définie pour la classe CollapsiblePanelFocused dans le fichier SpryCollapsiblePanel.css. Variation des balises utilisées pour la structure du widget Panneau réductible

Dans l'exemple précédent, les balises div créent une structure de balises imbriquées pour le widget : Container div Tab div Content div

Cette structure à 2 niveaux et 3 conteneurs est essentielle au bon fonctionnement du widget Panneau réductible. La structure est toutefois plus importante que les balises que vous décidez d'employer. Spry lit la structure (pas nécessairement les balises div) et construit le widget sur sa base. Tant que la structure à 2 niveaux et 3 conteneurs est en place, vous pouvez utiliser n'importe quel élément de niveau bloc pour créer le widget :


SPRY 15 Guide de l'utilisateur

Container div H3 tag P tag

Les balises div dans l'exemple se caractérisent par une souplesse qui leur permet de contenir d'autres éléments de niveau bloc. Une balise p (ou toute autre balise intégrée) ne peut toutefois pas contenir d'autres éléments de niveau bloc. Il est dès lors impossible de l'utiliser comme conteneur ou comme balise de panneau pour le panneau réductible.

Code CSS du widget Panneau réductible Le fichier SpryCollapsiblePanel.css contient les règles qui définissent le style du widget Panneau réductible. Vous pouvez modifier ces règles afin de modifier l'apparence et le fonctionnement du panneau réductible. Les noms des règles dans le fichier CSS correspondent directement aux noms des classes définies dans le code HTML du widget Panneau réductible. Remarque : Vous pouvez remplacer les noms de classes relatives au style, dans le fichier SpryCollapsiblePanel.css et dans le code HTML, par les noms de classes de votre choix. Vous n'influerez en rien sur les fonctionnalités du widget, car le code CSS n'est pas requis pour celles-ci. Les fonctionnalités par défaut des classes des comportements, à la fin de la feuille de style, sont définies dans le fichier de bibliothèque JavaScript SpryCollapsiblePanel.js. Vous pouvez modifier les fonctionnalités par défaut en ajoutant des propriétés et des valeurs aux règles de comportement de la feuille de style. Le code CSS du fichier SpryCollapsiblePanel.css est le suivant : /*Collapsible Panel styling classes*/ .CollapsiblePanel { margin: 0px; padding: 0px; border-left: solid 1px #CCC; border-right: solid 1px #999; } .CollapsiblePanelTab { font: bold 0.7em sans-serif; background-color: #DDD; border-top: solid 1px #999; border-bottom: solid 1px #CCC; margin: 0px; padding: 2px; cursor: pointer; -moz-user-select: none; -khtml-user-select: none; } .CollapsiblePanelContent { margin: 0px; padding: 0px; border-bottom: solid 1px #CCC; } .CollapsiblePanelTab a { color: black; text-decoration: none; } .CollapsiblePanelOpen .CollapsiblePanelTab { background-color: #EEE; } .CollapsiblePanelTabHover, .CollapsiblePanelOpen .CollapsiblePanelTabHover { background-color: #CCC; } .CollapsiblePanelFocused .CollapsiblePanelTab { background-color: #3399FF; }

Le fichier SpryCollapsiblePanel.css contient de nombreux commentaires qui expliquent le code et le rôle de certaines règles. Pour plus d'informations, consultez les commentaires dans le fichier.


SPRY 16 Guide de l'utilisateur

Insertion du widget Panneau réductible 1 Recherchez le fichier SpryCollapsiblePanel.js et ajoutez-le à votre site Web. Le fichier SpryCollapsiblePanel.js se trouve dans le répertoire widgets/collapsiblepanel qui figure dans le répertoire Spry téléchargé depuis le site Adobe Labs. Pour plus d'informations, consultez la section « Préparation des fichiers » à la page 3. Par exemple, créez un dossier nommé SpryAssets dans le dossier racine de votre site Web, puis déplacez-y le fichier SpryCollapsiblePanel.js. Le fichier SpryCollapsiblePanel.js contient toutes les informations qui rendent le widget Panneau réductible interactif. 2 Recherchez le fichier SpryCollapsiblePanel.js et ajoutez-le à votre site Web. Vous pouvez l'ajouter dans le répertoire principal ou dans un répertoire CSS, si vous en avez créé un. 3 Ouvrez la page Web à laquelle ajouter le widget Panneau réductible et liez le fichier SpryCollapsiblePanel.js à la page en insérant la balise script suivante dans la balise "head" de la page : <script src="SpryAssets/SpryCollapsiblePanel.js" type="text/javascript"></script>

Assurez-vous que le chemin d'accès au fichier SpryCollapsiblePanel.js est bien correct. Ce chemin d'accès varie selon l'endroit où vous avez placé le fichier dans votre site Web. 4 Liez le fichier SpryCollapsiblePanel.js à votre page Web en insérant la balise link suivante dans la balise "head" de la page : <link href="SpryAssets/SpryCollapsiblePanel.css" rel="stylesheet" type="text/css" />

Assurez-vous que le chemin d'accès au fichier SpryCollapsiblePanel.css est bien correct. Ce chemin d'accès varie selon l'endroit où vous avez placé le fichier dans votre site Web. 5 Ajoutez le panneau réductible à la page Web en insérant la balise div suivante à l'endroit de la page où le panneau réductible doit apparaître : <div id="CollapsiblePanel1" class="CollapsiblePanel"> </div>

6 Pour ajouter un onglet au panneau réductible, insérez une balise div balise div class="CollapsiblePanel", comme suit :

class="CollapsiblePanelTab" à l'intérieur de la

<div id="CollapsiblePanel1" class="CollapsiblePanel"> <div class="CollapsiblePanelTab">Tab</div> </div>

7 Pour ajouter une zone de contenu au panneau, insérez une balise div de la balise div class="CollapsiblePanel", comme suit :

class="CollapsiblePanelContent" à l'intérieur

<div class="AccordionPanel"> <div class="CollapsiblePanelTab">Tab</div> <div class="CollapsiblePanelContent">Content</div> </div>

Insérez le contenu entre les balises CollapsiblePanelContent d'ouverture et de fermeture. Par exemple, Content, comme dans l'exemple précédent.. Le contenu peut être n'importe quel code HTML, y compris des éléments de formulaire HTML. 8 Pour initialiser l'objet Panneau réductible Spry, insérez le bloc de script suivant après le code HTML du widget Panneau réductible : <div id="CollapsiblePanel1" class="CollapsiblePanel"> . . . </div> <script type="text/javascript"> var acc1 = new Spry.Widget.CollapsiblePanel("CollapsiblePanel1"); </script>

L'opérateur JavaScript new initialise l'objet widget Panneau réductible et transforme le contenu div possédant l'ID CollapsiblePanel1, qui était un code HTML statique, en un objet Panneau réductible interactif. La méthode Spry.Widget.CollapsiblePanel est un constructeur du cadre applicatif Spry qui crée des objets panneau réductible. Les informations requises pour l'initialisation de l'objet figurent dans la bibliothèque JavaScript SpryCollapsiblePanel.js que vous avez liée au début de cette procédure.


SPRY 17 Guide de l'utilisateur

Assurez-vous que l'ID de la balise div du panneau réductible corresponde au paramètre ID spécifié dans la méthode Spry.Widgets.CollapsiblePanel. Assurez-vous que l'appel JavaScript se trouve bien après le code HTML du widget. 9 Enregistrez la page. Le code complet ressemble à ce qui suit : <head> ... <link href="SpryAssets/SpryCollapsiblePanel.css" rel="stylesheet" type="text/css" /> <script src="SpryAssets/SpryCollapsiblePanel.js" type="text/javascript"></script> </head> <body> <div id="CollapsiblePanel1" class="CollapsiblePanel"> <div class="CollapsiblePanelTab">Tab</div> <div class="CollapsiblePanelContent">Content</div> </div> <script type="text/javascript"> var CollapsiblePanel1 = new Spry.Widget.CollapsiblePanel("CollapsiblePanel1"); </script> </body>

Activation de la navigation au clavier Il importe que chaque widget soit rendu accessible pour la navigation au clavier. La navigation au clavier permet à l'utilisateur de contrôler le widget à l'aide de la barre d'espace ou de la touche Entrée. La base de la navigation au clavier consiste en l'attribut tabIndex. Cet attribut indique au navigateur comment utiliser les tabulations pour naviguer dans le document. ❖ Pour permettre la navigation au clavier dans le panneau réductible, ajoutez une valeur TabIndex à la balise conteneur de l'onglet du panneau réductible, comme suit : <div id="CollapsiblePanel1" class="CollapsiblePanel"> <div class="CollapsiblePanelTab" tabIndex="0">Tab</div> <div class="CollapsiblePanelContent">Content</div> </div>

Si l'attribut tabIndex possède la valeur zéro (0), c'est le navigateur qui détermine l'ordre. Si l'attribut tabIndex possède une valeur entière positive, c'est cette valeur qui détermine l'ordre. Pour activer la navigation au clavier, entourez le contenu de l'onglet d'une balise a. Remarque : L'application de tabIndex à une balise div n'est pas conforme à la norme XHTML 1.0.

Définition de l'état par défaut du panneau Par défaut, le widget Panneau réductible est ouvert lorsque la page Web se charge dans un navigateur. Vous pouvez toutefois modifier l'état du panneau si vous voulez qu'il soit fermé lors du chargement de la page. ❖ Définissez l'option contentIsOpen dans le constructeur de la manière suivante : <script type="text/javascript"> var CollapsiblePanel1 = new Spry.Widget.CollapsiblePanel("CollapsiblePanel1", { contentIsOpen: false }); </script>

Vous pouvez également consulter l'état du panneau à l'aide de la fonction isOpen. Le code suivant renvoie true si le panneau est ouvert et false s'il est fermé :


SPRY 18 Guide de l'utilisateur

<script type="text/javascript"> function getStatus(){ var xx = CollapsiblePanel1.isOpen(); document.form1.textfield.value = xx } </script> </head> <body> <div id="CollapsiblePanel1" class="CollapsiblePanel"> <div class="CollapsiblePanelTab" tabIndex="0" onclick="getStatus();">Tab</div> <div class="CollapsiblePanelContent">Content</div> </div> <form id="form1" name="form1" method="post" action=""> <input name="textfield" type="text" id="textfield" value="a" size="50" /> </form> <script type="text/javascript"> <!-var CollapsiblePanel1 = new Spry.Widget.CollapsiblePanel("CollapsiblePanel1"); //--> </script>

Ouverture du panneau par voie de programmation Vous pouvez ouvrir et fermer le widget Panneau réductible par voie de programmation en employant des fonctions JavaScript. Par exemple, vous pouvez placer sur votre page un bouton qui ouvre le panneau réductible lorsque l'utilisateur clique dessus. ❖ Utilisez les fonctions suivantes pour ouvrir ou fermer un panneau réductible : <input type="button" onclick="CollapsiblePanel1.open();" >open panel</input> <input type="button" onclick="CollapsiblePanel1.close();">close panel</input> <script type="text/javascript"> var CollapsiblePanel1 = new Spry.Widget.CollapsiblePanel("CollapsiblePanel1"); </script>

Personnalisation du widget Panneau réductible Le fichier SpryCollapsiblePanel.css fournit le style par défaut du widget Panneau réductible. Vous pouvez toutefois personnaliser aisément ce widget en modifiant la règle CSS appropriée. Les règles CSS du fichier SpryCollapsiblePanel.css utilisent les mêmes noms de classes que les éléments apparentés dans le code HTML du panneau réductible. Vous pouvez ainsi déterminer aisément quelles règles correspondent aux différentes sections du widget Panneau réductible. En outre, le fichier SpryCollapsiblePanel.css contient des noms de classes pour les comportements associés au widget (par exemple, les comportements relatifs au survol du pointeur de souris et au clic). Le fichier SpryCollapsiblePanel.css doit déjà être placé sur votre site Web avant que vous entamiez des activités de personnalisation. Pour plus d'informations, consultez la section « Préparation des fichiers » à la page 3. Remarque : Internet Explorer, jusqu'à sa version 6, ne prend pas en charge les sélecteurs contextuels d'apparentement et d'enfants (par exemple .CollapsiblePanel + .CollapsiblePanel ou .CollapsiblePanel > .CollapsiblePanel). Définition du style du widget Panneau réductible (instructions générales)

Vous pouvez définir des propriétés pour le conteneur du widget Panneau réductible entier ou en définir pour des composants spécifiques du widget. 1 Ouvrez le fichier SpryCollapsiblePanel.css. 2 Accédez à la règle CSS pour la partie du panneau réductible à modifier. Par exemple, pour modifier la couleur d'arrièreplan de l'onglet du panneau réductible, modifiez la règle CollapsiblePanelTab dans le fichier CSS. 3 Apportez les modifications désirées à la règle CSS puis enregistrez le fichier. Vous pouvez remplacer les noms de classes relatives au style, dans le fichier SpryCollapsiblePanel.css et dans le code HTML, par les noms de classes de votre choix. Vous n'influerez en rien sur les fonctionnalités du widget.


SPRY 19 Guide de l'utilisateur

Le fichier SpryCollapsiblePanel.css contient de nombreux commentaires qui expliquent le code et le rôle de certaines règles. Pour plus d'informations, consultez les commentaires dans le fichier. Définition du style du texte d'un widget Panneau réductible

Vous pouvez définir des propriétés pour le conteneur du widget Panneau réductible entier ou en définir pour des composants spécifiques du widget. ❖ Pour modifier le format du texte d'un widget Panneau réductible, recherchez la règle CSS appropriée dans le tableau suivant, puis ajoutez vos propriétés et valeurs de style du texte. Style à modifier

Règle CSS pertinente

Exemple de propriétés et de valeurs à ajouter ou modifier

Texte du panneau réductible entier

.CollapsiblePanel

font: Arial; font-size:medium;

Texte dans l'onglet du panneau uniquement

.CollapsiblePanelTab

font: bold 0.7em sans-serif; (Valeur par défaut)

Texte dans le panneau de contenu uniquement

.CollapsiblePanelContent

font: Arial; font-size:medium;

Modification des couleurs d'arrière-plan du widget Panneau réductible ❖ Recherchez la règle CSS appropriée en vous aidant du tableau suivant, puis ajoutez ou modifiez les propriétés et les valeurs de couleur d'arrière-plan. Couleur à modifier

Règle CSS pertinente

Exemple de propriété et de valeur à ajouter ou modifier

Couleur d'arrière-plan de l'onglet du panneau

.CollapsiblePanelTab

background-color: #DDD; (Valeur par défaut)

Couleur d'arrière-plan du panneau de contenu

.CollapsiblePanelContent

background-color: #DDD;

Couleur d'arrière-plan de l'onglet quand le panneau est ouvert

.CollapsiblePanelOpen .CollapsiblePanelTab

background-color: #EEE; (Valeur par défaut)

Couleur d'arrière-plan de l'onglet d'un panneau ouvert lorsque le pointeur de la souris passe au-dessus

.CollapsiblePanelTabHover, .CollapsiblePanelOpen .CollapsiblePanelTabHover

background-color: #CCC; (Valeur par défaut)

Limitation de la largeur d'un panneau réductible

Par défaut, le widget Panneau réductible se développe pour occuper l'espace disponible. Pour limiter la largeur d'un widget Panneau réductible, définissez une propriété « width » pour le conteneur. 1 Accédez à la règle CSS CollapsiblePanel dans le fichier SpryCollapsiblePanel.css. Cette règle définit les propriétés de l'élément conteneur principal du widget Panneau réductible. 2 Ajoutez une propriété et une valeur de largeur (width) à la règle, par exemple width:

300px;.

Modification de la hauteur d'un panneau réductible

Pour définir la hauteur d'un panneau réductible, ajoutez une propriété "height" à la règle CollapsiblePanelContent ou à la règle CollapsiblePanel. ❖ Dans le fichier SpryCollapsiblePanel.css, ajoutez une propriété "height" et une valeur à la règle CollapsiblePanelContent, par exemple height: 300px;.

Remarque : La définition de la hauteur dans la règle CollapsiblePanel permet de fixer la hauteur du widget entier, indépendamment de la taille du panneau de contenu.


SPRY 20 Guide de l'utilisateur

Modification des comportements d'un panneau réductible

Le widget Panneau réductible comprend quelques comportements prédéfinis. Ces comportements servent à modifier les classes CSS lorsqu'un événement précis se produit. Par exemple, lorsque le pointeur de la souris survole l'onglet d'un panneau réductible, Spry applique la classe CollapsiblePanelTabHover au widget. Ce comportement est similaire à a:hover pour les liens. Les comportements sont vides par défaut. Pour les modifier, ajoutez des propriétés et des valeurs aux règles. 1 Ouvrez le fichier SpryCollapsiblePanel.css et accédez à la règle CSS correspondant au comportement de panneau réductible à modifier. Le widget Panneau réductible comprend quatre règles intégrées pour les comportements. Comportement

Description

.CollapsiblePanelTabHover

Spry ajoute cette classe à l'élément d'onglet du widget dès que le pointeur de la souris le survole. La classe est automatiquement supprimée lorsque le pointeur quitte l'onglet.

.CollapsiblePanelOpen

Spry ajoute cette classe à l'élément supérieur du widget lorsque la zone de contenu du panneau est visible.

.CollapsiblePanelClosed

Spry ajoute cette classe à l'élément supérieur du widget lorsque la zone de contenu du panneau est fermée.

.CollapsiblePanelFocused

Spry ajoute cette classe à l'élément supérieur du widget lorsque le widget est activé pour la saisie au clavier.

Vous trouverez des exemples dans le fichier d'exemple de panneau réductible qui se trouve dans le répertoire "samples" du répertoire Spry téléchargé depuis le site Adobe Labs. Pour plus d'informations, consultez la section « Préparation des fichiers » à la page 3. 2 Ajoutez des règles CSS aux comportements que vous voulez activer. Remarque : Vous ne pouvez pas remplacer des noms de classes associées à des comportements dans le fichier SpryCollapsiblePanel.css par des noms de classes de votre choix, car les comportements sont incorporés au cadre applicatif Spry. Pour remplacer la classe par défaut par le nom de votre choix, envoyez les nouvelles valeurs, sous la forme d'arguments, au constructeur du panneau réductible. <script type="text/javascript"> var CP2 = new Spry.Widget.CollapsiblePanel("CollapsiblePanel2", { hoverClass: "hover", openClass: "open", closedClass: "closed", focusedClass: "focused" }); </script>

Désactivation de l'animation des panneaux

Par défaut, un panneau réductible emploie une animation pour s'ouvrir et se fermer progressivement. ❖ Pour désactiver l'animation, de manière à ce que le panneau s'ouvre et se ferme instantanément, envoyez un argument au constructeur du panneau réductible, comme suit : <script type="text/javascript"> var CP5 = new Spry.Widget.CollapsiblePanel("CollapsiblePanel5", { enableAnimation: false }); </script>

Définition de la durée de l'animation

Vous pouvez modifier la durée requise pour qu'un panneau s'ouvre. Cette durée est définie en millisecondes (1000 = 1 seconde). Par défaut, Spry utilise un délai de 500 millisecondes. ❖ Vous pouvez ajouter l'option duration (durée) au constructeur : <script type="text/javascript"> var CP9 = new Spry.Widget.CollapsiblePanel("CollapsiblePanel9", { duration: 100 }); </script>


SPRY 21 Guide de l'utilisateur

Utilisation du widget Panneaux à onglet Présentation et structure du widget Panneaux à onglet Un widget Panneaux à onglet est un ensemble de panneaux qui peuvent stocker du contenu en n'occupant que peu de place. Les visiteurs du site affichent ou masquent le contenu stocké dans les panneaux à onglet en cliquant sur l'onglet du panneau auquel ils veulent accéder. Les panneaux du widget s'ouvrent à mesure que le visiteur clique sur les différents onglets. Dans un widget Panneaux à onglet, un seul panneau de contenu est ouvert à tout moment. L'exemple suivant montre un widget Panneaux à onglet dont le troisième panneau est ouvert. A

B

C

D

A. Onglet B. Contenu C. Widget Panneaux à onglet D. Panneau à onglet

Le code HTML du widget Panneaux à onglet comprend une balise extérieure div qui contient tous les panneaux, la liste des onglets, une balise div comprenant les panneaux de contenu, ainsi qu'une balise div pour chaque panneau de contenu. Le code HTML du widget Panneaux à onglet comprend également des balises script dans l'en-tête du document et après le code HTML du widget Panneaux à onglet. La balise script dans l'en-tête du document définit toutes les fonctions JavaScript relatives au widget Panneaux à onglet. La balise script qui suit le code du widget Panneaux à onglet crée un objet JavaScript qui rend les panneaux à onglet interactifs. Voici le code HTML d'un widget Panneaux à onglet : <head> . . . <!--Link the CSS style sheet that styles the tabbed panel--> <link href="SpryAssets/SpryTabbedPanels.css" rel="stylesheet" type="text/css" /> <!--Link the Spry TabbedPanels JavaScript library--> <script src="SpryAssets/SpryTabbedPanels.js" type="text/javascript"></script> </head> <body> <!--Create the Tabbed Panel widget and assign classes to each element--> <div class="TabbedPanels" id="TabbedPanels1"> <ul class="TabbedPanelsTabGroup"> <li class="TabbedPanelsTab">Tab 1</li> <li class="TabbedPanelsTab">Tab 2</li> <li class="TabbedPanelsTab">Tab 3</li> <li class="TabbedPanelsTab">Tab 4</li> </ul> <div class="TabbedPanelsContentGroup"> <div class="TabbedPanelsContent">Tab 1 Content</div> <div class="TabbedPanelsContent">Tab 2 Content</div> <div class="TabbedPanelsContent">Tab 3 Content</div> <div class="TabbedPanelsContent">Tab 4 Content</div> </div> </div> <!--Initialize the Tabbed Panel widget object--> <script type="text/javascript"> var TabbedPanels1 = new Spry.Widget.TabbedPanels("TabbedPanels1"); </script> </body>


SPRY 22 Guide de l'utilisateur

Dans le code, l'opérateur JavaScript new initialise l'objet widget Panneaux à onglet et transforme le contenu div possédant l'ID TabbedPanels1, qui était un code HTML statique, en un élément de page interactif. La méthode Spry.Widget.TabbedPanels est un constructeur du cadre applicatif Spry qui crée des objets Panneaux à onglet. Les informations nécessaires pour initialiser l'objet figurent dans la bibliothèque JavaScript SpryTabbedPanels.js que vous avez liée dans l'en-tête du document. Chaque élément du widget Panneaux à onglet contient une classe CSS. Ces classes contrôlent le style du widget Panneaux à onglet et se trouvent dans le fichier SpryTabbedPanels.css qui l'accompagne. Vous pouvez modifier l'apparence de n'importe quelle partie du widget Panneaux à onglet en modifiant la règle CSS qui correspond aux noms des classes qui lui sont attribués dans le code HTML. Par exemple, pour modifier la couleur d'arrièreplan des onglets des panneaux à onglet, modifiez la règle TabbedPanelsTab dans le fichier CSS. N'oubliez pas que la modification du code CSS dans le fichier SpryTabbedPanels.css influera sur tous les panneaux à onglet liés à ce fichier. Outre les classes figurant dans le code HTML, le widget Panneaux à onglet comprend des comportements par défaut qui sont associés au widget. Ces comportements font partie intégrante du cadre applicatif Spry et se trouvent dans le fichier de bibliothèque JavaScript SpryTabbedPanels.js. La bibliothèque Tabbed Panel contient des comportements relatifs au survol par le pointeur de souris, au clic sur les onglets (pour ouvrir des panneaux), à la définition du panneau actif et à la navigation au clavier. Vous pouvez modifier l'apparence du panneau à onglet, par rapport à ces comportements, en modifiant les classes appropriées dans le fichier SpryTabbedPanels.css. Si vous souhaitez supprimer un comportement, vous pouvez supprimer les règles CSS qui y correspondent. Remarque : S'il est possible de modifier l'apparence du panneau à onglet par rapport à un comportement précis, il est par contre impossible de modifier les comportements intégrés. Par exemple, Spry applique toujours une classe TabbedPanelsContentVisible au panneau actuellement ouvert, même si aucune propriété n'est définie pour la classe TabbedPanelsContentVisible dans le fichier SpryTabbedPanels.css. Variation des balises utilisées pour la structure du widget Panneaux à onglet

Dans l'exemple précédent, les balises div et les éléments de liste créent une structure de balises imbriquées pour le widget : Container <div> Tabs <ul> Tab <li> Content container <div> Content <div>

Cette structure à 3 niveaux et 5 conteneurs est essentielle au bon fonctionnement du widget Panneaux à onglet. La structure est toutefois plus importante que les balises que vous décidez d'employer. Spry lit la structure (pas nécessairement les balises div) et construit le widget sur sa base. Tant que la structure à 3 niveaux et 5 conteneurs est en place, vous pouvez utiliser n'importe quel élément de niveau bloc pour créer le widget : Container <div> Tabs <div> Tab <h3> Content container <div> Content <p>

Les balises div dans l'exemple se caractérisent par une souplesse qui leur permet de contenir d'autres éléments de niveau bloc. Une balise p (ou toute autre balise intégrée) ne peut toutefois pas contenir d'autres éléments de niveau bloc. Il est dès lors impossible de l'utiliser comme conteneur ou comme balise de panneau pour le panneau à onglet.

Code CSS du widget Panneaux à onglet Le fichier SpryTabbedPanels.css contient les règles qui définissent le style du widget Panneaux à onglet. Vous pouvez modifier ces règles afin de modifier l'apparence et le fonctionnement du panneau à onglet. Les noms des règles dans le fichier CSS correspondent directement aux noms des classes définies dans le code HTML du widget Panneaux à onglet. Remarque : Vous pouvez remplacer les noms de classes relatives au style, dans le fichier SpryTabbedPanels.css et dans le code HTML, par les noms de classes de votre choix. Vous n'influerez en rien sur les fonctionnalités du widget, car le code CSS n'est pas requis pour celles-ci.


SPRY 23 Guide de l'utilisateur

Les fonctionnalités par défaut des classes des comportements, à la fin de la feuille de style, sont définies dans le fichier de bibliothèque JavaScript SpryTabbedPanels.js. Vous pouvez modifier les fonctionnalités par défaut en ajoutant des propriétés et des valeurs aux règles de comportement de la feuille de style. Le code CSS du fichier SpryTabbedPanels.css est le suivant : La première moitié du fichier contient des règles de mise en forme des panneaux à onglet horizontaux. La deuxième moitié du fichier contient des règles de mise en forme des panneaux à onglet verticaux. /* Horizontal Tabbed Panels */ .TabbedPanels { margin: 0px; padding: 0px; clear: both; width: 100%; /* IE Hack to force proper layout when preceded by a paragraph. (hasLayout Bug)*/ } .TabbedPanelsTabGroup { margin: 0px; padding: 0px; } .TabbedPanelsTab { position: relative; top: 1px; float: left; padding: 4px 10px; margin: 0px 1px 0px 0px; font: bold 0.7em sans-serif; background-color: #DDD; list-style: none; border-left: solid 1px #CCC; border-bottom: solid 1px #999; border-top: solid 1px #999; border-right: solid 1px #999; -moz-user-select: none; -khtml-user-select: none; cursor: pointer; } .TabbedPanelsTabHover { background-color: #CCC; } .TabbedPanelsTabSelected { background-color: #EEE; border-bottom: 1px solid #EEE; } .TabbedPanelsTab a { color: black; text-decoration: none; } .TabbedPanelsContentGroup { clear: both; border-left: solid 1px #CCC; border-bottom: solid 1px #CCC; border-top: solid 1px #999; border-right: solid 1px #999; background-color: #EEE; } .TabbedPanelsContent { padding: 4px; } .TabbedPanelsContentVisible { } /* Vertical Tabbed Panels */ .VTabbedPanels .TabbedPanelsTabGroup { float: left; width: 10em; height: 20em; background-color: #EEE;


SPRY 24 Guide de l'utilisateur

position: relative; border-top: solid 1px #999; border-right: solid 1px #999; border-left: solid 1px #CCC; border-bottom: solid 1px #CCC; } .VTabbedPanels .TabbedPanelsTab { float: none; margin: 0px; border-top: none; border-left: none; border-right: none; } .VTabbedPanels .TabbedPanelsTabSelected { background-color: #EEE; border-bottom: solid 1px #999; } .VTabbedPanels .TabbedPanelsContentGroup { clear: none; float: left; padding: 0px; width: 30em; height: 20em; }

Le fichier SpryTabbedPanels.css contient de nombreux commentaires qui expliquent le code et le rôle de certaines règles. Pour plus d'informations, consultez les commentaires dans le fichier.

Insertion du widget Panneaux à onglet 1 Recherchez le fichier SpryTabbedPanels.js et ajoutez-le à votre site Web. Le fichier SpryTabbedPanels.js se trouve dans le répertoire widgets/tabbedpanels qui figure dans le répertoire Spry téléchargé depuis le site Adobe Labs. Pour plus d'informations, consultez la section « Préparation des fichiers » à la page 3. Par exemple, créez un dossier nommé SpryAssets dans le dossier racine de votre site Web, puis déplacez-y le fichier SpryTabbedPanels.js. Le fichier SpryTabbedPanels.js contient toutes les informations qui rendent le widget Panneaux à onglet interactif. 2 Recherchez le fichier SpryTabbedPanels.css et ajoutez-le à votre site Web. Vous pouvez l'ajouter dans le répertoire principal, dans un répertoire SpryAssets ou dans un répertoire CSS, si vous en avez créé un. 3 Ouvrez la page Web à laquelle ajouter le widget Panneaux à onglet et liez le fichier SpryTabbedPanels.js à la page en insérant la balise script suivante dans la balise "head" de la page : <script src="SpryAssets/SpryTabbedPanels.js" type="text/javascript"></script>

Assurez-vous que le chemin d'accès au fichier SpryTabbedPanels.js est bien correct. Ce chemin d'accès varie selon l'endroit où vous avez placé le fichier dans votre site Web. 4 Liez le fichier SpryTabbedPanels.css à votre page Web en insérant la balise link suivante dans la balise "head" de la page : <link href="SpryAssets/SpryTabbedPanels.css" rel="stylesheet" type="text/css" />

Assurez-vous que le chemin d'accès au fichier SpryTabbedPanels.css est bien correct. Ce chemin d'accès varie selon l'endroit où vous avez placé le fichier dans votre site Web. 5 Ajoutez le widget Panneaux à onglet à la page Web en insérant la balise div suivante à l'endroit de la page où le panneau doit apparaître : <div id="TabbedPanels1" class="TabbedPanels"> </div>

6 Pour ajouter un onglet au panneau à onglet, insérez une balise ul class="TabbedPanelsTabGroup" à l'intérieur de la balise div id="TabbedPanels1"..., ainsi qu'une balise li class="TabbedPanelsTab" pour chaque onglet à ajouter, comme suit :


SPRY 25 Guide de l'utilisateur

<div class="TabbedPanels" id="TabbedPanels1"> <ul class="TabbedPanelsTabGroup"> <li class="TabbedPanelsTab">Tab 1</li> <li class="TabbedPanelsTab">Tab 2</li> <li class="TabbedPanelsTab">Tab 3</li> <li class="TabbedPanelsTab">Tab 4</li> </ul> </div>

Le code précédent ajoute quatre panneaux au widget. Vous pouvez ajouter autant d'onglets que vous le souhaitez. 7 Pour ajouter une zone de contenu (un panneau) à chaque onglet, insérez une balise conteneur div class="TabbedPanelsContentGroup" après la balise ul, ainsi qu'une balise div class="TabbedPanelsContent" pour

chaque panneau de contenu, comme suit : <div class="TabbedPanels" id="TabbedPanels1"> <ul class="TabbedPanelsTabGroup"> <li class="TabbedPanelsTab">Tab 1</li> <li class="TabbedPanelsTab">Tab 2</li> <li class="TabbedPanelsTab">Tab 3</li> <li class="TabbedPanelsTab">Tab 4</li> </ul> <div class="TabbedPanelsContentGroup"> <div class="TabbedPanelsContent">Tab 1 <div class="TabbedPanelsContent">Tab 2 <div class="TabbedPanelsContent">Tab 3 <div class="TabbedPanelsContent">Tab 4 </div> </div>

Content</div> Content</div> Content</div> Content</div>

Insérez le contenu entre les balises TabbedPanelsContent d'ouverture et de fermeture. Par exemple, Tab 1 Content, comme dans l'exemple précédent.. Le contenu peut être n'importe quel code HTML, y compris des éléments de formulaire HTML. 8 Pour initialiser l'objet Panneaux à onglet Spry, insérez le bloc script suivant après le code HTML du widget Panneaux à onglet : <div id="TabbedPanels1" class="TabbedPanels"> . . . </div> <script type="text/javascript"> var TabbedPanels1 = new Spry.Widget.TabbedPanels("TabbedPanels1"); </script>

L'opérateur JavaScript new initialise l'objet widget Panneaux à onglet et transforme le contenu div possédant l'ID TabbedPanels1, qui était un code HTML statique, en un objet Panneaux à onglet interactif. La méthode Spry.Widget.TabbedPanels est un constructeur du cadre applicatif Spry qui crée des objets Panneaux à onglet. Les informations requises pour l'initialisation de l'objet figurent dans la bibliothèque JavaScript SpryTabbedPanels.js que vous avez liée au début de cette procédure. Assurez-vous que l'ID de la balise div du panneau à onglet corresponde au paramètre ID spécifié dans la méthode Spry.Widgets.TabbedPanels. Assurez-vous que l'appel JavaScript se trouve bien après le code HTML du widget. 9 Enregistrez la page. Le code complet ressemble à ce qui suit :


SPRY 26 Guide de l'utilisateur

<head> . . . <link href="SpryAssets/SpryTabbedPanels.css" rel="stylesheet" type="text/css" /> <script src="SpryAssets/SpryTabbedPanels.js" type="text/javascript"></script> </head> <body> <div class="TabbedPanels" id="TabbedPanels1"> <ul class="TabbedPanelsTabGroup"> <li class="TabbedPanelsTab">Tab 1</li> <li class="TabbedPanelsTab">Tab 2</li> <li class="TabbedPanelsTab">Tab 3</li> <li class="TabbedPanelsTab">Tab 4</li> </ul> <div class="TabbedPanelsContentGroup"> <div class="TabbedPanelsContent">Tab 1 Content</div> <div class="TabbedPanelsContent">Tab 2 Content</div> <div class="TabbedPanelsContent">Tab 3 Content</div> <div class="TabbedPanelsContent">Tab 4 Content</div> </div> </div> <script type="text/javascript"> var TabbedPanels1 = new Spry.Widget.TabbedPanels("TabbedPanels1"); </script> </body></body>

Ajout d'un panneau à un widget Panneaux à onglet ❖ Ajoutez une balise li class="TabbedPanelsTab" à la liste d'onglets ul, ainsi qu'une balise div class="TabbedPanelsContent" à la balise conteneur div du contenu des panneaux. Lorsque vous ajoutez le code, n'oubliez

pas d'ajouter les balises /li et /div de fermeture. Par exemple : <div class="TabbedPanels" id="TabbedPanels1"> <ul class="TabbedPanelsTabGroup"> <li class="TabbedPanelsTab">Tab 1</li> <li class="TabbedPanelsTab">Tab 2</li> </ul> <div class="TabbedPanelsContentGroup"> <div class="TabbedPanelsContent">Tab 1 Content</div> <div class="TabbedPanelsContent">Tab 2 Content</div> </div> </div>

Vous pouvez ajouter autant de panneaux que vous le souhaitez. Le rapport entre le nombre d'éléments TabbedPanelsTabli et le nombre de balises TabbedPanelsContentdiv doit toujours être de un pour un.

Suppression d'un panneau d'un widget Panneaux à onglet ❖ Supprimez la balise li class="TabbedPanelsTab" désirée et la balise <div class="TabbedPanelsContent">

correspondante du code. Lorsque vous supprimez le code, n'oubliez pas de supprimer les balises </li> et </div> de fermeture.

Activation de la navigation au clavier Il importe que chaque widget soit rendu accessible pour la navigation au clavier. La navigation au clavier permet à l'utilisateur de contrôler le widget à l'aide des touches fléchées ou de touches personnalisées. La base de la navigation au clavier consiste en l'attribut tabIndex. Cet attribut indique au navigateur comment utiliser les tabulations pour naviguer dans le document. ❖ Pour permettre la navigation au clavier dans les panneaux à onglet, ajoutez une valeur TabIndex à chaque balise li, comme suit :


SPRY 27 Guide de l'utilisateur

<ul class="TabbedPanelsTabGroup"> <li class="TabbedPanelTab" tabIndex="0">Tab</li> <li class="TabbedPanelTab" tabIndex="0">Tab</li> </ul>

Si l'attribut tabIndex possède la valeur zéro (0), c'est le navigateur qui détermine l'ordre. Si l'attribut possède une valeur entière positive, c'est cette valeur qui détermine l'ordre. Remarque : L'application de tabIndex à une balise div n'est pas conforme à la norme XHTML 1.0.

Modification de l'orientation de panneaux à onglet Par défaut, les panneaux à onglet s'affichent à l'horizontale. Vous pouvez toutefois créer aisément des panneaux à onglet verticaux. ❖ Pour transformer un widget Panneaux à onglet horizontal en panneau vertical, remplacez TabbedPanels par VTabbedPanels dans la classe de la balise conteneur div principale, comme suit : <div class="VTabbedPanels" id="TabbedPanels1"> <ul class="TabbedPanelsTabGroup"> <li class="TabbedPanelsTab">Tab 1</li> <li class="TabbedPanelsTab">Tab 2</li> . . . </div>

Définition du panneau ouvert par défaut Vous pouvez stipuler qu'un panneau précis sera ouvert lorsque la page contenant le widget Panneaux à onglet est chargée dans un navigateur. ❖ Définissez l'option defaultTab dans le constructeur de la manière suivante : <script type="text/javascript"> var TabbedPanels1 = new Spry.Widget.TabbedPanels("TabbedPanels1", { defaultTab: 2 }); </script>

Remarque : Le widget Panneaux à onglet emploie un système de comptage en base zéro. Si la valeur est fixée à 2, c'est dès lors le troisième panneau à onglet qui s'ouvre.

Ouverture de panneaux par voie de programmation Vous pouvez utiliser des fonctions JavaScript pour ouvrir des panneaux précis par voie de programmation. Par exemple, vous pouvez placer sur votre page un bouton qui ouvre un panneau à onglet précis lorsque l'utilisateur clique dessus. N'oubliez pas que Spry emploie un système de comptage en base zéro, si bien que 0 représente le premier panneau à onglet, à l'extrême gauche. Si le panneau à onglet possède un ID, vous pouvez également faire référence au panneau à l'aide de cet ID. ❖ Utilisez les fonctions suivantes pour ouvrir des panneaux à onglet précis : <button onclick="TabbedPanels1.showPanel(0)" >open first panel</button> <button onclick="TabbedPanels1.showPanel('tabID')">open panel</button> <script type="text/javascript"> var TabbedPanels1 = new Spry.Widget.TabbedPanels("TabbedPanels1"); </script>

Personnalisation du widget Panneaux à onglet Le fichier SpryTabbedPanels.css fournit le style par défaut du widget Panneaux à onglet. Vous pouvez toutefois personnaliser aisément ce widget en modifiant la règle CSS appropriée. Les règles CSS du fichier SpryTabbedPanels.css utilisent les mêmes noms de classes que les éléments apparentés dans le code HTML du panneau à onglet. Vous pouvez ainsi déterminer aisément quelles règles correspondent aux différentes sections du widget Panneaux à onglet. En outre, le fichier SpryTabbedPanels.css contient des noms de classes pour les comportements associés au widget (par exemple, les comportements relatifs au survol du pointeur de souris et au clic).


SPRY 28 Guide de l'utilisateur

Le fichier SpryTabbedPanels.css doit déjà être placé sur votre site Web avant que vous entamiez des activités de personnalisation. Pour plus d'informations, consultez la section « Préparation des fichiers » à la page 3. Remarque : Internet Explorer, jusqu'à sa version 6, ne prend pas en charge les sélecteurs contextuels d'apparentement et d'enfants (par exemple .TabbedPanels + .TabbedPanels ou .TabbedPanels > .TabbedPanels). Définition du style du widget Panneaux à onglet (instructions générales)

Vous pouvez définir des propriétés pour le conteneur du widget Panneaux à onglet entier ou en définir pour des composants spécifiques du widget. 1 Ouvrez le fichier SpryTabbedPanels.css. 2 Accédez à la règle CSS pour la partie du panneau à onglet à modifier. Par exemple, pour modifier la couleur d'arrièreplan des onglets des panneaux à onglet, modifiez la règle TabbedPanelsTab dans le fichier CSS. 3 Apportez les modifications désirées à la règle CSS puis enregistrez le fichier. Vous pouvez remplacer les noms de classes relatives au style, dans le fichier SpryTabbed Panels.css et dans le code HTML, par les noms de classes de votre choix. Vous n'influerez en rien sur les fonctionnalités du widget. Le fichier SpryTabbed Panels.css contient de nombreux commentaires qui expliquent le code et le rôle de certaines règles. Pour plus d'informations, consultez les commentaires dans le fichier. Définition du style du texte d'un widget Panneaux à onglet

Vous pouvez définir des propriétés pour le conteneur du widget Panneaux à onglet entier ou en définir pour des composants spécifiques du widget. ❖ Recherchez la règle CSS appropriée en vous aidant du tableau suivant, puis ajoutez ou modifiez les propriétés et les valeurs de mise en forme de texte. Texte à modifier

Règle CSS pertinente

Exemple de propriétés et de valeurs à ajouter

Texte dans le widget entier

.TabbedPanels

font: Arial; font-size:medium;

Texte dans les onglets du panneau uniquement

.TabbedPanelsTabGroup ou .TabbedPanelsTab

font: Arial; font-size:medium;

Texte dans les panneaux de contenu uniquement

.TabbedPanelsContentGroup ou .TabbedPanelsContent

font: Arial; font-size:medium;

Modification des couleurs d'arrière-plan du widget Panneaux à onglet ❖ Recherchez la règle CSS appropriée en vous aidant du tableau suivant, puis ajoutez ou modifiez les propriétés et les valeurs de couleur d'arrière-plan. Couleur à modifier

Règle CSS pertinente

Exemple de propriété et de valeur à ajouter ou modifier

Couleur d'arrière-plan des onglets du panneau

.TabbedPanelsTabGroup ou .TabbedPanelsTab

background-color: #DDD; (Valeur par défaut)

Couleur d'arrière-plan des panneaux de .Tabbed PanelsContentGroup ou contenu .TabbedPanelsContent

background-color: #EEE; (Valeur par défaut)

Couleur d'arrière-plan de l'onglet sélectionné

.TabbedPanelsTabSelected

background-color: #EEE; (Valeur par défaut)

Couleur d'arrière-plan des onglets du panneau ouvert lorsque le pointeur de la souris passe au-dessus de ceux-ci

.TabbedPanelsTabHover

background-color: #CCC; (Valeur par défaut)


SPRY 29 Guide de l'utilisateur

Limitation de la largeur de panneaux à onglet

Par défaut, le widget Panneaux à onglet se développe pour occuper l'espace disponible. Pour limiter la largeur d'un widget Panneaux à onglet, définissez une propriété « width » pour le conteneur. 1 Recherchez la règle CSS TabbedPanels dans le fichier SpryTabbedPanels.css. Cette règle définit les propriétés de l'élément conteneur principal du widget Panneaux à onglet. 2 Ajoutez une propriété et une valeur de largeur (width) à la règle, par exemple width:

300px;.

Modification de la hauteur des panneaux à onglet

Par défaut, la hauteur des panneaux à onglet s'adapte au contenu de ceux-ci. Pour donner une hauteur précise aux panneaux, ajoutez une propriété "height" à la règle TabbedPanelsContent. 1 Recherchez la règle CSS TabbedPanelsContent dans le fichier SpryTabbedPanels.css. 2 Ajoutez une propriété et une valeur "height" à la règle, par exemple height:

300px;.

Modification des comportements des panneaux à onglet

Le widget Panneaux à onglet comprend quelques comportements prédéfinis. Ces comportements servent à modifier les classes CSS lorsqu'un événement précis se produit. Par exemple, lorsque le pointeur de la souris survole l'onglet d'un panneau à onglet, Spry applique la classe TabbedPanelsTabHover au widget. Ce comportement est similaire à a:hover pour les liens. Les comportements sont vides par défaut. Pour les modifier, ajoutez des propriétés et des valeurs aux règles. 1 Ouvrez le fichier SpryTabbedPanels.css et accédez à la règle CSS correspondant au comportement de panneaux à onglet à modifier. Le widget Panneaux à onglet comprend quatre règles intégrées pour les comportements. Comportement

Description

Activé

Activé en cas de survol de l'onglet du panneau.

.Tabbed PanelsTabFocused

Activé lorsqu'un onglet est activé pour la saisie au clavier.

.Tabbed PanelsTabSelected

Activé sur l'onglet actuellement sélectionné.

.TabbedPanelsContentVisible

Activé sur la zone de contenu de l'onglet actuellement sélectionné.

Vous trouverez des exemples dans le fichier d'exemple Tabbed Panels qui se trouve dans le répertoire "samples" du répertoire Spry téléchargé depuis le site Adobe Labs. Pour plus d'informations, consultez la section « Préparation des fichiers » à la page 3. 2 Ajoutez des règles CSS aux comportements que vous voulez activer. Remarque : Vous ne pouvez pas remplacer des noms de classes associées à des comportements dans le fichier SpryTabbedPanels.css par des noms de classes de votre choix, car les comportements sont incorporés au cadre applicatif Spry. Pour remplacer la classe par défaut par les noms de votre choix, envoyez les nouvelles valeurs, sous la forme d'arguments, au constructeur des panneaux à onglet. <script type="text/javascript"> var TabbedPanels1 = new Spry.Widget.TabbedPanels("TabbedPanels1", { tabHoverClass: "hover", panelVisibleClass: "open", tabSelectedClass: "selected", tabFocusedClass: "focused" }); </script>


SPRY 30 Guide de l'utilisateur

Utilisation du widget Barre de menus Présentation et structure du widget Barre de menus Un widget Barre de menus est un ensemble de boutons de menu de navigation. Lorsque le pointeur de la souris est placé au-dessus de ces boutons, ils affichent des sous-menus. Les barres de menus permettent d'afficher une grande quantité d'informations de navigation dans un espace compact et de donner aux visiteurs du site un aperçu de son contenu sans les contraindre à l'explorer dans ses moindres recoins. L'exemple suivant montre un widget Barre de menus horizontale, dont le troisième élément de menu est développé.

A

B

Widget Barre de menus (consistant en balises <ul>, <li> et <a>) A. Elément de menu avec sous-menu B. Elément de sous-menu avec sous-menu

Le code HTML du widget Barre de menus comprend une balise ul extérieure contenant une balise li pour chaque élément de menu de niveau supérieur. Les éléments de menu de niveau supérieur (balises li) contiennent à leur tous des balises ul et li qui définissent les sous-menus de chacun d'eux. Ces sous-menus peuvent à leur tour comprendre des sous-menus. Les menus de niveau supérieur et les sous-menus peuvent contenir un nombre illimité d'éléments de sous-menu. Remarque : Il est recommandé d'éviter d'inclure chaque page de votre site dans les différents niveaux d'une barre de menus. Si un visiteur du site a désactivé JavaScript dans son navigateur (ce qui est courant), il ne pourra voir que les éléments de menu supérieurs de la barre de menus. Le code HTML du widget Barre de menus comprend également des balises script dans l'en-tête du document et après le code HTML de la barre de menus. Ces balises créent un objet JavaScript qui rend la barre de menus interactive. Vous pouvez déterminer si le widget Barre de menus est vertical ou horizontal dans la balise conteneur ul principale de la barre de menus. Voici le code HTML d'un widget Barre de menus :


SPRY 31 Guide de l'utilisateur

<head> ... <!--Link the Spry Manu Bar JavaScript library--> <script src="SpryAssets/SpryMenuBar.js" type="text/javascript"></script> <!--Link the CSS style sheet that styles the menu bar. You can select between horizontal and vertical--> <link href="SpryAssets/SpryMenuBarHorizontal.css" rel="stylesheet" type="text/css" /> </head> <body> <!--Create a Menu bar widget and assign classes to each element--> <ul id="menubar1" class="MenuBarHorizontal"> <li><a class="MenuBarItemSubmenu" href="#">Item 1</a> <ul> <li><a href="#">Item 1.1</a></li> <li><a href="#">Item 1.2</a></li> <li><a href="#">Item 1.3</a></li> </ul> </li> <li><a href="#">Item 2</a></li> <li><a class="MenuBarItemSubmenu" href="#">Item 3</a> <ul> <li><a class="MenuBarItemSubmenu" href="#">Item 3.1</a> <ul> <li><a href="#">Item 3.1.1</a></li> <li><a href="#">Item 3.1.2</a></li> </ul> </li> <li><a href="#">Item 3.2</a></li> <li><a href="#">Item 3.3</a></li> </ul> </li> <li><a href="#">Item 4</a></li> </ul> <!--Initialize the Menu Bar widget object--> <script type="text/javascript"> var menubar1 = new Spry.Widget.MenuBar("menubar1", {imgDown:"SpryAssets/SpryMenuBarDownHover.gif", imgRight:"SpryAssets/SpryMenuBarRightHover.gif"}); </script> </body>

Dans le code, l'opérateur JavaScript new initialise l'objet widget Barre de menus et transforme le contenu ul possédant l'ID menubar1, qui était un code HTML statique, en un élément de page interactif. La méthode Spry.Widget.MenuBar est un constructeur du cadre applicatif Spry qui crée des objets Barre de menus. Les informations nécessaires pour initialiser l'objet figurent dans la bibliothèque JavaScript MenuBar.js que vous avez liée dans l'en-tête du document. De nombreuses balises a qui créent le widget contiennent une classe CSS. Ces classes déterminent le style du widget Barre de menus. Elles se trouvent dans le fichier CSS qui l'accompagne (SpryMenuBarHorizontal.css ou SpryMenuBarVertical.css, en fonction de votre sélection). Vous pouvez modifier l'apparence de n'importe quelle partie du widget Barre de menus en modifiant la règle CSS qui correspond aux noms des classes qui lui sont attribués dans le code HTML. Par exemple, pour modifier la couleur d'arrièreplan des éléments de menu de niveau supérieur, modifiez la règle CSS correspondante dans le fichier CSS. N'oubliez pas que la modification du code CSS dans le fichier SpryManuBarHorizontal.css influera sur toutes les barres de menus liés à ce fichier. Outre les classes figurant dans le code HTML, le widget Barre de menus comprend des comportements par défaut qui sont associés au widget. Ces comportements font partie intégrante du cadre applicatif Spry et se trouvent dans le fichier de bibliothèque JavaScript SpryMenuBar.js. Le fichier de bibliothèque contient des comportements relatifs au survol par le pointeur de souris. Vous pouvez modifier l'apparence de la barre de menus, par rapport à ces comportements, en modifiant les classes appropriées dans l'un des fichiers CSS. Si vous souhaitez, à un moment donné, supprimer un comportement, vous pouvez supprimer les règles CSS qui y correspondent.


SPRY 32 Guide de l'utilisateur

Code CSS du widget Barre de menus Les fichiers SpryMenuBarHorizontal.css et SpryMenuBarVertical.css contient les règles qui définissent le style du widget Barre de menus. Vous pouvez modifier ces règles afin de modifier l'apparence et le fonctionnement de la barre de menus. Les noms des règles dans le fichier CSS correspondent directement aux noms des classes définies dans le code HTML du widget Barre de menus. Remarque : Vous pouvez remplacer les noms de classes relatives au style, dans les fichiers SpryMenuBarHorizontal.css et SpryMenuBarVertical.css ainsi que dans le code HTML, par vos propres noms de classes. Vous n'influerez en rien sur les fonctionnalités du widget, car le code CSS n'est pas requis pour celles-ci. Les fonctionnalités par défaut des classes des comportements, à la fin de la feuille de style, sont définies dans le fichier de bibliothèque JavaScript SpryMenuBar.js. Vous pouvez modifier les fonctionnalités par défaut en ajoutant des propriétés et des valeurs aux règles de comportement de la feuille de style. Le code CSS du fichier SpryMenuBarHorizontal.css est le suivant : /*Menu Bar styling classes*/ ul.MenuBarHorizontal{ margin: 0; padding: 0; list-style-type: none; font-size: 100%; cursor: default; width: auto; } ul.MenuBarActive{ z-index: 1000; } ul.MenuBarHorizontal li{ margin: 0; padding: 0; list-style-type: none; font-size: 100%; position: relative; text-align: left; cursor: pointer; width: 8em; float: left; } ul.MenuBarHorizontal ul{ margin: 0; padding: 0; list-style-type: none; font-size: 100%; z-index: 1020; cursor: default; width: 8.2em; position: absolute; left: -1000em; } ul.MenuBarHorizontal ul.MenuBarSubmenuVisible{ left: auto; } ul.MenuBarHorizontal ul li{ width: 8.2em; } ul.MenuBarHorizontal ul ul{ position: absolute; margin: -5% 0 0 95%; } ul.MenuBarHorizontal ul.MenuBarSubmenuVisible ul.MenuBarSubmenuVisible{ left: auto; top: 0; } ul.MenuBarHorizontal ul{


SPRY 33 Guide de l'utilisateur

border: 1px solid #CCC; } ul.MenuBarHorizontal a{ display: block; cursor: pointer; background-color: #EEE; padding: 0.5em 0.75em; color: #333; text-decoration: none; } ul.MenuBarHorizontal a:hover, ul.MenuBarHorizontal a:focus{ background-color: #33C; color: #FFF; } ul.MenuBarHorizontal a.MenuBarItemHover, ul.MenuBarHorizontal a.MenuBarItemSubmenuHover, ul.MenuBarHorizontal a.MenuBarSubmenuVisible{ background-color: #33C; color: #FFF; } ul.MenuBarHorizontal a.MenuBarItemSubmenu{ background-image: url(SpryMenuBarDown.gif); background-repeat: no-repeat; background-position: 95% 50%; } ul.MenuBarHorizontal ul a.MenuBarItemSubmenu{ background-image: url(SpryMenuBarRight.gif); background-repeat: no-repeat; background-position: 95% 50%; } ul.MenuBarHorizontal a.MenuBarItemSubmenuHover{ background-image: url(SpryMenuBarDownHover.gif); background-repeat: no-repeat; background-position: 95% 50%; } ul.MenuBarHorizontal ul a.MenuBarItemSubmenuHover{ background-image: url(SpryMenuBarRightHover.gif); background-repeat: no-repeat; background-position: 95% 50%; } ul.MenuBarHorizontal iframe{ position: absolute; z-index: 1010; } @media screen, projection{ ul.MenuBarHorizontal li.MenuBarItemIE{ display: inline; f\loat: left; background: #FFF; } }

Le fichier SpryMenuBar.css contient de nombreux commentaires qui expliquent le code et le rôle de certaines règles. Pour plus d'informations, consultez les commentaires dans le fichier.

Insertion du widget Barre de menus 1 Recherchez le fichier SpryMenuBar.css et ajoutez-le à votre site Web. Le fichier SpryMenuBar.js se trouve dans le répertoire widgets/menubar qui figure dans le répertoire Spry téléchargé depuis le site Adobe Labs. Pour plus d'informations, consultez la section « Préparation des fichiers » à la page 3. Par exemple, créez un dossier nommé SpryAssets dans le dossier racine de votre site Web, puis déplacez-y le fichier SpryMenuBar.js. Le fichier SpryMenuBar.js contient toutes les informations qui rendent le widget Barre de menus interactif.


SPRY 34 Guide de l'utilisateur

2 Recherchez le fichier SpryMenuBarHorizontal.css ou SpryMenuBarVertical.css (selon le type de barre de menus que vous voulez créer) et ajoutez-le à votre site Web. Vous pouvez l'ajouter dans le répertoire principal, dans un répertoire SpryAssets ou dans un répertoire CSS, si vous en avez créé un. 3 Ouvrez la page Web à laquelle ajouter le widget Barre de menus et liez le fichier SpryMenuBar.js à la page en insérant la balise script suivante dans la balise "head" de la page : <script src="SpryAssets/SpryMenuBar.js" type="text/javascript"></script>

Assurez-vous que le chemin d'accès au fichier SpryMenuBar.js est bien correct. Ce chemin d'accès varie selon l'endroit où vous avez placé le fichier dans votre site Web. 4 Liez le fichier SpryMenuBarHorizontal.css ou SpryMenuBarVertical.css à votre page Web en insérant la balise link suivante dans la balise "head" de la page : <link href="SpryAssets/SpryMenuBarHorizontal.css" rel="stylesheet" type="text/css" />

Assurez-vous que le chemin d'accès au fichier SpryMenuBarHorizontal.css ou SpryMenuBarVertical.css est bien correct. Ce chemin d'accès varie selon l'endroit où vous avez placé le fichier dans votre site Web. 5 Ajoutez le code HTML de la barre de menus à votre page Web en insérant une balise conteneur ul, puis des balisesli contenant du texte pour chaque élément de menu supérieur de la barre de menus, comme suit : <body> <ul> <li>Item <li>Item <li>Item <li>Item </ul> </body>

1</li> 2</li> 3</li> 4</li>

6 Entourez le texte des balises li à l'aide de balises a : <body> <ul> <li><a <li><a <li><a <li><a </ul> </body>

href="#">Item href="#">Item href="#">Item href="#">Item

1</a></li> 2</a></li> 3</a></li> 4</a></li>

7 Imbriquez une autre liste simple (avec des balises a) dans le troisième élément de menu (ou tout autre élément de menu), comme suit : <body> <ul> <li><a href="#">Item 1</a></li> <li><a href="#">Item 2</a></li> <li><a href="#">Item 3</a> <ul> <li><a href="#">Submenu Item 1</a></li> <li><a href="#">Submenu Item 2</a></li> </ul> </li> <li><a href="#">Item 4</a></li> </ul> </body>

Cette liste simple imbriquée sera le sous-menu du troisième élément de menu. Assurez-vous que la liste imbriquée ne se trouve pas à l'intérieur de la balise a de l'élément de menu supérieur. 8 Ajoutez un ID unique qui identifie le conteneur de la barre de menus (balise ul), comme suit :


SPRY 35 Guide de l'utilisateur

<body> <ul id="menubar1"> <li><a href="#">Item 1</a></li> <li><a href="#">Item 2</a></li> <li><a href="#">Item 3</a> <ul> <li><a href="#">Submenu Item 1</a></li> <li><a href="#">Submenu Item 2</a></li> </ul> </li> <li><a href="#">Item 4</a></li> </ul> </body>

Vous pourrez par la suite utiliser cet ID pour identifier le conteneur dans le constructeur du widget. 9 Pour ajouter une mise en forme à la barre de menus, ajoutez les classes appropriées, comme suit : <body> <ul id="menubar1" class="MenuBarHorizontal"> <li><a href="#">Item 1</a></li> <li><a href="#">Item 2</a></li> <li><a href="#" class="MenuBarItemSubmenu">Item 3</a> <ul> <li><a href="#">Submenu Item 1</a></li> <li><a href="#">Submenu Item 2</a></li> </ul> </li> <li><a href="#">Item 4</a></li> </ul> </body>

Déterminez si vous créez une barre de menus horizontale ou verticale. Attribuez la classe MenuBarItemSubmenu aux balises a si les éléments de menu supérieur comportent des sous-menus. Cette classe affiche l'image d'une flèche vers le bas qui signale l'existence d'un sous-menu à l'utilisateur. 10 Pour initialiser l'objet Barre de menus Spry, insérez le bloc script suivant après le code HTML du widget Barre de menus : <ul id="menubar1" class="MenuBarHorizontal"> . . . </ul> <script type="text/javascript"> var menubar1 = new Spry.Widget.MenuBar("menubar1"); </script>

L'opérateur JavaScript new initialise l'objet widget Barre de menus et transforme le contenu ul possédant l'ID menubar1, qui était un code HTML statique, en un objet Barre de menus interactif. La méthode Spry.Widget.MenuBar est un constructeur du cadre applicatif Spry qui crée des objets Barre de menus. Les informations requises pour l'initialisation de l'objet figurent dans la bibliothèque JavaScript SpryMenuBar.js que vous avez liée au début de cette procédure. Assurez-vous que l'ID de la balise url de la barre de menus corresponde au paramètre ID spécifié dans la méthode Spry.Widgets.MenuBar. Assurez-vous que l'appel JavaScript se trouve bien après le code HTML du widget.

11 Enregistrez la page. Le code complet ressemble à ce qui suit :


SPRY 36 Guide de l'utilisateur

<head> ... <script src="SpryAssets/SpryMenuBar.js" type="text/javascript"></script> <link href="SpryAssets/SpryMenuBarHorizontal.css" rel="stylesheet" type="text/css" /> </head> <body> <ul id="menubar1" class="MenuBarHorizontal"> <li><a href="#">Item 1</a></li> <li><a href="#">Item 2</a></li> <li><a href="#" class="MenuBarItemSubmenu">Item 3</a> <ul> <li><a href="#">Submenu Item 1</a></li> <li><a href="#">Submenu Item 2</a></li> </ul> </li> <li><a href="#">Item 4</a></li> </ul> <script type="text/javascript"> var menubar1 = new Spry.Widget.MenuBar("menubar1"); </script> </body>

Remarque : Le widget Barre de menus Spry emploie des calques DHTML pour afficher des sections de code HTML au-dessus d'autres sections. Si votre page comporte du contenu Flash, un problème peut se poser. Les animations Flash sont en effet toujours affichées au-dessus de tous les autres calques DHTML, si bien qu'il se peut que le contenu Flash s'affiche au-dessus de vos sous-menus. La solution à ce problème consiste à modifier les paramètres du contenu Flash, de manière à employer wmode="transparent". Pour plus d'informations, consultez le site www.adobe.com/go/15523_fr.

Ajout ou suppression de menus et de sous-menus Ajout d'un élément de menu principal ❖ Pour ajouter un élément de menu principal, ajoutez un nouvel élément de liste (balise li tag) à la balise conteneur ul.

Par exemple : <ul id="menubar1" class="MenuBarHorizontal"> <li><a href="#">Item 1</a></li> <li><a href="#">Item 2</a></li> <li><a href="#" class="MenuBarItemSubmenu">Item 3</a> <ul> <li><a href="#">Submenu Item 1</a></li> <li><a href="#">Submenu Item 2</a></li> </ul> </li> <li><a href="#">Item 4</a></li> <li><a href="#">Item 5--NEW MENU ITEM</a></li> </ul>

Ajout d'un élément de sous-menu ❖ Pour ajouter un élément de sous-menu, ajoutez un nouvel élément de liste (balise li tag) à la balise ul de sous-menu. Par

exemple : <ul id="menubar1" class="MenuBarHorizontal"> <li><a href="#">Item 1</a></li> <li><a href="#">Item 2</a></li> <li><a href="#" class="MenuBarItemSubmenu">Item 3</a> <ul> <li><a href="#">Submenu Item 1</a></li> <li><a href="#">Submenu Item 2</a></li> <li><a href="#">Submenu Item 3--NEW SUBMENU ITEM</a></li> </ul> </li> <li><a href="#">Item 4</a></li> </ul>


SPRY 37 Guide de l'utilisateur

Suppression d'un élément de menu principal ou de sous-menu ❖ Supprimez la balise li pour l'élément de menu ou de sous-menu que vous voulez supprimer.

Création d'une infobulle pour un élément de menu ❖ Pour créer une infobulle pour un élément de menu, ajoutez un attribut title à la balise a de l'élément en question. Par

exemple : <ul id="menubar1" class="MenuBarHorizontal"> <li><a href="#">Item 1</a></li> <li><a href="#">Item 2</a></li> <li><a href="#">Item 3</a></li> <li><a href="contacts.html" title="Contacts">Item 4</a></li> </ul>

Préchargement des images ❖ Pour précharger les images utilisées pour les flèches vers le bas et la droite du sous-menu, ajoutez l'option imgDown, l'option imgRight ou les deux au constructeur du widget, comme suit : <script type="text/javascript"> var menubar1 = new Spry.Widget.MenuBar("menubar1", {imgDown:"SpryAssets/SpryMenuBarDownHover.gif", imgRight:"SpryAssets/SpryMenuBarRightHover.gif"}); </script>

Ajoutez le chemin d'accès à l'image comme valeur de l'option. Ce chemin varie selon l'endroit où vous stockez les images.

Modification de l'orientation d'un widget Barre de menus Vous pouvez modifier l'orientation d'un widget Barre de menus, de manière à transformer une barre horizontale en barre verticale et inversement. Il vous suffit de modifier le code HTML de la barre de menus et de vérifier que votre site Web contient bien le fichier CSS correct. La procédure suivante transforme un widget Barre de menus horizontale en widget Barre de menus verticale. 1 Assurez-vous que le fichier SpryMenuBarVertical.css se trouve bien dans votre site Web. Par exemple, vous pouvez stocker ce fichier dans un dossier SpryAssets dans le site. 2 Remplacez le lien vers le fichier SpryMenuBarHorizontal.css par un lien vers le fichier SpryMenuBarVertical.css dans l'en-tête de votre document, comme suit : <link href="SpryAssets/SpryMenuBarVertical.css" rel="stylesheet" type="text/css" />

3 Recherchez la classe MenuBarHorizontal dans le code HTML de la barre de menus horizontale, et remplacez-la par MenuBarVertical. La classe MenuBarHorizontal est définie dans la balise conteneur ul de la barre de menus (<ul id="menubar1" class="MenuBarHorizontal">). 4 Après le code de la barre de menus, accédez au constructeur de la barre : var menubar1 = new Spry.Widget.MenuBar("menubar1", {imgDown:"SpryAssets/SpryMenuBarDownHover.gif", imgRight:"SpryAssets/SpryMenuBarRightHover.gif"});

5 Supprimez l'option de préchargement imgDown (et la virgule) du constructeur : var menubar1 = new Spry.Widget.MenuBar("menubar1", {imgRight:"SpryAssets/SpryMenuBarRightHover.gif"});

Remarque : Si vous convertissez une barre de menus verticale en barre horizontale, vous devez au contraire ajouter l'option de préchargement imgDown et la virgule. 6 (Facultatif) Si votre page ne comprend plus d'autres widgets Barre de menus horizontale, supprimez le lien vers l'ancien fichier MenuBarHorizontal.css dans l'en-tête du document. 7 Enregistrez la page.


SPRY 38 Guide de l'utilisateur

Personnalisation du widget Barre de menus Les fichiers SpryMenuBarHorizontal.css et SpryMenuBarVertical.css fournissent le style par défaut du widget Barre de menus. Vous pouvez toutefois personnaliser ce widget en modifiant la règle CSS appropriée. Les règles CSS des fichiers SpryMenuBarHorizontal.css et SpryMenuBarVertical.css utilisent les mêmes noms de classes que les éléments apparentés dans le code HTML de la barre de menus. Vous pouvez ainsi déterminer aisément quelles règles correspondent aux différentes sections du widget Barre de menus. En outre, les fichiers SpryMenuBarHorizontal.css et SpryMenuBarVertical.css contiennent des noms de classes pour les comportements associés au widget (par exemple, les comportements relatifs au survol du pointeur de souris et au clic). La feuille de style horizontale ou verticale du widget doit déjà être placée sur votre site Web avant que vous entamiez des activités de personnalisation. Pour plus d'informations, consultez la section « Préparation des fichiers » à la page 3. Définition du style du widget Barre de menus (instructions générales)

Vous pouvez définir le style du texte d'un widget Barre de menus en définissant des propriétés pour le conteneur entier du widget Barre de menus, ou en définissant des propriétés distinctes pour chaque composant du widget. 1 Ouvrez le fichier SpryMenuBarHorizontal.css ou SpryMenuBarVertical.css. 2 Accédez à la règle CSS pour la partie de la barre de menus à modifier. Par exemple, pour modifier la couleur d'arrièreplan des éléments de menu de niveau supérieur, modifiez la règle ulMenuBarHorizontal a ou ulMenuBarVertical a dans le fichier CSS. 3 Apportez les modifications désirées au code CSS puis enregistrez le fichier. Vous pouvez remplacer les noms de classes relatives au style, dans les fichiers CSS et dans le code HTML, par les noms de classes de votre choix. Vous n'influerez en rien sur les fonctionnalités du widget. Les fichiers SpryMenuBarHorizontal.css et SpryMenuBarVertical.css contiennent de nombreux commentaires qui expliquent le code et le rôle de certaines règles. Pour plus d'informations, consultez les commentaires dans le fichier. Modification du style du texte d'un élément de menu

Le code CSS joint à la balise a contient les informations de style du texte. La balise a comprend également plusieurs valeurs de classe de style de texte pertinentes qui concernent différents états des menus. ❖ Pour modifier le style du texte d'un élément de menu, recherchez la règle CSS appropriée dans le tableau suivant, puis modifiez sa valeur par défaut. Style à modifier

Règle CSS pour une barre de menus verticale ou horizontale

Propriétés correspondantes et valeurs par défaut

Texte par défaut

ul.MenuBarVertical a, ul.MenuBarHorizontal a

color: #333; text-decoration: none;

Couleur du texte lorsque le pointeur de ul.MenuBarVertical a:hover, la souris se trouve au-dessus de celui-ci ul.MenuBarHorizontal a:hover

color: #FFF;

Couleur du texte actif

ul.MenuBarVertical a:focus, ul.MenuBarHorizontal a:focus

color: #FFF;

Couleur d'un élément de la barre de menus lorsque le pointeur de la souris se trouve au-dessus de celui-ci

ul.MenuBarVertical a.MenuBarItemHover, ul.MenuBarHorizontal a.MenuBarItemHover

color: #FFF;

Couleur d'un élément de sous-menu lorsque le pointeur de la souris se trouve au-dessus de celui-ci

ul.MenuBarVertical a.MenuBarItemSubmenuHover, ul.MenuBarHorizontal a.MenuBarItemSubmenuHover

color: #FFF;


SPRY 39 Guide de l'utilisateur

Modification de la couleur d'arrière-plan d'un élément de menu

La règle CSS jointe à la balise a contient les informations de couleur d'arrière-plan d'un élément de menu. La balise a comprend également plusieurs valeurs de classe de couleur d'arrière-plan pertinentes qui concernent différents états des menus. ❖ Pour modifier la couleur d'arrière-plan d'un élément de menu, recherchez la règle CSS appropriée dans le tableau suivant, puis modifiez sa valeur par défaut. Couleur à modifier

Règle CSS pour une barre de menus verticale ou horizontale

Propriétés correspondantes et valeurs par défaut

Arrière-plan par défaut

ul.MenuBarVertical a, ul.MenuBarHorizontal a

background-color: #EEE;

Couleur d'arrière-plan de l'élément lorsque le pointeur de la souris se trouve au-dessus de celui-ci

ul.MenuBarVertical a:hover, ul.MenuBarHorizontal a:hover

background-color: #33C;

Couleur d'arrière-plan quand l'élément est actif

ul.MenuBarVertical a:focus, ul.MenuBarHorizontal a:focus

background-color: #33C;

Couleur d'un élément de la barre de menus lorsque le pointeur de la souris se trouve au-dessus de celui-ci

ul.MenuBarVertical a.MenuBarItemHover, ul.MenuBarHorizontal a.MenuBarItemHover

background-color: #33C;

Couleur d'un élément de sous-menu lorsque le pointeur de la souris se trouve au-dessus de celui-ci

ul.MenuBarVertical a.MenuBarItemSubmenuHover, ul.MenuBarHorizontal a.MenuBarItemSubmenuHover

background-color: #33C;

Modification de la taille des éléments de menu

Vous pouvez modifier la taille des éléments de menu en modifiant les propriétés de largeur des balises li et ul de ces éléments. 1 Accédez à la règle ul.MenuBarVertical

li ou ul.MenuBarHorizontal li :

2 Modifiez la propriété "width" afin de lui donner la largeur désirée, ou remplacez sa valeur par auto pour supprimer une largeur fixe, puis ajoutez la propriété et la valeur white-space: nowrap; à la règle. 3 Accédez à la règle ul.MenuBarVertical

ul ou ul.MenuBarHorizontal ul.

4 Modifiez la propriété « width » afin de lui donner la largeur désirée (ou remplacez sa valeur par auto pour supprimer une largeur fixe). 5 Accédez à la règle ul.MenuBarVertical

ul li ou ul.MenuBarHorizontal ul li.

6 Ajoutez les propriétés suivantes à la règle : float: 7 Supprimez la propriété width:

none; et background-color: transparent;.

8.2em; et sa valeur.

Définition de la position des sous-menus

La position des sous-menus d'une barre de menus Spry est contrôlée par la propriété « margin » des balises ul du sous-menu. 1 Accédez à la règle ul.MenuBarVertical

ul ou ul.MenuBarHorizontal ul.

2 Remplacez les valeurs par défaut margin:

-5% 0 0 95%; par les valeurs désirées.


SPRY 40 Guide de l'utilisateur

Utilisation du widget Champ de texte de validation Présentation et structure du widget Champ de texte de validation Le widget Validation Spry de champ de texte est un champ de texte qui affiche des états valides ou non valides lorsque le visiteur du site entre du texte. Par exemple, vous pouvez ajouter un widget Validation de zone de texte à un formulaire dans lequel le visiteur doit entrer son adresse électronique. Si l'utilisateur ne tape pas le signe @ et un point (.) dans l'adresse, le widget affiche un message qui indique que les informations entrées ne sont pas valides. L'exemple suivant montre un widget Validation de zone de texte dans différents états : A

B

C

D

A. Widget Champ de texte, conseil activé B. Widget Champ de texte, état valide C. Widget Champ de texte, état non valide D. Widget Champ de texte, état obligatoire

Le widget Champ de texte de validation peut posséder divers états (par exemple valide, non valide, valeur obligatoire, etc.). Vous pouvez modifier les propriétés de ces états en modifiant le fichier CSS correspondant (SpryValidationTextField.css), en fonction des résultats de validation désirés. Un widget Champ de texte de validation peut effectuer une validation à différents moments, par exemple lorsque le visiteur clique en dehors du widget, pendant qu'il entre des données ou lorsqu'il tente d'envoyer le formulaire. Etat initial Lorsque la page se charge dans le navigateur, ou lorsque l'utilisateur réinitialise le formulaire. Etat actif Lorsque l'utilisateur place le point d'insertion à l'intérieur du widget. Etat valide Lorsque l'utilisateur a entré des informations correctes, ce qui permet l'envoi du formulaire. Etat non valide Si l'utilisateur a entré du texte dans un format non valide. Par exemple, 06 pour l'année au lieu de 2006. Etat obligatoire Lorsque l'utilisateur n'a pas entré du texte obligatoire dans le champ de texte. Nombre minimal de caractères Lorsque l'utilisateur a entré moins de caractères que le nombre minimal requis pour le

champ de texte. Nombre maximal de caractères Lorsque l'utilisateur a entré plus de caractères que le nombre maximal admis pour le champ

de texte. Valeur minimale Lorsque l'utilisateur a entré une valeur inférieure à la valeur requise par le champ de texte. S'applique aux

validations de type entier, réel et date. Valeur maximale Lorsque l'utilisateur a entré une valeur supérieure à la valeur maximale admise par le champ de texte. S'applique aux validations de type entier, réel et date.

Lorsqu'un widget Validation de zone de texte passe dans l'un de ces états suite à l'interaction avec l'utilisateur, la logique du cadre applicatif Spry applique une classe CSS spécifique au conteneur HTML pour le widget lors de l'exécution. Par exemple, si un utilisateur tente d'envoyer un formulaire mais n'a pas entré de texte dans un champ obligatoire, Spry applique au widget une classe qui le force à afficher le message d'erreur « Vous devez entrer une valeur » et empêche l'envoi du formulaire. Les règles qui contrôlent le style et les états d'affichage de messages d'erreur se trouvent dans le fichier qui accompagne le widget, SpryValidationTextField.css.


SPRY 41 Guide de l'utilisateur

Le code HTML par défaut du widget Champ de texte de validation, généralement dans un formulaire, contient une balise conteneur span qui entoure la balise input du champ de texte. Le code HTML du widget Champ de texte de validation comprend également des balises script dans l'en-tête du document et après le code HTML du widget. La balise script dans l'en-tête du document définit toutes les fonctions JavaScript relatives au widget Champ de texte. La balise script qui suit le code du widget crée un objet JavaScript qui rend le champ de texte interactif. Voici le code HTML d'un widget Champ de texte de validation : <head> ... <!-- Link the Spry Validation Text Field JavaScript library --> <script src="SpryAssets/SpryValidationTextField.js" type="text/javascript"></script> <!-- Link the CSS style sheet that styles the widget --> <link href="SpryAssets/SpryValidationTextField.css" rel="stylesheet" type="text/css" /> </head> <body> <form id="form1" name="form1" method="post" action=""> <!-- Create the text field widget and assign a unique id--> <span id="sprytextfield1"> <input type="text" name="mytextfield" id="mytextfield" /> <!--Display an error message> <span class="textfieldRequiredMsg">A value is required.</span> </span> </form> <!-- Initialize the Validation Text Field widget object--> <script type="text/javascript"> var sprytextfield1 = new Spry.Widget.ValidationTextField("sprytextfield1"); </script> </body>

Dans le code, l'opérateur JavaScript new initialise l'objet widget Champ de texte et transforme le contenu span possédant l'ID sprytextfield1, qui était un code HTML statique, en un élément de page interactif. La balise span du message d'erreur dans le widget comporte une classe CSS qui y est appliquée. Cette classe (fixée à display:none; par défaut) détermine le style et la visibilité du message d'erreur. Elle se trouve dans le fichier CSS joint, SpryValidationTextField.css. Lorsque le widget passe dans un état différent suite à l'interaction avec l'utilisateur, Spry applique une classe différente au conteneur du widget, ce qui influe sur la classe de message d'erreur. Pour ajouter d'autres messages d'erreur à un widget Champ de texte de validation, créez une balise span (ou tout autre type de balise) qui en contiendra le texte. Ensuite, en lui appliquant une classe CSS, vous pouvez afficher ou masquer le message en fonction de l'état du widget. Vous pouvez ajouter d'autres messages d'erreur à un widget Champ de texte de validation en créant la règle CSS correspondante dans le fichier SpryValidationTextField.css. Par exemple, pour modifier la couleur d'arrière-plan en fonction d'un état, modifiez la règle correspondante ou ajoutez-en une nouvelle (si elle n'existe pas encore) dans la feuille de style. Variation des balises utilisées pour la structure du widget Champ de texte

Dans l'exemple précédent, nous avons utilisé des balises span pour créer la structure du widget : Container SPAN INPUT type="text" Error message SPAN

Il est toutefois possible d'employer à peu près n'importe quelle balise conteneur pour créer un widget : Container DIV INPUT type="text" Error Message P

Spry utilise l'ID de balise (et pas la balise proprement dite) pour créer le widget. Spry affiche également les messages d'erreur à l'aide de code CSS qui ne varie pas selon la balise qui contient les messages en question.


SPRY 42 Guide de l'utilisateur

L'ID transmis au constructeur du widget identifie un élément HTML spécifique. Le constructeur trouve cet élément et recherche, dans le conteneur identifié, la balise input correspondante. Si l'ID transmis au constructeur est l'ID de la balise input (au lieu d'une balise conteneur), le constructeur joint directement des déclencheurs de validation à la balise input. Par contre, si aucune balise conteneur n'est présente, le widget ne peut pas afficher les messages d'erreur. Les divers états de validation se bornent à modifier l'apparence de l'élément de balise input (par exemple sa couleur d'arrière-plan). Remarque : Les balises INPUT multiples ne fonctionnent pas à l'intérieur d'un même conteneur de widget HTML. Chaque champ de texte doit être son propre widget.

Code CSS pour le widget Champ de texte de validation Le fichier SpryValidationTextField.css contient les règles qui définissent le style du widget Champ de texte de validation et de ses messages d'erreur. Vous pouvez modifier ces règles afin de définir l'apparence du widget et des messages d'erreur. Les noms des règles dans le fichier CSS correspondent aux noms des classes définies dans le code HTML du widget. Le code CSS du fichier SpryValidationTextField.css est le suivant : /*Text Field styling classes*/ .textfieldRequiredMsg, .textfieldInvalidFormatMsg, .textfieldMinValueMsg, .textfieldMaxValueMsg, .textfieldMinCharsMsg, .textfieldMaxCharsMsg, .textfieldValidMsg { display: none; } .textfieldRequiredState .textfieldRequiredMsg, .textfieldInvalidFormatState .textfieldInvalidFormatMsg, .textfieldMinValueState .textfieldMinValueMsg, .textfieldMaxValueState .textfieldMaxValueMsg, .textfieldMinCharsState .textfieldMinCharsMsg, .textfieldMaxCharsState .textfieldMaxCharsMsg { display: inline; color: #CC3333; border: 1px solid #CC3333; } .textfieldValidState input, input.textfieldValidState { background-color: #B8F5B1; } input.textfieldRequiredState, .textfieldRequiredState input, input.textfieldInvalidFormatState, .textfieldInvalidFormatState input, input.textfieldMinValueState, .textfieldMinValueState input, input.textfieldMaxValueState, .textfieldMaxValueState input, input.textfieldMinCharsState, .textfieldMinCharsState input, input.textfieldMaxCharsState, .textfieldMaxCharsState input { background-color: #FF9F9F; } .textfieldFocusState input, input.textfieldFocusState { background-color: #FFFFCC; } .textfieldFlashText input, input.textfieldFlashText { color: red !important; }

Le fichier SpryValidationTextField.css contient également de nombreux commentaires qui expliquent le code et le rôle de certaines règles. Pour plus d'informations, consultez les commentaires dans le fichier.

Insertion du widget Validation de zone de texte 1 Recherchez le fichier SpryValidationTextField.css et ajoutez-le à votre site Web. Le fichier SpryValidationTextField.js se trouve dans le répertoire widgets/textfieldvalidation qui figure dans le répertoire Spry téléchargé depuis le site Adobe Labs. Pour plus d'informations, consultez la section « Préparation des fichiers » à la page 3.


SPRY 43 Guide de l'utilisateur

Par exemple, créez un dossier nommé SpryAssets dans le dossier racine de votre site Web, puis déplacez-y le fichier SpryValidationTextField.js. Le fichier SpryValidationTextField.js contient toutes les informations qui rendent le widget Champ de texte interactif. 2 Recherchez le fichier SpryValidationTextField.js et ajoutez-le à votre site Web. Vous pouvez l'ajouter dans le répertoire principal, dans un répertoire SpryAssets ou dans un répertoire CSS, si vous en avez créé un. 3 Ouvrez la page Web à laquelle ajouter le widget Champ de texte puis liez le fichier SpryValidationTextField.js à la page en insérant la balise script suivante dans la balise "head" de la page : <script src="SpryAssets/SpryValidationTextField.js" type="text/javascript"></script>

Assurez-vous que le chemin d'accès au fichier SpryValidationTextField.js est bien correct. Ce chemin d'accès varie selon l'endroit où vous avez placé le fichier dans votre site Web. 4 Liez le fichier SpryValidationTextField.css à votre page Web en insérant la balise link suivante dans la balise "head" de la page : <link href="SpryAssets/SpryValidationTextField.css" rel="stylesheet" type="text/css" />

Assurez-vous que le chemin d'accès au fichier SpryValidationTextField.css est bien correct. Ce chemin d'accès varie selon l'endroit où vous avez placé le fichier dans votre site Web. 5 Ajoutez un champ de texte à la page, puis attribuez-lui un nom et un ID unique : <input type="text" name="mytextfield" id="mytextfield"/>

6 Pour ajouter un conteneur autour du champ de texte, insérez des balises span autour des balises input, puis attribuez un ID unique au widget, comme suit : <span id="sprytextfield1"> <input type="text" name="mytextfield" id="mytextfield"/> </span>

7 Initialisez l'objet Champ de texte en insérant le bloc script suivant après le code HTML du widget : <script type="text/javascript"> var sprytextfield1 = new Spry.Widget.ValidationTextField("sprytextfield1"); </script>

L'opérateur JavaScript new initialise l'objet widget Champ de texte et transforme le contenu span possédant l'ID sprytextfield1, qui était un code HTML statique, en un objet Champ de texte interactif. La méthode Spry.Widget.ValidationTextField est un constructeur du cadre applicatif Spry qui crée des objets Champ de texte. Les informations requises pour l'initialisation de l'objet figurent dans la bibliothèque JavaScript SpryValidationTextField.js que vous avez liée au début de cette procédure. Assurez-vous que l'ID de la balise span du champ de texte corresponde au paramètre ID spécifié dans la méthode Spry.Widgets.ValidationTextField. Assurez-vous que l'appel JavaScript se trouve bien après le code HTML du widget. 8 Enregistrez la page. Le code complet ressemble à ce qui suit : <head> ... <script src="SpryAssets/SpryValidationTextField.js" type="text/javascript"></script> <link href="SpryAssets/SpryValidationTextField.css" rel="stylesheet" type="text/css" /> </head> <body> <span id="sprytextfield1"> <input type="text" name="mytextfield" id="mytextfield" /> </span> <script type="text/javascript"> var sprytextfield1 = new Spry.Widget.ValidationTextField("sprytextfield1"); </script> </body>


SPRY 44 Guide de l'utilisateur

Affichage de messages d'erreur ❖ Créez une balise span (ou tout autre type de balise) pour afficher le message d'erreur, et attribuez-lui la classe appropriée, comme suit : <span id="sprytextfield1"> <input type="text" name="mytextfield" id="mytextfield" /> <span class="textfieldRequiredMsg">Please enter a description</span> </span>

La règle textfieldRequiredMsg se trouve dans le fichier SpryValidationTextField.css et est fixée àdisplay:none par défaut. Lorsque le widget passe dans un état différent suite à l'interaction avec l'utilisateur, Spry applique la classe appropriée (la classe d'état) au conteneur du widget. Cette action influe sur la classe du message d'erreur et, dès lors, sur l'apparence de ce message. Par exemple, voici une partie de la règle CSS du fichier SpryValidationTextField.css : .textfieldRequiredMsg, .textfieldInvalidFormatMsg, .textfieldMinValueMsg, .textfieldMaxValueMsg, .textfieldMinCharsMsg, .textfieldMaxCharsMsg, .textfieldValidMsg { display: none; } .textfieldRequiredState .textfieldRequiredMsg, .textfieldInvalidFormatState .textfieldInvalidFormatMsg, .textfieldMinValueState .textfieldMinValueMsg, .textfieldMaxValueState .textfieldMaxValueMsg, .textfieldMinCharsState .textfieldMinCharsMsg, .textfieldMaxCharsState .textfieldMaxCharsMsg{ display: inline; color: #CC3333; border: 1px solid #CC3333; }

Par défaut, aucune classe d'état n'est appliquée au conteneur du widget. Dès lors, lorsque la page est chargée dans un navigateur, seule la classe textfieldRequiredMsg est appliquée au texte du message d'erreur présenté dans l'exemple de code HTML précédent. La paire propriété/valeur pour cette règle étant display:none, le message reste masqué. Toutefois, si l'utilisateur n'a pas entré de texte dans un champ de texte obligatoire, Spry applique la classe appropriée au conteneur du widget, comme suit : <span id="sprytextfield1" class="textfieldRequiredState"> <input type="text" name="mytextfield" id="mytextfield" /> <span class="textfieldRequiredMsg">Please enter a description</span> </span>

Dans le code CSS précédent, la règle d'état avec le sélecteur contextuel .textfieldRequiredState .textfieldRequiredMsg supplante la règle de message d'erreur par défaut, qui masquait le texte du message. Dès lors, lorsque Spry applique la classe d'état au conteneur du widget, la règle d'état détermine l'apparence du widget et affiche le message d'erreur en ligne, en rouge, encadré d'une bordure pleine de 1 pixel d'épaisseur. La liste suivante présente les classes de messages d'erreur par défaut et leurs descriptions. Vous pouvez modifier ces classes et les renommer. Dans ce cas, n'oubliez pas de les modifier également dans le sélecteur contextuel. Classe de message d'erreur

Description

.textfieldRequiredMsg

Force l'affichage du message d'erreur lorsque le widget accède à l'état "obligatoire".

.textfieldInvalidFormatMsg

Force l'affichage du message d'erreur lorsque le widget accède à l'état "non valide".

.textfieldMinValueMsg

Force l'affichage du message d'erreur lorsque le widget accède à l'état "valeur minimale".


SPRY 45 Guide de l'utilisateur

Classe de message d'erreur

Description

.textfieldMaxValueMsg

Force l'affichage du message d'erreur lorsque le widget accède à l'état "valeur maximale".

.textfieldMinCharsMsg

Force l'affichage du message d'erreur lorsque le widget accède à l'état "nombre minimal de caractères".

.textfieldMaxCharsMsg

Force l'affichage du message d'erreur lorsque le widget accède à l'état "nombre maximal de caractères".

.textfieldValidMsg

Force l'affichage du message d'erreur lorsque le widget accède à l'état "valide".

Remarque : Il est impossible de renommer les classes associées aux états, car elles sont incorporées au cadre applicatif Spry.

Définition d'un type de validation et d'un format Vous pouvez définir de nombreux types de validation, des formats et d'autres options pour le widget Champ de texte de validation. Par exemple, vous pouvez définir un type de validation Carte de crédit si la zone de texte est destinée à contenir des numéros de carte de crédit. Les types de validation, les formats et les autres options sont définis en tant que paramètres dans le constructeur du widget. Le premier paramètre du constructeur est l'ID de conteneur du widget, suivi d'un deuxième paramètre (le paramètre de type de validation) et éventuellement d'un troisième. Le troisième paramètre est une plage d'options JavaScript qui dépend du type de validation défini dans le deuxième. Il est par conséquent impossible de définir le troisième paramètre sans le deuxième. Remarque : Si vous voulez définir le troisième paramètre alors qu'aucun type de validation n'est requis, vous pouvez fixer ce dernier à "none" (aucun). Le code suivant présente la syntaxe générique du constructeur d'un widget Champ de texte avec divers paramètres : <script type="text/javascript"> var sprytextfield1= new Spry.Widget.ValidationTextField("WidgetContainerID", "ValidationType", {option1:"value1", option2:"value2", ..}); </script>

Options de type de validation

Pour la plupart des types de validation, le champ de texte attend un format standard. Par exemple, si vous appliquez le type de validation Entier à un champ de texte, le widget n'effectue de validation que si l'utilisateur a entré des chiffres dans le champ de texte. Toutefois, certains types de validation permettent de choisir le type de format que votre champ de texte acceptera. Le tableau suivant présente les types de validation disponibles et leurs formats. Type de validation

Format

none

Aucun format particulier requis.

integer

Le champ de texte n'accepte que des chiffres.

email

Le champ de texte accepte les adresses électroniques contenant un symbole @ et un point (.) précédé et suivi d'au moins une lettre.

date

Formats variables.

time

Formats variables.

credit_card

Formats variables.

zip_code

Formats variables.

phone_number

Le champ de texte accepte les numéros de téléphone mis en forme pour les Etats-Unis et le Canada, à savoir (000) 0000000, ainsi que les formats personnalisés.


SPRY 46 Guide de l'utilisateur

Type de validation

Format

social_security_number

Le champ de texte accepte les numéros de sécurité sociale, en format 000-00-0000 par défaut.

currency

Le champ de texte accepte les devises en format 1,000,000.00 ou 1.000.000,00.

real

Valide divers types de nombres et la notation scientifique : les entiers (par exemple 1), les valeurs flottantes (par exemple 12,123) et les valeurs flottantes en notation scientifique (par exemple 1,212e+12, 1,221e-12, où e représente une puissance de 10).

ip

Valide les adresses IP de type IPv4, IPv6 ou les deux.

url

Le champ de texte accepte les URL en format http://xxx.xxx.xxx , https://xxx.xxx.xxx ou ftp://xxx.xxx.xxx.

custom

Permet de choisir un type et un format de validation personnalisé.

Validation d'un entier ❖ Pour que le champ de texte n'accepte que les nombres entiers, ajoutez "integer" comme valeur du deuxième paramètre

du constructeur, comme suit : <script type="text/javascript"> var textfieldwidget1 = new Spry.Widget.ValidationTextField("textfieldwidget1", "integer"); </script>

Le type de validation "integer" accepte les valeurs négatives et positives. Pour n'accepter que les valeurs positives, ajoutez l'option allowNegative au troisième paramètre et fixez sa valeur à false. <script type="text/javascript"> var textfieldwidget1 = new Spry.Widget.ValidationTextField("textfieldwidget1", "integer", {allowNegative:false}); </script>

Le tableau suivant présente d'autres options et valeurs courantes pour le troisième paramètre. Option

Valeur

format

Pas d'application.

validateOn

["blur"], ["change"] ou les deux ensemble (["blur", "change"])

isRequired

true (par défaut), false

useCharacterMasking

false (par défaut), true

minChars/maxChars

Pas d'application.

minValue/maxValue

Nombre entier

pattern

Pas d'application.

Validation d'un e-mail ❖ Pour que le champ de texte n'accepte que les formats d'e-mail standard, ajoutez "email" comme valeur du deuxième

paramètre du constructeur, comme suit : <script type="text/javascript"> var sprytextfield1= new Spry.Widget.ValidationTextField("sprytextfield1", "email"); </script>

Vous pouvez également définir des options pour le troisième paramètre en employant la syntaxe suivante : <script type="text/javascript"> var textfieldwidget1 = new Spry.Widget.ValidationTextField("textfieldwidget1", "email", {option:value}); </script>


SPRY 47 Guide de l'utilisateur

Le tableau suivant présente quelques options et valeurs courantes pour le troisième paramètre. Option

Valeur

format

Pas d'application.

validateOn

["blur"], ["change"] ou les deux ensemble (["blur", "change"])

isRequired

true (par défaut), false

useCharacterMasking

Pas d'application.

minChars/maxChars

Nombre entier positif

minValue/maxValue

Pas d'application.

pattern

Pas d'application.

Validation d'une date ❖ Pour que le champ de texte n'accepte que les formats de date, ajoutez "date" comme valeur du deuxième paramètre du

constructeur, comme suit : <script type="text/javascript"> var sprytextfield1= new Spry.Widget.ValidationTextField("sprytextfield1", "date"); </script>

Le format de date par défaut est "mm/jj/aa" (format de date des Etats-Unis). Vous pouvez toutefois définir divers autres formats de date dans le troisième paramètre en utilisant l'option format, comme dans l'exemple suivant : <script type="text/javascript"> var textfieldwidget1 = new Spry.Widget.ValidationTextField("textfieldwidget1", "date", {format:"yyyymm-dd"}); </script>

Le tableau suivant présente la liste des options de mise en forme ainsi que quelques autres options et valeurs courantes pour le troisième paramètre. Option

Valeur

format

"mm/jj/aa" (par défaut), "mm/jj/aaaa", "jj/mm/aaaa", "jj/mm/aa", "aa/mm/jj", "aaaa/mm/jj", "mm-jj-aa", "jj-mm-aa", "aaaa-mm-jj", "mm.jj.aaaa", "jj.mm.aaaa"

validateOn

["blur"], ["change"] ou les deux ensemble (["blur", "change"])

isRequired

true (par défaut), false

useCharacterMasking

false (par défaut), true

minChars/maxChars

Pas d'application.

minValue/maxValue

Valeur de date dans le format spécifié.

pattern

Pas d'application.

Validation d'une heure ❖ Pour que le champ de texte n'accepte que les formats d'heure, ajoutez "time" comme valeur du deuxième paramètre du

constructeur, comme suit : <script type="text/javascript"> var sprytextfield1= new Spry.Widget.ValidationTextField("sprytextfield1", "time"); </script>

Le format d'heure par défaut est "HH:mm" (heures et minutes). Vous pouvez toutefois définir divers autres formats d'heure dans le troisième paramètre en utilisant l'option format, comme dans l'exemple suivant :


SPRY 48 Guide de l'utilisateur

<script type="text/javascript"> var textfieldwidget1 = new Spry.Widget.ValidationTextField("textfieldwidget1", "time", {format:"HH:mm:ss"}); </script>

Le tableau suivant présente la liste des options de mise en forme ainsi que quelques autres options et valeurs courantes pour le troisième paramètre. Option

Valeur

format

"HH:mm" (par défaut), "HH:mm:ss", "hh:mm tt", "hh:mm:ss tt", "hh:mm t", "hh:mm;ss t" (où "tt" représente le format am/pm et "t" le format a/p)

validateOn

["blur"], ["change"] ou les deux ensemble (["blur", "change"])

isRequired

true (par défaut), false

useCharacterMasking

false (par défaut), true

minChars/maxChars

Pas d'application.

minValue/maxValue

Valeur d'heure dans le format spécifié.

pattern

Pas d'application.

Validation d'une carte de crédit ❖ Pour que le champ de texte n'accepte que les formats de carte de crédit, ajoutez "credit_card" comme valeur du

deuxième paramètre du constructeur, comme suit : <script type="text/javascript"> var sprytextfield1= new Spry.Widget.ValidationTextField("sprytextfield1", "credit_card"); </script>

Par défaut, tous les types de cartes de crédit sont validés. Vous pouvez toutefois spécifier des formats spécifiques à accepter, en utilisant l'option format dans le troisième paramètre, comme dans l'exemple suivant : <script type="text/javascript"> var textfieldwidget1 = new Spry.Widget.ValidationTextField("textfieldwidget1", "credit_card", {format:"visa"}); </script>

Le tableau suivant présente la liste des options de mise en forme ainsi que quelques autres options et valeurs courantes pour le troisième paramètre. Option

Valeur

format

Aucun format (par défaut), "visa", "mastercard", "amex", "discover", "dinersclub"

validateOn

["blur"], ["change"] ou les deux ensemble (["blur", "change"])

isRequired

true (par défaut), false

useCharacterMasking

false (par défaut), true

minChars/maxChars

Pas d'application.

minValue/maxValue

Pas d'application.

pattern

Pas d'application.

Validation d'un code postal ❖ Pour que le champ de texte n'accepte que les formats de code postal, ajoutez "zip_code" comme valeur du deuxième paramètre du constructeur, comme suit : <script type="text/javascript"> var sprytextfield1= new Spry.Widget.ValidationTextField("sprytextfield1", "zip_code"); </script>


SPRY 49 Guide de l'utilisateur

Le format par défaut est le format de code ZIP à 5 chiffres des Etats-Unis. Vous pouvez toutefois spécifier d'autres formats, en utilisant l'option format dans le troisième paramètre, comme dans l'exemple suivant : <script type="text/javascript"> var textfieldwidget1 = new Spry.Widget.ValidationTextField("textfieldwidget1", "zip_code", {format:"zip_uk"}); </script>

Le tableau suivant présente la liste des options de mise en forme ainsi que quelques autres options et valeurs courantes pour le troisième paramètre. Option

Valeur

format

"zip_us5" (par défaut), "zip_us9", "zip_uk", "zip_canada", "zip_custom"

validateOn

["blur"], ["change"] ou les deux ensemble (["blur", "change"])

isRequired

true (par défaut), false

useCharacterMasking

false (par défaut), true

minChars/maxChars

Pas d'application.

minValue/maxValue

Pas d'application.

pattern

Motif de code postal personnalisé. Utilisé lorsque format="zip_custom".

Le format "zip_custom" permet de définir un schéma personnalisé de format de code postal. Si vous choisissez le format "zip_custom", ajoutez l'option "pattern" au troisième paramètre afin de définir ce format. Par exemple, il peut arriver que vous souhaitiez valider un code postal constitué de trois chiffres suivi d'un autre groupe de chiffres et de caractères alphabétiques sensibles à la casse. Après l'option format, ajoutez l'option pattern au troisième paramètre du constructeur afin de définir le schéma personnalisé, comme suit : <script type="text/javascript"> var textfieldwidget1 = new Spry.Widget.ValidationTextField("textfieldwidget1", "zip_code", {format:"zip_custom", pattern:"000 00AA"}); </script>

Le tableau suivant présente la liste des valeurs utilisées pour les motifs personnalisés. Valeur

Description

"0"

Nombres entiers entre 0 et 9.

"A"

Caractères alphabétiques en majuscules

"a"

Caractères alphabétiques en minuscules

"B", "b"

Caractères alphabétiques non sensibles à la casse

"X"

Caractères alphanumériques en majuscules

"x"

Caractères alphanumériques en minuscules

"Y", "y"

Caractères alphanumériques non sensibles à la casse

"?"

N'importe quel caractère

Les caractères de schéma personnalisé "A", "a", "X" et "x" sont sensibles à la casse. Dans une situation qui emploie de tels caractères, Spry les convertit selon la casse appropriée, même si l'utilisateur les entre dans une casse incorrecte. Validation d'un numéro de téléphone ❖ Pour que le champ de texte n'accepte que les formats de numéro de téléphone, ajoutez "phone_number" comme valeur

du deuxième paramètre du constructeur, comme suit :


SPRY 50 Guide de l'utilisateur

<script type="text/javascript"> var sprytextfield1= new Spry.Widget.ValidationTextField("sprytextfield1", "phone_number"); </script>

Le format par défaut est le format d'indicatif local et de numéro de téléphone des Etats-Unis : (000) 000-0000. Vous pouvez également définir un format personnalisé dans le troisième paramètre en employant les options "phone_custom" et "pattern", comme dans l'exemple suivant : <script type="text/javascript"> var textfieldwidget1 = new Spry.Widget.ValidationTextField("textfieldwidget1", "zip_code", {format:"phone_custom" , pattern:"00 0000 A"}); </script>

Le tableau suivant présente la liste des valeurs utilisées pour les motifs personnalisés. Valeur

Description

"0"

Nombres entiers entre 0 et 9.

"A"

Caractères alphabétiques en majuscules

"a"

Caractères alphabétiques en minuscules

"B", "b"

Caractères alphabétiques non sensibles à la casse

"X"

Caractères alphanumériques en majuscules

"x"

Caractères alphanumériques en minuscules

"Y", "y"

Caractères alphanumériques non sensibles à la casse

"?"

N'importe quel caractère

Les caractères de schéma personnalisé "A", "a", "X" et "x" sont sensibles à la casse. Dans une situation qui emploie de tels caractères, Spry les convertit selon la casse appropriée, même si l'utilisateur les entre dans une casse incorrecte. Le tableau suivant présente quelques autres options et valeurs courantes pour le troisième paramètre. Option

Valeur

format

"phone_number" (par défaut), "phone_custom"

validateOn

["blur"], ["change"] ou les deux ensemble (["blur", "change"])

isRequired

true (par défaut), false

useCharacterMasking

false (par défaut), true

minChars/maxChars

Pas d'application.

minValue/maxValue

Pas d'application.

pattern

Schéma de numéro de téléphone personnalisé. Utilisé lorsque format="phone_custom".

Validation d'un numéro de sécurité sociale ❖ Pour que le champ de texte n'accepte que les formats de numéro de sécurité sociale, ajoutez "social_security_number"

comme valeur du deuxième paramètre du constructeur, comme suit : <script type="text/javascript"> var sprytextfield1= new Spry.Widget.ValidationTextField("sprytextfield1", "social_security number"); </script>

Le format par défaut est le format de numéro de sécurité sociale des Etats-Unis, avec des tirets : 000-00-0000. Vous pouvez également définir un format personnalisé dans le troisième paramètre en employant l'option "pattern", comme dans l'exemple suivant :


SPRY 51 Guide de l'utilisateur

<script type="text/javascript"> var textfieldwidget1 = new Spry.Widget.ValidationTextField("textfieldwidget1", "social_security_number", {format:"custom" pattern:"00 0000 A"}); </script>

Le tableau suivant présente la liste des valeurs utilisées pour les motifs personnalisés. Valeur

Description

"0"

Nombres entiers entre 0 et 9.

"A"

Caractères alphabétiques en majuscules

"a"

Caractères alphabétiques en minuscules

"B", "b"

Caractères alphabétiques non sensibles à la casse

"X"

Caractères alphanumériques en majuscules

"x"

Caractères alphanumériques en minuscules

"Y", "y"

Caractères alphanumériques non sensibles à la casse

"?"

N'importe quel caractère

Les caractères de schéma personnalisé "A", "a", "X" et "x" sont sensibles à la casse. Dans une situation qui emploie de tels caractères, Spry les convertit selon la casse appropriée, même si l'utilisateur les entre dans une casse incorrecte. Le tableau suivant présente quelques autres options courantes pour le troisième paramètre. Option

Valeur

format

Pas d'application.

validateOn

["blur"], ["change"] ou les deux ensemble (["blur", "change"])

isRequired

true (par défaut), false

useCharacterMasking

false (par défaut), true

minChars/maxChars

Pas d'application.

minValue/maxValue

Pas d'application.

pattern

Schéma de numéro de sécurité sociale personnalisé

Validation d'une devise ❖ Pour que le champ de texte n'accepte que les formats de devise, ajoutez "currency" comme valeur du deuxième

paramètre du constructeur, comme suit : <script type="text/javascript"> var sprytextfield1= new Spry.Widget.ValidationTextField("sprytextfield1", "currency"); </script>

Le format par défaut est le format de devise des Etats-Unis : 1,000.00. Vous pouvez également définir le format "dot_comma" (1.000,00) dans le troisième paramètre, comme suit : <script type="text/javascript"> var textfieldwidget1 = new Spry.Widget.ValidationTextField("textfieldwidget1", "currency", {format:"dot_comma"}); </script>

Dans les deux cas, les séparateurs des groupes de 3 chiffres peuvent être facultatifs, et la partie décimale (c.-à-d. ,00 dans 1 000,00) n'est pas obligatoire. Le tableau suivant présente quelques autres options courantes pour le troisième paramètre.


SPRY 52 Guide de l'utilisateur

Option

Valeur

format

"comma_dot" (par défaut), "dot_comma"

validateOn

["blur"], ["change"] ou les deux ensemble (["blur", "change"])

isRequired

true (par défaut), false

useCharacterMasking

false (par défaut), true

minChars/maxChars

Pas d'application.

minValue/maxValue

Valeur numérique avec deux décimales admises.

pattern

Pas d'application.

Validation de nombres réels et de notations scientifiques ❖ Pour que le champ de texte n'accepte que les nombres réels et la notation scientifique, ajoutez "real" comme valeur du deuxième paramètre du constructeur, comme suit : <script type="text/javascript"> var sprytextfield1= new Spry.Widget.ValidationTextField("sprytextfield1", "real"); </script>

Le champ de texte valide un nombre réel en notation scientifique, par exemple 1,231e10. Le tableau suivant présente quelques autres options courantes pour le troisième paramètre. Option

Valeur

format

Pas d'application.

validateOn

["blur"], ["change"] ou les deux ensemble (["blur", "change"])

isRequired

true (par défaut), false

useCharacterMasking

false (par défaut), true

minChars/maxChars

Pas d'application.

minValue/maxValue

Valeur numérique avec décimales.

pattern

Pas d'application.

Validation d'une adresse IP ❖ Pour que le champ de texte ne valide que les adresses IP, ajoutez "ip" comme valeur du deuxième paramètre du

constructeur, comme suit : <script type="text/javascript"> var sprytextfield1= new Spry.Widget.ValidationTextField("sprytextfield1", "ip"); </script>

La valeur par défaut est le format d'adresse IP IPv4, mais vous pouvez définir d'autres formats d'adresse dans le troisième paramètre en employant l'option "format", comme dans l'exemple suivant : <script type="text/javascript"> var textfieldwidget1 = new Spry.Widget.ValidationTextField("textfieldwidget1", "ip", {format:"ipv6"}); </script>

Le tableau suivant présente la liste des options de mise en forme ainsi que quelques autres options courantes pour le troisième paramètre.


SPRY 53 Guide de l'utilisateur

Option

Valeur

format

"ipv4" (par défaut), "ipv6", "ipv4_ipv6"

validateOn

["blur"], ["change"] ou les deux ensemble (["blur", "change"])

isRequired

true (par défaut), false

useCharacterMasking

false (par défaut), true

minChars/maxChars

Pas d'application.

minValue/maxValue

Pas d'application.

pattern

Pas d'application.

Validation d'une URL ❖ Pour que le champ de texte n'accepte que les URL, ajoutez "url" comme valeur du deuxième paramètre du constructeur,

comme suit : <script type="text/javascript"> var textfieldwidget1 = new Spry.Widget.ValidationTextField("textfieldwidget1", "url"); </script>

Le type de validation URL accepte les valeurs d'URL HTTP, HTTP et FTP. Le tableau suivant présente d'autres options courantes pour le troisième paramètre. Option

Valeur

format

Pas d'application.

validateOn

["blur"], ["change"] ou les deux ensemble (["blur", "change"])

isRequired

true (par défaut), false

useCharacterMasking

Pas d'application.

minChars/maxChars

Nombre entier positif

minValue/maxValue

Pas d'application.

pattern

Pas d'application.

Validation d'un format personnalisé ❖ Pour configurer le champ de texte de manière à ce qu'il accepte n'importe quel format personnalisé, spécifiez "custom"

comme valeur pour le deuxième paramètre et ajoutez l'option "pattern" au troisième, comme suit : <script type="text/javascript"> var textfieldwidget1 = new Spry.Widget.ValidationTextField("textfieldwidget1", "custom", {pattern:"00 0000 AX"}); </script>

Le tableau suivant présente la liste des valeurs utilisées pour les motifs personnalisés. Valeur

Description

"0"

Nombres entiers entre 0 et 9.

"A"

Caractères alphabétiques en majuscules

"a"

Caractères alphabétiques en minuscules

"B", "b"

Caractères alphabétiques non sensibles à la casse

"X"

Caractères alphanumériques en majuscules


SPRY 54 Guide de l'utilisateur

Valeur

Description

"x"

Caractères alphanumériques en minuscules

"Y", "y"

Caractères alphanumériques non sensibles à la casse

"?"

N'importe quel caractère

Les caractères de schéma personnalisé "A", "a", "X" et "x" sont sensibles à la casse. Dans une situation qui emploie de tels caractères, Spry les convertit selon la casse appropriée, même si l'utilisateur les entre dans une casse incorrecte.

Définition du moment de validation Par défaut, le widget Champ de texte de validation effectue sa validation lorsque l'utilisateur clique sur le bouton d'envoi. Vous pouvez toutefois définir deux autres options : blur ou change. Le paramètre validateOn:["blur"] force le widget à procéder à la validation quand l'utilisateur clique en dehors du champ de texte. Le paramètre validateOn:["change"] force le widget à procéder à la validation lorsque l'utilisateur modifie du texte dans le champ de texte. ❖ Pour déterminer quand la validation se produit, ajoutez un paramètre validateOn au constructeur, comme suit : <script type="text/javascript"> var sprytextfield1 = new Spry.Widget.ValidationTextField("sprytextfield1", "none", {validateOn:["blur"]}); </script>

Vous pouvez vous passer de parenthèses si votre paramètre validateOn contient une seule valeur (par exemple validateOn: "blur"). Par contre, si le paramètre contient les deux valeurs (validateOn:["blur", "change"]), la syntaxe doit comporter des parenthèses. Remarque : Dans l'exemple précédent, le second paramètre est fixé à "none". Il pourrait toutefois être aisément fixé à n'importe quel type de validation disponible (par exemple "phone" ou "credit_card"). Voir « Définition d'un type de validation et d'un format » à la page 45.

Définition d'un nombre minimal et maximal de caractères Cette option n'est disponible que pour les types de validation "none", "integer", "email" et "url". L'option minChars n'impose pas de nombre minimal de caractères si le champ de texte n'est pas obligatoire. ❖ Pour définir un nombre minimal ou maximal de caractères, ajoutez la propriété minChars ou maxChars (ou les deux) et une valeur au constructeur, comme suit : <script type="text/javascript"> var textfieldwidget1 = new Spry.Widget.ValidationTextField("textfieldwidget1", "validation_type", {minChars:value, maxChars:value}); </script>

Remarque : Si un type de validation n'est pas obligatoire, vous pouvez le fixer à "none". Voir « Définition d'un type de validation et d'un format » à la page 45.

Définition des valeurs minimale et maximale Cette option n'est disponible que pour les types de validation "integer", "date", "time", "currency" et "real". ❖ Pour définir des valeurs minimales ou maximales dans le champ de texte, ajoutez la propriété minValue ou maxValue (ou

les deux) et une valeur au constructeur, comme suit : <script type="text/javascript"> var textfieldwidget1 = new Spry.Widget.ValidationTextField("textfieldwidget1", "validation_type", {minValue:value, maxValue:value}); </script>


SPRY 55 Guide de l'utilisateur

Modification de l'état obligatoire d'une zone de texte Par défaut, le widget Champ de texte de validation exige une saisie par l'utilisateur lorsqu'il est publié sur une page Web. Vous pouvez toutefois rendre la saisie de texte dans certains champs facultative pour l'utilisateur. ❖ Pour modifier l'état obligatoire d'un champ de texte, ajoutez la propriété isRequired au constructeur et fixez sa valeur à

"false", comme suit : <script type="text/javascript"> var textfieldwidget1 = new Spry.Widget.ValidationTextField("textfieldwidget1", "none", {isRequired:false}); </script>

Remarque : Dans l'exemple précédent, le second paramètre est fixé à "none". Il pourrait toutefois être aisément fixé à n'importe quel type de validation disponible (par exemple "phone" ou "credit_card"). Voir « Définition d'un type de validation et d'un format » à la page 45.

Création d'un conseil pour une zone de texte Comme les zones de texte peuvent posséder de multiples formats, il peut être utile de donner aux utilisateurs un conseil relatif aux données qu'ils doivent entrer. Par exemple, un champ de texte possédant le type de validation Phone Number (numéro de téléphone) n'accepte, par défaut, que les numéros en format (000) 000-0000. Vous pouvez entrer cet exemple de numéro sous la forme d'un conseil, de manière à ce que le champ affiche le format correct lorsque l'utilisateur charge la page dans un navigateur. Cette option ne dépend pas du type de validation. Vous pouvez dès lors toujours la spécifier. Définissez "none" comme type de validation si aucun autre type de validation n'est requis. Lorsque l'utilisateur clique dans le champ de texte, le conseil disparaît. Lorsqu'il clique en dehors du champ, Spry rétablit le conseil dans le champ de texte si ce dernier ne contient aucune valeur. ❖ Pour créer un conseil pour un champ de texte, ajoutez la propriété hint au troisième paramètre du constructeur, avec comme valeur le texte du conseil, comme suit : <script type="text/javascript"> var textfieldwidget1 = new Spry.Widget.ValidationTextField("textfieldwidget1", "validation_type", {hint:"some hint text here"}); </script>

Blocage des caractères incorrects Vous pouvez empêcher les utilisateurs d'entrer des caractères non valides dans un widget Champ de texte de validation. Par exemple, si vous activez cette option pour un widget possédant le type de validation Nombre entier, rien ne s'affiche dans le champ si l'utilisateur tente d'y taper une lettre. Vous devez définir un type de validation pour cette option, car la spécification du troisième paramètre dépend du deuxième paramètre. Si aucun type de validation n'est requis, choisissez "none" comme type de validation. Cette option ne fonctionne pas dans les navigateurs plus anciens. ❖ Pour bloquer les caractères non valides, ajoutez la propriété useCharacterMasking au constructeur et fixez sa valeur à

"true", comme suit : <script type="text/javascript"> var textfieldwidget1 = new Spry.Widget.ValidationTextField("textfieldwidget1", "validation_type", {useCharacterMasking:true}); </script>

Personnalisation du widget Validation de zone de texte Le fichier SpryValidationTextField.css fournit le style par défaut du widget Champ de texte de validation. Vous pouvez toutefois personnaliser ce widget en modifiant la règle CSS appropriée. Les règles CSS du fichier SpryValidationTextField.css emploient les mêmes noms de classes que les éléments associés du code HTML du widget. Vous pouvez ainsi déterminer aisément quelles règles CSS correspondent au widget et à ses états d'erreur.


SPRY 56 Guide de l'utilisateur

Le fichier SpryValidationTextField.css doit déjà être placé sur votre site Web avant que vous entamiez des activités de personnalisation. Pour plus d'informations, consultez la section « Préparation des fichiers » à la page 3. Définition du style du widget Champ de texte de validation (instructions générales)

1 Ouvrez le fichier SpryValidationTextField.css. 2 Accédez à la règle CSS pour la partie du widget à modifier. Par exemple, pour modifier la couleur d'arrière-plan de l'état obligatoire du widget Champ de texte, modifiez la règle .textfieldRequiredState dans le fichier CSS. 3 Apportez les modifications désirées au code CSS puis enregistrez le fichier. Le fichier SpryValidationTextField.css contient de nombreux commentaires qui expliquent le code et le rôle de certaines règles. Pour plus d'informations, consultez les commentaires dans le fichier. Définition du style du texte de message d'erreur d'un widget Zone de texte de validation

Par défaut, les messages d'erreur du widget Champ de texte de validation s'affichent en rouge, entourés d'un bord plein de 1 pixel d'épaisseur. ❖ Pour modifier le style des messages d'erreur d'un widget Champ de texte de validation, recherchez la règle CSS

appropriée dans le tableau suivant, puis modifiez les propriétés par défaut ou ajoutez vos propriétés et valeurs de style du texte. Texte à modifier

Règle CSS pertinente

Propriétés à modifier

Texte de message d'erreur

.textfieldRequiredState .textfieldRequiredMsg, .textfieldInvalidFormatState .textfieldInvalidFormatMsg, .textfieldMinValueState .textfieldMinValueMsg, .textfieldMaxValueState .textfieldMaxValueMsg, .textfieldMinCharsState .textfieldMinCharsMsg, .textfieldMaxCharsState .textfieldMaxCharsMsg

color: #CC3333; border: 1px solid #CC3333;

Modification des couleurs d'arrière-plan du widget Validation de zone de texte ❖ Pour modifier les couleurs d'arrière-plan du widget Champ de texte de validation dans différents états, recherchez la règle CSS appropriée dans le tableau suivant, puis modifiez la couleur d'arrière-plan par défaut. Couleur à modifier

Règle CSS pertinente

Propriété à modifier

Couleur d'arrière-plan du widget dans un état valide

.textfieldValidState input, input.textfieldValidState

background-color: #B8F5B1;

Couleur d'arrière-plan du widget dans un état non valide

input.textfieldRequiredState, .textfieldRequiredState input, input.textfieldInvalidFormatState, .textfieldInvalidFormatState input, input.textfieldMinValueState, .textfieldMinValueState input, input.textfieldMaxValueState, .textfieldMaxValueState input, input.textfieldMinCharsState, .textfieldMinCharsState input, input.textfieldMaxCharsState, .textfieldMaxCharsState input

background-color: #FF9F9F;

Couleur d'arrière-plan du widget actif

.textfieldFocusState input, input.textfieldFocusState

background-color: #FFFFCC;

Définition de motifs personnalisés

Le tableau suivant présente la liste des valeurs utilisées pour les motifs personnalisés. Valeur

Description

"0"

Nombres entiers entre 0 et 9.

"A"

Caractères alphabétiques en majuscules

"a"

Caractères alphabétiques en minuscules

"B", "b"

Caractères alphabétiques non sensibles à la casse


SPRY 57 Guide de l'utilisateur

Valeur

Description

"X"

Caractères alphanumériques en majuscules

"x"

Caractères alphanumériques en minuscules

"Y", "y"

Caractères alphanumériques non sensibles à la casse

"?"

N'importe quel caractère

Ces valeurs permettent de créer un schéma personnalisé pour n'importe quel type de format. Par exemple, pour définir un numéro de sécurité sociale personnalisé qui combine des chiffres et des lettres en majuscules, définissez le schéma personnalisé suivant dans le troisième paramètre du constructeur : <script type="text/javascript"> var textfieldwidget1 = new Spry.Widget.ValidationTextField("textfieldwidget1", "social_security_number", {format:"custom", pattern:"AA00AA"}); </script>

Le code précédent produit un champ de texte qui accepte des valeurs telles que UT99CW, AB87PP, GV44RE, etc. Remarque : Les utilisateurs de Dreamweaver peuvent se contenter d'entrer un schéma personnalisé dans le champ de texte Schéma de l'inspecteur Propriétés, à l'aide des valeurs fournies dans le tableau ci-dessus. Par exemple, AA00AA. Remarque : Le mécanisme de validation de Spry n'accepte que les caractères ASCII. Insertion de caractères de saisie semi-automatique

Le tableau suivant présente la liste des valeurs utilisées pour les motifs personnalisés. Valeur

Description

"0"

Nombres entiers entre 0 et 9.

"A"

Caractères alphabétiques en majuscules

"a"

Caractères alphabétiques en minuscules

"B", "b"

Caractères alphabétiques non sensibles à la casse

"X"

Caractères alphanumériques en majuscules

"x"

Caractères alphanumériques en minuscules

"Y", "y"

Caractères alphanumériques non sensibles à la casse

"?"

N'importe quel caractère

Tout caractère (lettres, ponctuation, etc.) autres que la barre oblique inverse (\) et ceux qui figurent dans le tableau précédent sont considérés comme des caractères pour saisie semi-automatique. Spry peut les insérer au moment opportun. Par exemple, dans le cas d'un code postal de type UT.99CW, il peut être utile que Spry insère le point automatiquement lorsque l'utilisateur a tapé les deux premières lettres en majuscules. ❖ Pour utiliser un caractère pour saisie semi-automatique, insérez-le dans le schéma de format, comme suit : <script type="text/javascript"> var textfieldwidget1 = new Spry.Widget.ValidationTextField("textfieldwidget1", "zip_code", {format:"zip_custom", pattern:"AA.00AA"}); </script>

Le code précédent produit un champ de texte qui accepte des valeurs telles que UT.99CW, AB.87PP, GV.44RE, etc., où le point apparaît automatiquement lorsque l'utilisateur a tapé les deux premières lettres en majuscules. Vous pouvez également demander à Spry de saisir des lettres de manière semi-automatique (à l'exception de celles qui figurent dans le tableau précédent), comme dans l'exemple suivant :


SPRY 58 Guide de l'utilisateur

<script type="text/javascript"> var textfieldwidget1 = new Spry.Widget.ValidationTextField("textfieldwidget1", "zip_code", {format:"zip_custom", pattern:"AA.00AAF3"}); </script>

Le code précédent produit un champ de texte qui accepte des valeurs telles que UT.99CWF3, AB.87PPF3, GV.44REF3, etc., où le point apparaît automatiquement lorsque l'utilisateur a tapé les deux premières lettres en majuscules et où F3 apparaît lorsque l'utilisateur a tapé les deux dernières lettres en majuscules. Pour employer l'un des caractères spéciaux figurant dans le tableau précédent pour la saisie semi-automatique, faites-les précéder d'une double barre oblique (\\), comme dans l'exemple suivant : <script type="text/javascript"> var textfieldwidget1 = new Spry.Widget.ValidationTextField("textfieldwidget1", "zip_code", {format:"zip_custom", pattern:"AA.00AA\\B3"}); </script>

Le code précédent produit un champ de texte qui accepte des valeurs telles que UT.99CWB3, AB.87PPB3, GV.44REB3, etc., où le point apparaît automatiquement lorsque l'utilisateur a tapé les deux premières lettres en majuscules et où B3 apparaît lorsque l'utilisateur a tapé les deux dernières lettres en majuscules. Pour utiliser une barre oblique (\) dans une séquence de saisie semi-automatique, doublez-la puis faites-la précéder d'une double barre oblique (\\), ce qui donne au total quatre barres obliques (\\\\), comme dans l'exemple suivant : <script type="text/javascript"> var textfieldwidget1 = new Spry.Widget.ValidationTextField("textfieldwidget1", "zip_code", {format:"zip_custom", pattern:"AA\\\\00AA"}); </script>

Le code précédent produit un champ de texte qui accepte des valeurs telles que UT\99CW, AB\87PP, GV\44RE, etc., où la barre oblique apparaît automatiquement lorsque l'utilisateur a tapé les deux premières lettres en majuscules. Personnalisation des noms de classes associées aux états

Bien qu'il soit possible de remplacer des noms de classes associées aux messages d'erreur par des noms personnalisés en modifiant les règles dans le code CSS et les noms des classes dans le code HTML, vous ne pouvez pas modifier ni remplacer des noms de classes associées à des états. Les comportements sont en effet incorporés au cadre applicatif Spry. Vous pouvez toutefois remplacer le nom par défaut d'une classe associée à un état par le nom de votre choix en définissant une nouvelle valeur dans le troisième paramètre du constructeur du widget. ❖ Pour modifier des noms de classes associés à l'état d'un widget, ajoutez l'une des options de remplacement au troisième paramètre du constructeur du widget, puis définissez le nom de votre choix, comme suit : <script type="text/javascript"> var sprytextfield1 = new Spry.Widget.ValidationTextField("sprytextfield1", "none", {requiredClass:"required"}); </script>

Le tableau suivant fournit la liste des options que vous pouvez utiliser pour remplacer les noms intégrés des classes associées aux états. Option

Description

requiredClass

Supplante la valeur prédéfinie "textfieldRequiredState".

invalidFormatClass

Supplante la valeur prédéfinie "textfieldInvalidFormatState".

validClass

Supplante la valeur prédéfinie "textfieldValidState".

focusClass

Supplante la valeur prédéfinie "textfieldFocusState".

invalidFormatClass

Supplante la valeur prédéfinie "textfieldInvalidFormatState".

invalidRangeMinClass

Supplante la valeur prédéfinie "textfieldMinValueState".

invalidRangeMaxClass

Supplante la valeur prédéfinie "textfieldMaxValueState".


SPRY 59 Guide de l'utilisateur

Option

Description

invalidCharsMinClass

Supplante la valeur prédéfinie "textfieldMinCharsState".

invalidCharsMaxClass

Supplante la valeur prédéfinie "textfieldMaxCharsState".

textfieldFlashTextClass

Supplante la valeur prédéfinie "textfieldFlashText".

Utilisation du widget Zone de texte de validation Présentation et structure du widget Zone de texte de validation Le widget Validation Spry de zone de texte est une zone de texte qui affiche des états valides ou non valides lorsque le visiteur du site entre quelques lignes de texte. Si la zone de texte est un champ obligatoire et que l'utilisateur n'y entre pas de texte, le widget affiche un message indiquant qu'une valeur est requise. L'exemple suivant montre un widget Zone de texte de validation dans différents états. A

B

C

D

E

A. Compteur de caractères restants B. Widget Zone de texte activé, nombre maximal de caractères C. Widget Zone de texte activé, état valide D. Widget Zone de texte, état obligatoire E. Compteur de caractères tapés

Le widget Zone de texte de validation peut posséder divers états (par exemple valide, non valide, valeur obligatoire, etc.). Vous pouvez modifier les propriétés de ces états à l'aide de l'inspecteur Propriétés, en fonction des résultats de validation désirés. Un widget Zone de texte de validation peut effectuer une validation à différents moments, par exemple lorsque le visiteur clique en dehors du widget, pendant qu'il entre des données ou lorsqu'il tente d'envoyer le formulaire. Etat initial Lorsque la page se charge dans le navigateur, ou lorsque l'utilisateur réinitialise le formulaire. Etat actif Lorsque l'utilisateur place le point d'insertion à l'intérieur du widget. Etat valide Lorsque l'utilisateur a entré des informations correctes, ce qui permet l'envoi du formulaire. Etat obligatoire Lorsque l'utilisateur n'a pas entré de texte. Nombre minimal de caractères Lorsque l'utilisateur a entré moins de caractères que le nombre minimal requis pour la zone

de texte. Nombre maximal de caractères Lorsque l'utilisateur a entré plus de caractères que le nombre maximal admis pour la zone

de texte. Lorsqu'un widget Zone de texte de validation passe dans l'un de ces états suite à l'interaction avec l'utilisateur, la logique du cadre Spry applique une classe CSS spécifique au conteneur HTML pour le widget lors de l'exécution. Par exemple, si un utilisateur tente d'envoyer un formulaire mais n'a pas entré de texte dans la zone de texte, Spry applique au widget une classe qui le force à afficher le message d'erreur « Vous devez entrer une valeur ». Les règles qui contrôlent le style et les états d'affichage de messages d'erreur se trouvent dans le fichier qui accompagne le widget, SpryValidationTextarea.css.


SPRY 60 Guide de l'utilisateur

Le code HTML par défaut du widget Zone de texte de validation, généralement dans un formulaire, contient une balise conteneur span qui entoure la balise textarea de la zone de texte. Le code HTML du widget Zone de texte de validation comprend également des balises script dans l'en-tête du document et après le code HTML du widget. La balise script dans l'en-tête du document définit toutes les fonctions JavaScript relatives au widget Zone de texte. La balise script qui suit le code du widget crée un objet JavaScript qui rend la zone de texte interactive. Voici le code HTML d'un widget Zone de texte de validation : <head> ... <!-- Link the Spry Validation Text Area JavaScript library --> <script src="SpryAssets/SpryValidationTextarea.js" type="text/javascript"></script> <!-- Link the CSS style sheet that styles the widget --> <link href="SpryAssets/SpryValidationTextarea.css" rel="stylesheet" type="text/css" /> </head> <body> <form id="form1" name="form1" method="post" action=""> <!-- Create the text area widget and assign a unique id--> <span id="sprytextarea1"> <textarea name="textarea1" id="textarea1" cols="45" rows="5"></textarea> <!--Display an error message--> <span class="textareaRequiredMsg">A value is required.</span> </span> </form> <!-- Initialize the Validation Text Area widget object--> <script type="text/javascript"> var sprytextarea1 = new Spry.Widget.ValidationTextarea("sprytextarea1"); </script> </body>

Dans le code, l'opérateur JavaScript new initialise l'objet widget Zone de texte et transforme le contenu span possédant l'ID sprytextarea1, qui était un code HTML statique, en un élément de page interactif. La balise span du message d'erreur dans le widget comporte une classe CSS qui y est appliquée. Cette classe (fixée à display:none; par défaut) détermine le style et la visibilité du message d'erreur. Elle se trouve dans le fichier CSS joint, SpryValidationTextarea.css. Lorsque le widget passe dans un état différent suite à l'interaction avec l'utilisateur, Spry applique une classe différente au conteneur du widget, ce qui influe sur la classe de message d'erreur. Pour ajouter d'autres messages d'erreur à un widget Zone de texte de validation, créez une balise span (ou tout autre type de balise) qui en contiendra le texte. Ensuite, en lui appliquant une classe CSS, vous pouvez afficher ou masquer le message en fonction de l'état du widget. Vous pouvez modifier l'apparence par défaut des états du widget Zone de texte de validation en modifiant la règle CSS correspondante dans le fichier SpryValidationTextarea.css. Par exemple, pour modifier la couleur d'arrière-plan en fonction d'un état, modifiez la règle correspondante ou ajoutez-en une nouvelle (si elle n'existe pas encore) dans la feuille de style. Variation des balises utilisées pour la structure du widget Zone de texte

Dans l'exemple précédent, des balises span servent à créer la structure du widget : Container SPAN TEXTAREA tag Error message SPAN

Il est toutefois possible d'employer à peu près n'importe quelle balise conteneur pour créer un widget : Container DIV TEXTAREA tag Error Message P

Spry utilise l'ID de balise (et pas la balise proprement dite) pour créer le widget. Spry affiche également les messages d'erreur à l'aide de code CSS qui ne varie pas selon la balise qui contient les messages en question.


SPRY 61 Guide de l'utilisateur

L'ID transmis au constructeur du widget identifie un élément HTML spécifique. Le constructeur trouve cet élément et recherche, dans le conteneur identifié, la balise textarea correspondante. Si l'ID transmis au constructeur est l'ID de la balise textarea (au lieu d'une balise conteneur), le constructeur joint directement des déclencheurs de validation à la balise textarea. Par contre, si aucune balise conteneur n'est présente, le widget ne peut pas afficher les messages d'erreur. Les divers états de validation se bornent à modifier l'apparence de l'élément de balise textarea (par exemple sa couleur d'arrière-plan). Remarque : Les balises textarea multiples ne fonctionnent pas à l'intérieur d'un même conteneur de widget HTML. Chaque champ de texte doit être son propre widget.

Code CSS pour le widget Zone de texte de validation Le fichier SpryValidationTextarea.css contient les règles qui définissent le style du widget Zone de texte de validation et de ses messages d'erreur. Vous pouvez modifier ces règles afin de définir l'apparence du widget et des messages d'erreur. Les noms des règles dans le fichier CSS correspondent aux noms des classes définies dans le code HTML du widget. Le code CSS du fichier SpryValidationTextarea.css est le suivant : /*Validation Textarea styling classes*/ .textareaRequiredMsg, .textareaMinCharsMsg, .textareaMaxCharsMsg, .textareaValidMsg { display:none; } .textareaRequiredState .textareaRequiredMsg, .textareaMinCharsState .textareaMinCharsMsg, .textareaMaxCharsState .textareaMaxCharsMsg{ display: inline; color: #CC3333; border: 1px solid #CC3333; } .textareaValidState textarea, textarea.textareaValidState { background-color:#B8F5B1; } textarea.textareaRequiredState, .textareaRequiredState textarea, textarea.textareaMinCharsState, .textareaMinCharsState textarea, textarea.textareaMaxCharsState, .textareaMaxCharsState textarea { background-color:#FF9F9F; } .textareaFocusState textarea, textarea.textareaFocusState { background-color:#FFFFCC; } .textareaFlashState textarea, textarea.textareaFlashState{ color:red !important; }

Le fichier SpryValidationTextarea.css contient également de nombreux commentaires qui expliquent le code et le rôle de certaines règles. Pour plus d'informations, consultez les commentaires dans le fichier.

Insertion du widget Zone de texte de validation 1 Recherchez le fichier SpryValidationTextarea.js et ajoutez-le à votre site Web. Le fichier SpryValidationTextarea.js se trouve dans le répertoire widgets/textareavalidation qui figure dans le répertoire Spry téléchargé depuis le site Adobe Labs. Pour plus d'informations, consultez la section « Préparation des fichiers » à la page 3. Par exemple, créez un dossier nommé SpryAssets dans le dossier racine de votre site Web, puis déplacez-y le fichier SpryValidationTextarea.js. Le fichier SpryValidationTextarea.js contient toutes les informations qui rendent le widget Zone de texte interactif. 2 Recherchez le fichier SpryValidationTextarea.css et ajoutez-le à votre site Web. Vous pouvez l'ajouter dans le répertoire principal, dans un répertoire SpryAssets ou dans un répertoire CSS, si vous en avez créé un. 3 Ouvrez la page Web à laquelle ajouter le widget Zone de texte puis liez le fichier SpryValidationTextarea.js à la page en insérant la balise script suivante dans la balise "head" de la page : <script src="SpryAssets/SpryValidationTextarea.js" type="text/javascript"></script>


SPRY 62 Guide de l'utilisateur

Assurez-vous que le chemin d'accès au fichier SpryValidationTextarea.js est bien correct. Ce chemin d'accès varie selon l'endroit où vous avez placé le fichier dans votre site Web. 4 Liez le fichier SpryValidationTextarea.css à votre page Web en insérant la balise link suivante dans la balise "head" de la page : <link href="SpryAssets/SpryValidationTextarea.css" rel="stylesheet" type="text/css" />

Assurez-vous que le chemin d'accès au fichier SpryValidationTextarea.css est bien correct. Ce chemin d'accès varie selon l'endroit où vous avez placé le fichier dans votre site Web. 5 Ajoutez une zone de texte à la page, puis attribuez-lui un nom et un ID unique : <textarea name="mytextarea" id="textarea"></textarea>

6 Pour ajouter un conteneur autour de la zone de texte, insérez des balises span autour des balises <textarea>, puis attribuez un ID unique au widget, comme suit : <span id="sprytextarea1"> <textarea name="mytextarea"></textarea> </span>

7 Initialisez l'objet Zone de texte en insérant le bloc "script" suivant après le code HTML du widget : <script type="text/javascript"> var sprytextarea1 = new Spry.Widget.ValidationTextarea("sprytextarea1"); </script>

L'opérateur JavaScript new initialise l'objet widget Zone de texte et transforme le contenu span possédant l'ID "sprytextarea1", qui était un code HTML statique, en un objet Zone de texte interactif. La méthode Spry.Widget.ValidationTextarea est un constructeur du cadre applicatif Spry qui crée des objets Zone de texte. Les informations requises pour l'initialisation de l'objet figurent dans la bibliothèque JavaScript SpryValidationTextarea.js que vous avez liée au début de cette procédure. Assurez-vous que l'ID de la balise span de la zone de texte corresponde au paramètre ID spécifié dans la méthode "Spry.Widgets.ValidationTextarea". Assurez-vous que l'appel JavaScript se trouve bien après le code HTML du widget. 8 Enregistrez la page. Le code complet ressemble à ce qui suit : <head> ... <script src="SpryAssets/SpryValidationTextarea.js" type="text/javascript"></script> <link href="SpryAssets/SpryValidationTextarea.css" rel="stylesheet" type="text/css" /> </head> <body> <form id="form1" name="form1" method="post" action=""> <span id="sprytextarea1"> <textarea name="textarea1" id="textarea1" cols="45" rows="5"></textarea> </span> </form> <script type="text/javascript"> var sprytextarea1 = new Spry.Widget.ValidationTextarea("sprytextarea1"); </script> </body>

Affichage de messages d'erreur ❖ Créez une balise "span" (ou tout autre type de balise) pour afficher le message d'erreur, et attribuez-lui la classe appropriée, comme suit : <span id="sprytextarea1"> <textarea name="textarea1" id="textarea1" cols="45" rows="5"></textarea> <span class="textareaRequiredMsg">Please enter a description</span> </span>


SPRY 63 Guide de l'utilisateur

La règle .textareaRequiredMsg se trouve dans le fichier SpryValidationTextarea.css et est fixée àdisplay:none par défaut. Lorsque le widget passe dans un état différent suite à l'interaction avec l'utilisateur, Spry applique la classe appropriée (la classe d'état) au conteneur du widget. Cette action influe sur la classe du message d'erreur et, dès lors, sur l'apparence de ce message. Par exemple, voici une partie du code CSS dans le fichier SpryValidationTextarea.css : .textareaRequiredMsg, .textareaMinCharsMsg, .textareaMaxCharsMsg, .textareaValidMsg { display:none; } .textareaRequiredState .textareaRequiredMsg, .textareaMinCharsState .textareaMinCharsMsg, .textareaMaxCharsState .textareaMaxCharsMsg { display: inline; color: #CC3333; border: 1px solid #CC3333; }

Par défaut, aucune classe d'état n'est appliquée au conteneur du widget. Dès lors, lorsque la page est chargée dans un navigateur, seule la classe .textareaRequiredMsg est appliquée au texte du message d'erreur présenté dans l'exemple de code HTML précédent. La paire propriété/valeur pour cette règle étant display:none, le message reste masqué. Toutefois, si l'utilisateur n'a pas entré de texte dans une zone de texte obligatoire, Spry applique la classe appropriée au conteneur du widget, comme suit : <span id="sprytextarea1" class="textareaRequiredState"> <input type="text" name="mytextarea" id="mytextarea" /> <span class="textareaRequiredMsg">Please enter a description</span> </span>

Dans le code CSS précédent, vous pouvez constater que la règle d'état avec le sélecteur contextuel .textareaRequiredState . textareaRequiredMsg supplante la règle de message d'erreur par défaut, qui masquait le texte du message. Dès lors, lorsque Spry applique la classe d'état au conteneur du widget, la règle d'état détermine l'apparence du widget et affiche le message d'erreur en ligne, en rouge, encadré d'une bordure pleine de 1 pixel d'épaisseur. La liste suivante présente les classes de messages d'erreur par défaut et leurs descriptions. Vous pouvez modifier ces classes et les renommer. Dans ce cas, n'oubliez pas de les modifier également dans le sélecteur contextuel. Classe de message d'erreur

Description

.textareaRequiredMsg

Force l'affichage du message d'erreur lorsque le widget accède à l'état "obligatoire".

.textareaMinCharsMsg

Force l'affichage du message d'erreur lorsque le widget accède à l'état "nombre minimal de caractères".

.textareaMaxCharsMsg

Force l'affichage du message d'erreur lorsque le widget accède à l'état "nombre maximal de caractères".

.textareaValidMsg

Force l'affichage du message d'erreur lorsque le widget accède à l'état "valide".

Remarque : Il est impossible de renommer les classes associées aux états, car elles sont incorporées au cadre applicatif Spry.

Définition du moment de validation Par défaut, le widget Zone de texte de validation effectue sa validation lorsque l'utilisateur clique sur le bouton d'envoi. Vous pouvez toutefois définir deux autres options : "blur" ou "change". Le paramètre validateOn:["blur"] force le widget à procéder à la validation quand l'utilisateur clique en dehors de la zone de texte. Le paramètre validateOn:["change"] force le widget à procéder à la validation lorsque l'utilisateur modifie du texte dans la zone champ de texte. ❖ Pour déterminer quand la validation se produit, ajoutez un paramètre validateOn au constructeur, comme suit :


SPRY 64 Guide de l'utilisateur

<script type="text/javascript"> var sprytextarea1 = new Spry.Widget.ValidationTextarea("sprytextarea1", {validateOn:["blur"]}); </script>

Vous pouvez vous passer de parenthèses si votre paramètre validateOn contient une seule valeur (par exemple validateOn: "blur"). Par contre, si le paramètre contient les deux valeurs (validateOn:["blur", "change"]), la syntaxe doit comporter des parenthèses.

Définition d'un nombre minimal et maximal de caractères ❖ Pour définir un nombre minimal ou maximal de caractères, ajoutez la propriété minChars ou maxChars (ou les deux) et une valeur au constructeur, comme suit : <script type="text/javascript"> var textareawidget1 = new Spry.Widget.ValidationTextarea("textareawidget1",{minChars:value, maxChars:value}); </script>

Ajout d'un compteur de caractères Vous pouvez ajouter un compteur de caractères qui indique à l'utilisateur combien de caractères il a tapé ou combien il lui reste de caractères lorsqu'il entre du texte dans la zone de texte. 1 Ajoutez une balise span après la balise textarea du widget, puis attribuez un ID unique à la balise, comme suit : <form id="form1" name="form1" method="post" action=""> <span id="sprytextarea1"> <textarea name="textarea1" id="textarea1" cols="45" rows="5"></textarea> <span id="my_counter_span"></span> <span class="textareaRequiredMsg">Maximum number of characters exceeded</span> </span> </form> <script type="text/javascript"> var sprytextarea1 = new Spry.Widget.ValidationTextarea("sprytextarea1" {maxChars:100}); </script>

Laissez la nouvelle balise vide. Spry fournira le contenu de cette balise plus tard, lorsque l'utilisateur tapera du texte. Remarque : La balise de compteur doit se trouver à l'intérieur de la balise conteneur HTML du widget. 2 Ajoutez l'option counterType et une valeur au constructeur du widget, comme suit : <form id="form1" name="form1" method="post" action=""> <span id="sprytextarea1"> <textarea name="textarea1" id="textarea1" cols="45" rows="5"></textarea> <span id="my_counter_span"></span> <span class="textareaRequiredMsg">Maximum number of characters exceeded</span> </span> </form> <script type="text/javascript"> var sprytextarea1 = new Spry.Widget.ValidationTextarea("sprytextarea1" {maxChars:100, counterType:"chars_remaining"}); </script>

L'option counterType définit le type de compteur à utiliser. Elle peut accepter deux valeurs : "chars_count" ou "chars_remaining". La valeur "chars_count" produit un compteur qui compte le nombre de caractères tapés dans la zone de texte. La valeur "chars_remaining" produit pour sa part un compteur qui affiche le nombre de caractères restants avant que le nombre maximal de caractères soit atteint. La seconde option doit être utilisée en combinaison avec l'option maxChars, comme dans l'exemple précédent. Pour plus d'informations, consultez la section « Définition d'un nombre minimal et maximal de caractères » à la page 64. 3 Ajoutez l'option counterId au constructeur du widget et fixez sa valeur à l'ID unique que vous avez attribué à la balise span du compteur , comme suit :


SPRY 65 Guide de l'utilisateur

<form id="form1" name="form1" method="post" action=""> <span id="sprytextarea1"> <textarea name="textarea1" id="textarea1" cols="45" rows="5"></textarea> <span id="my_counter_span"></span> <span class="textareaRequiredMsg">Maximum number of characters exceeded</span> </span> </form> <script type="text/javascript"> var sprytextarea1 = new Spry.Widget.ValidationTextarea("sprytextarea1" {maxChars:100, counterType:"chars_remaining", counterId:"my_counter_span"}); </script>

Modification de l'état obligatoire d'une zone de texte Par défaut, le widget Zone de texte de validation exige une saisie par l'utilisateur lorsqu'il est publié sur une page Web. Vous pouvez toutefois rendre la saisie de texte dans certaines zones facultative pour l'utilisateur. ❖ Pour modifier l'état obligatoire d'une zone de texte, ajoutez la propriété isRequired au constructeur et fixez sa valeur à "false", comme suit : <script type="text/javascript"> var textareawidget1 = new Spry.Widget.ValidationTextarea("textareawidget1", {isRequired:false}); </script>

Création d'un conseil pour une zone de texte L'option hint permet d'ajouter un conseil pour indiquer aux utilisateurs le type d'informations qu'ils doivent entrer (par exemple « Entrez votre adresse ici ») . Le conseil s'affiche dans la zone de texte lorsque l'utilisateur charge la page dans un navigateur, s'il n'existe aucune valeur prédéfinie. ❖ Pour créer un conseil pour une zone de texte, ajoutez la propriété hint au constructeur, avec comme valeur le texte du

conseil, comme suit : <script type="text/javascript"> var textareawidget1 = new Spry.Widget.ValidationTextarea("textareawidget1", {hint:"Enter your address here"}); </script>

Blocage des caractères supplémentaires Vous pouvez empêcher les utilisateurs d'entrer davantage de caractères que le nombre maximal admis dans un widget Zone de texte de validation. Par exemple, si vous configurez l'option useCharacterMasking de sorte qu'un widget n'accepte pas plus de 20 caractères, l'utilisateur ne pourra pas taper plus de 20 caractères dans la zone de texte. Cette option s'emploie en combinaison avec l'option maxChars. Pour plus d'informations, consultez la section « Définition d'un nombre minimal et maximal de caractères » à la page 64. ❖ Pour bloquer les caractères excédentaires, ajoutez la propriété useCharacterMasking au constructeur et fixez sa valeur à true, comme suit : <script type="text/javascript"> var textareawidget1 = new Spry.Widget.ValidationTextarea("textareawidget1", maxChars:20, {useCharacterMasking:true}); </script>

Personnalisation du widget Zone de texte de validation Le fichier SpryValidationTextarea.css fournit le style par défaut du widget Zone de texte de validation. Vous pouvez toutefois personnaliser ce widget en modifiant la règle CSS appropriée. Les règles CSS du fichier SpryValidationTextarea.css emploient les mêmes noms de classes que les éléments associés du code HTML du widget. Vous pouvez ainsi déterminer aisément quelles règles CSS correspondent au widget et à ses états d'erreur. Le fichier SpryValidationTextarea.css doit déjà être placé sur votre site Web avant que vous entamiez des activités de personnalisation. Pour plus d'informations, consultez la section « Préparation des fichiers » à la page 3.


SPRY 66 Guide de l'utilisateur

Définition du style du widget Zone de texte de validation (instructions générales)

1 Ouvrez le fichier SpryValidationTextarea.css. 2 Accédez à la règle CSS pour la partie du widget à modifier. Par exemple, pour modifier la couleur d'arrière-plan de l'état obligatoire du widget Zone de texte, modifiez la règle textareaRequiredState dans le fichier CSS. 3 Apportez les modifications désirées à la règle CSS puis enregistrez le fichier. Le fichier SpryValidationTextarea.css contient de nombreux commentaires qui expliquent le code et le rôle de certaines règles. Pour plus d'informations, consultez les commentaires dans le fichier. Définition du style du texte de message d'erreur d'un widget Zone de texte de validation

Par défaut, les messages d'erreur du widget Zone de texte de validation s'affichent en rouge, entourés d'un bord plein de 1 pixel d'épaisseur. ❖ Pour modifier le style des messages d'erreur d'un widget Zone de texte de validation, recherchez la règle CSS appropriée dans le tableau suivant, puis modifiez les propriétés par défaut ou ajoutez vos propriétés et valeurs de style du texte. Texte à modifier

Règle CSS pertinente

Propriétés à modifier

Texte de message d'erreur

.textareaRequiredState .textareaRequiredMsg, .textareaMinCharsState .textareaMinCharsMsg, .textareaMaxCharsState .textareaMaxCharsMsg

color: #CC3333; border: 1px solid #CC3333;

Modification des couleurs d'arrière-plan du widget Zone de texte de validation ❖ Pour modifier les couleurs d'arrière-plan du widget Zone de texte de validation dans différents états, recherchez la règle CSS appropriée dans le tableau suivant, puis modifiez la couleur d'arrière-plan par défaut. Couleur d'arrière-plan à modifier

Règle CSS pertinente

Propriété à modifier

Couleur d'arrière-plan du widget dans un état valide

.textareaValidState textarea, textarea.textareaValidState

background-color: #B8F5B1;

Couleur d'arrière-plan du widget dans un état non valide

textarea.textareaRequiredState, .textareaRequiredState textarea, textarea.textareaMinCharsState, .textareaMinCharsState textarea, textarea.textareaMaxCharsState, .textareaMaxCharsState textarea

background-color: #FF9F9F;

Couleur d'arrière-plan du widget actif

.textareaFocusState textarea, textarea.textareaFocusState

background-color: #FFFFCC;

Personnalisation des noms de classes associées aux états

Bien qu'il soit possible de remplacer des noms de classes associées aux messages d'erreur par des noms personnalisés en modifiant les règles dans le code CSS et les noms des classes dans le code HTML, vous ne pouvez pas modifier ni remplacer des noms de classes associées à des états. Les comportements sont en effet incorporés au cadre applicatif Spry. Vous pouvez toutefois remplacer le nom par défaut d'une classe associée à un état par le nom de votre choix en définissant une nouvelle valeur dans le troisième paramètre du constructeur du widget. ❖ Pour modifier des noms de classes associés à l'état d'un widget, ajoutez l'une des options de remplacement au troisième paramètre du constructeur du widget, puis définissez le nom de votre choix, comme suit : <script type="text/javascript"> var sprytextarea1 = new Spry.Widget.ValidationTextarea("sprytextarea1", {requiredClass:"required"}); </script>

Le tableau suivant fournit la liste des options que vous pouvez utiliser pour remplacer les noms intégrés des classes associées aux états.


SPRY 67 Guide de l'utilisateur

Option

Description

requiredClass

Supplante la valeur prédéfinie "textareaRequiredState".

validClass

Supplante la valeur prédéfinie "textareaValidState".

focusClass

Supplante la valeur prédéfinie "textareaFocusState".

invalidCharsMinClass

Supplante la valeur prédéfinie "textareaMinCharsState".

invalidCharsMaxClass

Supplante la valeur prédéfinie "textareaMaxCharsState".

textareaFlashTextClass

Supplante la valeur prédéfinie "textareaFlashText".

Utilisation du widget Validation de la sélection Présentation et structure du widget Validation de la sélection Un widget Validation de la sélection Spry est un menu déroulant qui affiche des états valides ou non valides lorsque l'utilisateur effectue une sélection. Par exemple, vous pouvez insérer un widget Validation de la sélection contenant une liste d'états, regroupés en différentes sections et séparés par des lignes horizontales. Si l'utilisateur sélectionne par erreur l'une des lignes de séparation au lieu d'un des états, le widget Validation de la sélection affiche un message pour indiquer que la sélection n'est pas valide. L'exemple suivant montre un widget Validation de la sélection développé, ainsi que la forme réduite de ce widget dans divers états. B

C

D

A

A. Widget Validation de la sélection activé B. Widget Validation de la sélection, état valide C. Widget Validation de la sélection, état obligatoire D. Widget Validation de la sélection, état non valide

Le widget Validation de la sélection peut posséder divers états (par exemple valide, non valide, valeur obligatoire, etc.). Vous pouvez modifier les propriétés de ces états à l'aide de l'inspecteur Propriétés, en fonction des résultats de validation désirés. Un widget Validation de la sélection peut effectuer une validation à différents moments, par exemple lorsque le visiteur clique en dehors du widget, pendant qu'il effectue une sélection ou lorsqu'il tente d'envoyer le formulaire. Etat initial Lorsque la page se charge dans le navigateur, ou lorsque l'utilisateur réinitialise le formulaire. Etat actif Lorsque le visiteur clique sur le widget Etat valide Lorsque l'utilisateur a sélectionné un élément valide, ce qui permet l'envoi du formulaire. Etat non valide Lorsque l'utilisateur a sélectionné un élément non valide. Etat obligatoire Lorsque l'utilisateur n'a pas sélectionné d'élément valide.

Lorsqu'un widget Validation de la sélection passe dans l'un des états précédents suite à l'interaction avec l'utilisateur, la logique du cadre Spry applique une classe CSS spécifique au conteneur HTML pour le widget lors de l'exécution. Par exemple, si un utilisateur tente d'envoyer un formulaire mais n'a pas sélectionné d'élément dans le menu, Spry applique au widget une classe qui le force à afficher le message d'erreur « Vous devez sélectionner un élément ». Les règles qui contrôlent le style et les états d'affichage de messages d'erreur se trouvent dans le fichier qui accompagne le widget, SpryValidationSelect.css.


SPRY 68 Guide de l'utilisateur

Le code HTML par défaut du widget Validation de la sélection, généralement dans un formulaire, contient une balise conteneur span qui entoure la balise select de la zone de texte. Le code HTML du widget Validation de la sélection comprend également des balises script dans l'en-tête du document et après le code HTML du widget. La balise script dans l'en-tête du document définit toutes les fonctions JavaScript relatives au widget Sélection. La balise script qui suit le code du widget crée un objet JavaScript qui rend le widget interactif. Voici le code HTML d'un widget Validation de la sélection : <head> ... <!-- Link the Spry Validation Select JavaScript library --> <script src="SpryAssets/SpryValidationSelect.js" type="text/javascript"></script> <!-- Link the CSS style sheet that styles the widget --> <link href="SpryAssets/SpryValidationSelect.css" rel="stylesheet" type="text/css" /> </head> <body> <form id="form1" name="form1" method="post" action=""> <!-- Create the select widget and assign a unique id--> <span id="spryselect1"> <select name="select1" id="select1"> <!-- Add items and values to the widget--> <option>--Please select an item--</option> <option value="item1">Item 1</option> <option value="item2">Item 2</option> <option value="-1">Invalid Item</option> <option value="item3">Item 3</option> <option>Empty Item</option> </select> <!--Add an error message--> <span class="selectRequiredMsg">Please select an item.</span> </span> </form> <!-- Initialize the Validation Select widget object--> <script type="text/javascript"> var spryselect1 = new Spry.Widget.ValidationSelect("spryselect1"); </script> </body>

Dans le code, l'opérateur JavaScript new initialise l'objet widget Sélection et transforme le contenu span possédant l'ID spryselect1, qui était un code HTML statique, en un élément de page interactif. La balise span du message d'erreur dans le widget comporte une classe CSS qui y est appliquée. Cette classe (fixée à display:none; par défaut) détermine le style et la visibilité du message d'erreur. Elle se trouve dans le fichier CSS joint,

SpryValidationSelect.css. Lorsque le widget passe dans un état différent suite à l'interaction avec l'utilisateur, Spry applique une classe différente au conteneur du widget, ce qui influe sur la classe de message d'erreur. Pour ajouter d'autres messages d'erreur à un widget Validation de la sélection, créez une balise span (ou tout autre type de balise) qui en contiendra le texte. Ensuite, en lui appliquant une classe CSS, vous pouvez afficher ou masquer le message en fonction de l'état du widget. Vous pouvez modifier l'apparence par défaut des états du widget Validation de la sélection en modifiant la règle CSS correspondante dans le fichier SpryValidationSelect.css. Par exemple, pour modifier la couleur d'arrière-plan en fonction d'un état, modifiez la règle correspondante ou ajoutez-en une nouvelle (si elle n'existe pas encore) dans la feuille de style. Variation des balises utilisées pour la structure du widget Sélection

Dans l'exemple précédent, des balises span servent à créer la structure du widget : Container SPAN SELECT tag Error message SPAN

Il est toutefois possible d'employer à peu près n'importe quelle balise conteneur pour créer un widget.


SPRY 69 Guide de l'utilisateur

Container DIV SELECT tag Error Message P

Spry utilise l'ID de balise (et pas la balise proprement dite) pour créer le widget. Spry affiche également les messages d'erreur à l'aide de code CSS qui ne varie pas selon la balise qui contient les messages en question. L'ID transmis au constructeur du widget identifie un élément HTML spécifique. Le constructeur trouve cet élément et recherche, dans le conteneur identifié, la balise select correspondante. Si l'ID transmis au constructeur est l'ID de la balise select (au lieu d'une balise conteneur), le constructeur joint directement des déclencheurs de validation à la balise select. Par contre, si aucune balise conteneur n'est présente, le widget ne peut pas afficher les messages d'erreur. Les divers états de validation se bornent à modifier l'apparence de l'élément de balise select (par exemple sa couleur d'arrière-plan). Remarque : Les balises select multiples ne fonctionnent pas à l'intérieur d'un même conteneur de widget HTML. Chaque liste de sélection doit être son propre widget.

Code CSS pour le widget Validation de la sélection Le fichier SpryValidationSelect.css contient les règles qui définissent le style du widget Validation de la sélection et de ses messages d'erreur. Vous pouvez modifier ces règles afin de définir l'apparence du widget et des messages d'erreur. Les noms des règles dans le fichier CSS correspondent aux noms des classes définies dans le code HTML du widget. Le code CSS du fichier SpryValidationSelect.css est le suivant : /*Validation Select styling classes*/ .selectRequiredMsg, .selectInvalidMsg { display: none; } .selectRequiredState .selectRequiredMsg, .selectInvalidState .selectInvalidMsg { display: inline; color: #CC3333; border: 1px solid #CC3333; } .selectValidState select, select.selectValidState { background-color: #B8F5B1; } select.selectRequiredState, .selectRequiredState select, select.selectInvalidState, .selectInvalidState select { background-color: #FF9F9F; } .selectFocusState select, select.selectFocusState { background-color: #FFFFCC; }

Le fichier SpryValidationSelect.css contient également de nombreux commentaires qui expliquent le code et le rôle de certaines règles. Pour plus d'informations, consultez les commentaires dans le fichier.

Insertion du widget Validation de la sélection 1 Recherchez le fichier SpryValidationSelect.css et ajoutez-le à votre site Web. Le fichier SpryValidationSelect.js se trouve dans le répertoire widgets/selectvalidation qui figure dans le répertoire Spry téléchargé depuis le site Adobe Labs. Pour plus d'informations, consultez la section « Préparation des fichiers » à la page 3. Par exemple, créez un dossier nommé SpryAssets dans le dossier racine de votre site Web, puis déplacez-y le fichier SpryValidationSelect.js. Le fichier SpryValidationSelect.js contient toutes les informations qui rendent le widget Sélection interactif. 2 Recherchez le fichier SpryValidationSelect.css et ajoutez-le à votre site Web. Vous pouvez l'ajouter dans le répertoire principal, dans un répertoire SpryAssets ou dans un répertoire CSS, si vous en avez créé un. 3 Ouvrez la page Web à laquelle ajouter le widget Sélection puis liez le fichier SpryValidationSelect.js à la page en insérant la balise script suivante dans la balise "head" de la page : <script src="SpryAssets/SpryValidationSelect.js" type="text/javascript"></script>


SPRY 70 Guide de l'utilisateur

Assurez-vous que le chemin d'accès au fichier SpryValidationSelect.css est bien correct. Ce chemin d'accès varie selon l'endroit où vous avez placé le fichier dans votre site Web. 4 Liez le fichier SpryValidationSelect.css à votre page Web en insérant la balise link suivante dans la balise "head" de la page : <link href="SpryAssets/SpryValidationSelect.css" rel="stylesheet" type="text/css" />

Assurez-vous que le chemin d'accès au fichier SpryValidationSelect.js est bien correct. Ce chemin d'accès varie selon l'endroit où vous avez placé le fichier dans votre site Web. 5 Ajoutez une liste de sélection à la page, puis attribuez-lui un nom et un ID unique : <select name="myselect" id="myselect"></select>

6 Ajoutez des options à la liste de sélection, comme suit : <select name="myselect" id="myselect"> <option>--Please select an item--</option> <option value="item1">Item 1</option> <option value="item2">Item 2</option> <option value="-1">Invalid Item</option> <option value="item3">Item 3</option> <option>Empty Item</option> </select>

7 Pour ajouter un conteneur autour de la liste de sélection, insérez des balises span autour des balises select, puis attribuez un ID unique au widget, comme suit : <span id="spryselect1"> <select name="myselect" id="myselect"> <option>--Please select an item--</option> <option value="item1">Item 1</option> <option value="item2">Item 2</option> <option value="-1">Invalid Item</option> <option value="item3">Item 3</option> <option>Empty Item</option> </select> </span>

8 Pour initialiser l'objet Validation de la sélection Spry, insérez le bloc script suivant après le code HTML du widget : <script type="text/javascript"> var spryselect1 = new Spry.Widget.ValidationSelect("spryselect1"); </script>

L'opérateur JavaScript new initialise l'objet widget Sélection et transforme le contenu span possédant l'ID spryselect1, qui était un code HTML statique, en un objet Sélection interactif. La méthode Spry.Widget.ValidationSelect est un constructeur du cadre applicatif Spry qui crée des objets Sélection. Les informations requises pour l'initialisation de l'objet figurent dans la bibliothèque JavaScript SpryValidationSelect.js que vous avez liée au début de cette procédure. Assurez-vous que l'ID de la balise span de la liste de sélection corresponde au paramètre ID spécifié dans la méthode "Spry.Widgets.ValidationSelect". Assurez-vous que l'appel JavaScript se trouve bien après le code HTML du widget. 9 Enregistrez la page. Le code complet ressemble à ce qui suit :


SPRY 71 Guide de l'utilisateur

<head> ... <script src="SpryAssets/SpryValidationSelect.js" type="text/javascript"></script> <link href="SpryAssets/SpryValidationSelect.css" rel="stylesheet" type="text/css" /> </head> <body> <span id="spryselect1"> <select name="myselect" id="myselect"> <option>--Please select an item--</option> <option value="item1">Item 1</option> <option value="item2">Item 2</option> <option value="-1">Invalid Item</option> <option value="item3">Item 3</option> <option>Empty Item</option> </select> </span> <script type="text/javascript"> var spryselect1 = new Spry.Widget.ValidationSelect("spryselect1"); </script> </body>

Affichage de messages d'erreur ❖ Créez une balise span (ou tout autre type de balise) pour afficher le message d'erreur, et attribuez-lui la classe appropriée, comme suit : <span id="spryselect1"> <select name="select1" id="select1"> <option>--Please select an item--</option> <option value="item1">Item 1</option> . . . </select> <span class="selectRequiredMsg">Please select an item.</span> </span>

La règle selectRequiredMsg se trouve dans le fichier SpryValidationSelect.css et est fixée àdisplay:none par défaut. Lorsque le widget passe dans un état différent suite à l'interaction avec l'utilisateur, Spry applique la classe appropriée (la classe d'état) au conteneur du widget. Cette action influe sur la classe du message d'erreur et, dès lors, sur l'apparence de ce message. Par exemple, voici une partie de la règle CSS du fichier SpryValidationSelect.css : .selectRequiredMsg, .selectInvalidMsg { display: none; } .selectRequiredState .selectRequiredMsg, .selectInvalidState .selectInvalidMsg { display: inline; color: #CC3333; border: 1px solid #CC3333; }

Par défaut, aucune classe d'état n'est appliquée au conteneur du widget. Dès lors, lorsque la page est chargée dans un navigateur, seule la classe .selectRequiredMsg est appliquée au texte du message d'erreur présenté dans l'exemple de code HTML précédent. La paire propriété/valeur pour cette règle étant display:none, le message reste masqué. Toutefois, si l'utilisateur n'a pas effectué de sélection, Spry applique la classe appropriée au conteneur du widget, comme suit : <span id="spryselect1" class="selectRequiredState"> <select name="select1" id="select1"> <option>--Please select an item--</option> <option value="item1">Item 1</option> . . . </select> <span class="selectRequiredMsg">Please select an item.</span> </span>


SPRY 72 Guide de l'utilisateur

Dans le code CSS précédent, la règle d'état avec le sélecteur contextuel .selectRequiredState . selectRequiredMsg supplante la règle de message d'erreur par défaut, qui masquait le texte du message. Dès lors, lorsque Spry applique la classe d'état au conteneur du widget, la règle d'état détermine l'apparence du widget et affiche le message d'erreur en ligne, en rouge, encadré d'une bordure pleine de 1 pixel d'épaisseur. La liste suivante présente les classes de messages d'erreur par défaut et leurs descriptions. Vous pouvez modifier ces classes et les renommer. Dans ce cas, n'oubliez pas de les modifier également dans le sélecteur contextuel. Classe de message d'erreur

Description

.selectRequiredMsg

Force l'affichage du message d'erreur lorsque le widget accède à l'état "obligatoire".

.selectInvalidMsg

Force l'affichage du message d'erreur lorsque le widget accède à l'état "non valide".

Remarque : Il est impossible de renommer les classes associées aux états, car elles sont incorporées au cadre applicatif Spry.

Définition du moment de validation Par défaut, le widget Validation de la sélection effectue sa validation lorsque l'utilisateur clique sur le bouton d'envoi. Vous pouvez toutefois définir deux autres options : blur ou change. Le paramètre validateOn:["blur"] force le widget à procéder à la validation quand l'utilisateur clique en dehors de la liste de sélection. Le paramètre validateOn:["change"] force le widget à procéder à la validation lorsque l'utilisateur effectue des sélections. ❖ Pour déterminer quand la validation se produit, ajoutez un paramètre validateOn au constructeur, comme suit : <script type="text/javascript"> var spryselect1 = new Spry.Widget.ValidationSelect("spryselect1", {validateOn:["blur"]}); </script>

Vous pouvez vous passer de parenthèses si votre paramètre validateOn contient une seule valeur (par exemple validateOn: "blur"). Par contre, si le paramètre contient les deux valeurs (validateOn:["blur", "change"]), la syntaxe doit comporter des parenthèses.

Modification de l'état obligatoire d'une liste de sélection Par défaut, les widgets Validation de la sélection exigent que l'utilisateur effectue une sélection avant d'envoyer le formulaire. Vous pouvez toutefois stipuler que certaines sélections sont facultatives pour l'utilisateur. ❖ Pour modifier l'état obligatoire d'une liste de sélection, ajoutez la propriété isRequired au constructeur et fixez sa valeur à "false", comme suit : <script type="text/javascript"> var selectwidget1 = new Spry.Widget.ValidationSelect("selectwidget1", {isRequired:false}); </script>

Spécification d'une valeur incorrecte Vous pouvez définir une valeur qui est considérée comme non valide si l'utilisateur sélectionne un élément de menu associé à cette valeur. Par exemple, si vous définissez -1 comme valeur non valide et si vous l'attribuez à une balise d'option, le widget affiche un message d'erreur si l'utilisateur sélectionne cet élément de menu. 1 Attribuez une valeur négative à une balise d'option, par exemple : <option value="-1"> ------------------- </option>

2 Ajoutez l'option non valide et la valeur que vous avez spécifiée au constructeur du widget, comme suit : <script type="text/javascript"> var selectwidget1 = new Spry.Widget.ValidationSelect("selectwidget1", {invalidValue:"-1"}); </script>


SPRY 73 Guide de l'utilisateur

Personnalisation du widget Validation de la sélection Le fichier SpryValidationSelect.css fournit le style par défaut du widget Validation de la sélection. Vous pouvez toutefois personnaliser ce widget en modifiant la règle CSS appropriée. Les règles CSS du fichier SpryValidationSelect.css emploient les mêmes noms de classes que les éléments associés du code HTML du widget. Vous pouvez ainsi déterminer aisément quelles règles CSS correspondent au widget et à ses états d'erreur. Le fichier SpryValidationSelect.css doit déjà être placé sur votre site Web avant que vous entamiez des activités de personnalisation. Pour plus d'informations, consultez la section « Préparation des fichiers » à la page 3. Définition du style du widget Validation de la sélection (instructions générales)

1 Ouvrez le fichier SpryValidationSelect.css. 2 Accédez à la règle CSS pour la partie du widget à modifier. Par exemple, pour modifier la couleur d'arrière-plan de l'état obligatoire du widget Validation de la sélection, modifiez la règle .selectRequiredState dans le fichier CSS. 3 Apportez les modifications désirées à la règle CSS puis enregistrez le fichier. Le fichier SpryValidationSelect.css contient de nombreux commentaires qui expliquent le code et le rôle de certaines règles. Pour plus d'informations, consultez les commentaires dans le fichier. Définition du style du texte de message d'erreur d'un widget Validation de la sélection

Par défaut, les messages d'erreur du widget Validation de la sélection s'affichent en rouge, entourés d'un bord plein de 1 pixel d'épaisseur. ❖ Pour modifier le style des messages d'erreur d'un widget Validation de la sélection, recherchez la règle CSS appropriée dans le tableau suivant, puis modifiez les propriétés par défaut ou ajoutez vos propriétés et valeurs de style du texte. Texte à mettre en forme

Règle CSS pertinente

Propriétés à modifier

Texte de message d'erreur

.selectRequiredState .selectRequiredMsg, .selectInvalidState .selectInvalidMsg

color: #CC3333; border: 1px solid #CC3333;

Modification des couleurs d'arrière-plan du widget Validation de la sélection ❖ Pour modifier les couleurs d'arrière-plan du widget Validation de la sélection dans différents états, recherchez la règle CSS appropriée dans le tableau suivant, puis modifiez la couleur d'arrière-plan par défaut. Couleur d'arrière-plan à modifier

Règle CSS pertinente

Propriété à modifier

Couleur d'arrière-plan du widget dans un état valide

.selectValidState select, select.selectValidState

background-color: #B8F5B1;

Couleur d'arrière-plan du widget dans un état non valide

select.selectRequiredState, .selectRequiredState select, select.selectInvalidState, .selectInvalidState select

background-color: #FF9F9F;

Couleur d'arrière-plan du widget actif

.selectFocusState select, select.selectFocusState

background-color: #FFFFCC;

Personnalisation des noms de classes associées aux états

Bien qu'il soit possible de remplacer des noms de classes associées aux messages d'erreur par des noms personnalisés en modifiant les règles dans le code CSS et les noms des classes dans le code HTML, vous ne pouvez pas modifier ni remplacer des noms de classes associées à des états. Les comportements sont en effet incorporés au cadre applicatif Spry. Vous pouvez toutefois remplacer le nom par défaut d'une classe associée à un état par le nom de votre choix en définissant une nouvelle valeur dans le troisième paramètre du constructeur du widget. ❖ Pour modifier des noms de classes associés à l'état d'un widget, ajoutez l'une des options de remplacement au troisième paramètre du constructeur du widget, puis définissez le nom de votre choix, comme suit : <script type="text/javascript"> var spryselect1 = new Spry.Widget.ValidationSelect("spryselect1", {requiredClass:"required"}); </script>


SPRY 74 Guide de l'utilisateur

Le tableau suivant fournit la liste des options que vous pouvez utiliser pour remplacer les noms intégrés des classes associées aux états. Option

Description

requiredClass

Supplante la valeur prédéfinie "selectRequiredState".

validClass

Supplante la valeur prédéfinie "selectValidState".

focusClass

Supplante la valeur prédéfinie "selectFocusState".

invalidClass

Supplante la valeur prédéfinie "selectInvalidState".

Utilisation du widget Validation de case à cocher Présentation et structure du widget Validation de case à cocher Le widget Validation de case à cocher Spry est une case à cocher ou un groupe de cases à cocher, dans un formulaire HTML, qui affiche des états valides ou non valide lorsque l'utilisateur active ou n'active pas une case à cocher. Par exemple, vous pouvez ajouter un widget Validation de case à cocher à un formulaire dans lequel l'utilisateur doit effectuer trois sélections. Si l'utilisateur n'effectue pas ces trois sélections, le widget renvoie un message indiquant que le nombre minimal de sélections n'a pas été effectué. L'exemple suivant montre un widget Validation de case à cocher dans différents états.

A

B

A. Groupe de widgets Validation de case à cocher, nombre minimal de sélections B. Widget Validation de case à cocher, état obligatoire

Le widget Validation de case à cocher peut posséder divers états (par exemple valide, non valide, valeur obligatoire, etc.). Vous pouvez modifier les propriétés de ces états à l'aide de l'inspecteur Propriétés, en fonction des résultats de validation désirés. Un widget Validation de case à cocher peut effectuer une validation à différents moments, par exemple lorsque le visiteur clique en dehors du widget, pendant qu'il effectue une sélection ou lorsqu'il tente d'envoyer le formulaire. Etat initial Lorsque la page se charge dans le navigateur, ou lorsque l'utilisateur réinitialise le formulaire. Etat valide Lorsque l'utilisateur a effectué une sélection ou le nombre correct de sélections, ce qui permet l'envoi du

formulaire. Etat obligatoire Lorsque l'utilisateur n'a pas effectué une sélection obligatoire. Nombre minimal de sélections Lorsque l'utilisateur a sélectionné moins de cases à cocher que le nombre minimal requis. Nombre maximal de sélections Lorsque l'utilisateur a sélectionné plus de cases à cocher que le nombre maximal admis.

Lorsqu'un widget Validation de case à cocher passe dans l'un de ces états suite à l'interaction avec l'utilisateur, la logique du cadre Spry applique une classe CSS spécifique au conteneur HTML pour le widget lors de l'exécution. Par exemple, si un utilisateur tente d'envoyer un formulaire mais n'a pas effectué de sélections, Spry applique au widget une classe qui le force à afficher le message d'erreur « Vous devez effectuer une sélection ». Les règles qui contrôlent le style et les états d'affichage de messages d'erreur se trouvent dans le fichier qui accompagne le widget, SpryValidationCheckbox.css.


SPRY 75 Guide de l'utilisateur

Le code HTML par défaut du widget Validation de case à cocher, généralement dans un formulaire, contient une balise conteneur span qui entoure la balise input type="checkbox" de la case à cocher. Le code HTML du widget Validation de case à cocher comprend également des balises script dans l'en-tête du document et après le code HTML du widget. La balise script dans l'en-tête du document définit toutes les fonctions JavaScript relatives au widget Case à cocher. La balise script qui suit le code du widget crée un objet JavaScript qui rend la case à cocher interactive. Voici le code HTML d'un widget Validation de case à cocher : <head> ... <!-- Link the Spry Validation Checkbox JavaScript library --> <script src="SpryAssets/SpryValidationCheckbox.js" type="text/javascript"></script> <!-- Link the CSS style sheet that styles the widget --> <link href="SpryAssets/SpryValidationCheckbox.css" rel="stylesheet" type="text/css" /> </head> <body> <form id="form1" name="form1" method="post" action=""> <!-- Create the checkbox widget and assign a unique id--> <span id="sprycheckbox1"> <input type="checkbox" name="checkbox1" value="1"/> <input type="checkbox" name="checkbox2" value="2"/> <!--Add an error message--> <span class="checkboxRequiredMsg">Please make a selection.</span> </span> </form> <!-- Initialize the Validation Checkbox widget object--> <script type="text/javascript"> var sprycheckbox1 = new Spry.Widget.ValidationCheckbox("sprycheckbox1"); </script> </body>

Dans le code, l'opérateur JavaScript new initialise l'objet widget Case à cocher et transforme le contenu span possédant l'ID sprycheckbox1, qui était un code HTML statique, en un élément de page interactif. La balise span du message d'erreur dans le widget comporte une classe CSS qui y est appliquée. Cette classe (fixée à display:none; par défaut) détermine le style et la visibilité du message d'erreur. Elle se trouve dans le fichier CSS joint, SpryValidationCheckbox.css. Lorsque le widget passe dans un état différent suite à l'interaction avec l'utilisateur, Spry applique une classe différente au conteneur du widget, ce qui influe sur la classe de message d'erreur. Pour ajouter d'autres messages d'erreur à un widget Validation de case à cocher, créez une balise span (ou tout autre type de balise) qui en contiendra le texte. Ensuite, en lui appliquant une classe CSS, vous pouvez afficher ou masquer le message en fonction de l'état du widget. Vous pouvez modifier l'apparence par défaut des états du widget Validation de case à cocher en modifiant la règle CSS correspondante dans le fichier SpryValidationCheckbox.css. Par exemple, pour modifier la couleur d'arrière-plan en fonction d'un état, modifiez la règle correspondante ou ajoutez-en une nouvelle (si elle n'existe pas encore) dans la feuille de style. Variation des balises utilisées pour la structure du widget Validation de case à cocher

Dans l'exemple précédent, des balises span servent à créer la structure du widget : Container SPAN INPUT type="checkbox" Error message SPAN

Il est toutefois possible d'employer à peu près n'importe quelle balise conteneur pour créer un widget. Container DIV INPUT type="checkbox" Error Message P

Spry utilise l'ID de balise (et pas la balise proprement dite) pour créer le widget. Spry affiche également les messages d'erreur à l'aide de code CSS qui ne varie pas selon la balise qui contient les messages en question.


SPRY 76 Guide de l'utilisateur

L'ID transmis au constructeur du widget identifie un élément HTML spécifique. Le constructeur trouve cet élément et recherche, dans le conteneur identifié, la balise input correspondante. Si l'ID transmis au constructeur est l'ID de la balise input (au lieu d'une balise conteneur), le constructeur joint directement des déclencheurs de validation à la balise input. Par contre, si aucune balise conteneur n'est présente, le widget ne peut pas afficher les messages d'erreur. Les divers états de validation se bornent à modifier l'apparence de l'élément de balise input (par exemple sa couleur d'arrière-plan).

Code CSS pour le widget Validation de case à cocher Le fichier SpryValidationCheckbox.css contient les règles qui définissent le style du widget Validation de case à cocher et de ses messages d'erreur. Vous pouvez modifier ces règles afin de définir l'apparence du widget et des messages d'erreur. Les noms des règles dans le fichier CSS correspondent aux noms des classes définies dans le code HTML du widget. Le code CSS du fichier SpryValidationCheckbox.css est le suivant : /*Validation Checkbox styling classes*/ .checkboxRequiredMsg, .checkboxMinSelectionsMsg, .checkboxMaxSelectionsMsg{ display: none; } .checkboxRequiredState .checkboxRequiredMsg, .checkboxMinSelectionsState .checkboxMinSelectionsMsg, .checkboxMaxSelectionsState .checkboxMaxSelectionsMsg { display: inline; color: #CC3333; border: 1px solid #CC3333; }

Le fichier SpryValidationCheckbox.css contient également de nombreux commentaires qui expliquent le code et le rôle de certaines règles. Pour plus d'informations, consultez les commentaires dans le fichier.

Insertion du widget Validation de case à cocher 1 Recherchez le fichier SpryValidationCheckbox.js et ajoutez-le à votre site Web. Le fichier SpryValidationCheckbox.js se trouve dans le répertoire widgets/checkboxvalidation qui figure dans le répertoire Spry téléchargé depuis le site Adobe Labs. Pour plus d'informations, consultez la section « Préparation des fichiers » à la page 3. Par exemple, créez un dossier nommé SpryAssets dans le dossier racine de votre site Web, puis déplacez-y le fichier SpryValidationCheckbox.js. Le fichier SpryValidationCheckbox.js contient toutes les informations qui rendent le widget Case à cocher interactif. 2 Recherchez le fichier SpryValidationCheckbox.css et ajoutez-le à votre site Web. Vous pouvez l'ajouter dans le répertoire principal, dans un répertoire SpryAssets ou dans un répertoire CSS, si vous en avez créé un. 3 Ouvrez la page Web à laquelle ajouter le widget Case à cocher puis liez le fichier SpryValidationCheckbox.js à la page en insérant la balise script suivante dans la balise "head" de la page : <script src="SpryAssets/SpryValidationCheckbox.js" type="text/javascript"></script>

Assurez-vous que le chemin d'accès au fichier SpryValidationCheckbox.js est bien correct. Ce chemin d'accès varie selon l'endroit où vous avez placé le fichier dans votre site Web. 4 Liez le fichier SpryValidationCheckbox.css à votre page Web en insérant la balise link suivante dans la balise "head" de la page : <link href="SpryAssets/SpryValidationCheckbox.css" rel="stylesheet" type="text/css" />

Assurez-vous que le chemin d'accès au fichier SpryValidationCheckbox.css est bien correct. Ce chemin d'accès varie selon l'endroit où vous avez placé le fichier dans votre site Web. 5 Ajoutez des cases à cocher à la page puis attribuez-leur des noms et des valeurs. Vous pouvez ajouter autant de cases à cocher que vous le voulez. <input type="checkbox" name="checkbox1" value="1"/> <input type="checkbox" name="checkbox2" value="2"/>

6 Pour ajouter un conteneur autour des cases à cocher, insérez des balises span autour des balises input, puis attribuez un ID unique au widget, comme suit :


SPRY 77 Guide de l'utilisateur

<span id="sprycheckbox1"> <input type="checkbox" name="checkbox1" value="1"/> <input type="checkbox" name="checkbox2" value="2"/> </span>

7 Pour initialiser l'objet Validation de case à cocher Spry, insérez le bloc script suivant après le code HTML du widget : <script type="text/javascript"> var sprycheckbox1 = new Spry.Widget.ValidationCheckbox("sprycheckbox1"); </script>

L'opérateur JavaScript new initialise l'objet widget Case à cocher et transforme le contenu span possédant l'ID sprycheckbox1, qui était un code HTML statique, en un objet Case à cocher interactif. La méthode Spry.Widget.ValidationCheckbox est un constructeur du cadre applicatif Spry qui crée des objets Case à cocher. Les informations requises pour l'initialisation de l'objet figurent dans la bibliothèque JavaScript SpryValidationCheckbox.js que vous avez liée au début de cette procédure. Assurez-vous que l'ID de la balise span du widget Case à cocher corresponde au paramètre ID spécifié dans la méthode Spry.Widgets.ValidationCheckbox. Assurez-vous que l'appel JavaScript se trouve bien après le code HTML du widget.

8 Enregistrez la page. Le code complet ressemble à ce qui suit : <head> ... <script src="SpryAssets/SpryValidationCheckbox.js" type="text/javascript"></script> <link href="SpryAssets/SpryValidationCheckbox.css" rel="stylesheet" type="text/css" /> </head> <body> <span id="sprycheckbox1"> <input type="checkbox" name="checkbox1" value="1"/> <input type="checkbox" name="checkbox2" value="2"/> </span> <script type="text/javascript"> var sprycheckbox1 = new Spry.Widget.ValidationCheckbox("sprycheckbox1"); </script> </body>

Affichage de messages d'erreur ❖ Créez une balise span (ou tout autre type de balise) pour afficher le message d'erreur, et attribuez-lui la classe appropriée, comme suit : <span id="sprycheckbox1"> <input type="checkbox" name="checkbox1" value="1"/> <input type="checkbox" name="checkbox2" value="2"/> <span class="checkboxRequiredMsg">Please make a selection.</span> </span>

La règle checkboxRequiredMsg se trouve dans le fichier SpryValidationCheckbox.css et est fixée àdisplay:none par défaut. Lorsque le widget passe dans un état différent suite à l'interaction avec l'utilisateur, Spry applique la classe appropriée (la classe d'état) au conteneur du widget. Cette action influe sur la classe du message d'erreur et, dès lors, sur l'apparence de ce message. Par exemple, voici la règle CSS du fichier SpryValidationCheckbox.css : .checkboxRequiredMsg, .checkboxMinSelectionsMsg, .checkboxMaxSelectionsMsg{ display: none; } .checkboxRequiredState .checkboxRequiredMsg, .checkboxMinSelectionsState .checkboxMinSelectionsMsg, .checkboxMaxSelectionsState .checkboxMaxSelectionsMsg { display: inline; color: #CC3333; border: 1px solid #CC3333; }


SPRY 78 Guide de l'utilisateur

Par défaut, aucune classe d'état n'est appliquée au conteneur du widget. Dès lors, lorsque la page est chargée dans un navigateur, seule la classe checkboxRequiredMsg est appliquée au texte du message d'erreur présenté dans l'exemple de code HTML précédent. La paire propriété/valeur pour cette règle étant display:none, le message reste masqué. Toutefois, si l'utilisateur n'a pas effectué de sélection, Spry applique la classe appropriée au conteneur du widget, comme suit : <span id="sprycheckbox1" class="checkboxRequiredState"> <input type="checkbox" name="checkbox1" value="1"/> <input type="checkbox" name="checkbox2" value="2"/> <span class="checkboxRequiredMsg">Please make a selection.</span> </span>

Dans le code CSS précédent, la règle d'état avec le sélecteur contextuel .checkboxRequiredState .checkboxRequiredMsg supplante la règle de message d'erreur par défaut, qui masquait le texte du message. Dès lors, lorsque Spry applique la classe d'état au conteneur du widget, la règle d'état détermine l'apparence du widget et affiche le message d'erreur en ligne, en rouge, encadré d'une bordure pleine de 1 pixel d'épaisseur. La liste suivante présente les classes de messages d'erreur par défaut et leurs descriptions. Vous pouvez modifier ces classes et les renommer. Dans ce cas, n'oubliez pas de les modifier également dans le sélecteur contextuel. Classe de message d'erreur

Description

.checkboxRequiredMsg

Force l'affichage du message d'erreur lorsque le widget accède à l'état "obligatoire".

.checkboxMinSelectionsMsg

Force l'affichage du message d'erreur lorsque le widget accède à l'état "nombre minimal de sélections".

.checkboxMaxSelectionsMsg

Force l'affichage du message d'erreur lorsque le widget accède à l'état "nombre maximal de sélections".

Remarque : Il est impossible de renommer les classes associées aux états, car elles sont incorporées au cadre applicatif Spry.

Définition du moment de validation Par défaut, le widget Validation de case à cocher effectue sa validation lorsque l'utilisateur clique sur le bouton d'envoi. Vous pouvez toutefois définir deux autres options : "blur" ou "change". Le paramètre validateOn:["blur"] force le widget à procéder à la validation quand l'utilisateur clique en dehors du widget. Le paramètre validateOn:["change"] force le widget à procéder à la validation lorsque l'utilisateur effectue des sélections. ❖ Pour déterminer quand la validation se produit, ajoutez un paramètre validateOn au constructeur, comme suit : <script type="text/javascript"> var sprycheckbox1 = new Spry.Widget.ValidationCheckbox("sprycheckbox1", {validateOn:["blur"]}); </script>

Vous pouvez vous passer de parenthèses si votre paramètre validateOn contient une seule valeur (par exemple validateOn: "blur"). Par contre, si le paramètre contient les deux valeurs (validateOn:["blur", "change"]), la syntaxe doit comporter des parenthèses.

Définition d'un nombre minimal et maximal de sélections Par défaut, un widget Validation de case à cocher est réglé sur required (obligatoire). Si vous insérez plusieurs cases à cocher sur la page, il est toutefois possible de spécifier une plage de sélections minimale et maximale. Par exemple, si la balise span d'un widget Validation de case à cocher contient six cases à cocher et si vous voulez que l'utilisateur en sélectionne au moins trois, vous pouvez définir une exigence de ce type pour le widget entier. ❖ Pour définir un nombre minimal ou maximal de sélections, ajoutez la propriété minSelections ou maxSelections (ou les deux) et une valeur au constructeur, comme suit : <script type="text/javascript"> var checkboxwidget1 = new Spry.Widget.ValidationCheckbox("checkboxwidget1",{minSelections:value, maxSelections:value}); </script>


SPRY 79 Guide de l'utilisateur

Modification de l'état obligatoire des cases à cocher Par défaut, les widgets Validation de case à cocher exigent que l'utilisateur effectue au moins une sélection avant d'envoyer le formulaire. Vous pouvez toutefois stipuler que certaines sélections sont facultatives pour l'utilisateur. ❖ Pour modifier l'état obligatoire d'une case à cocher, ajoutez la propriété isRequired au constructeur et fixez sa valeur à "false", comme suit : <script type="text/javascript"> var checkboxwidget1 = new Spry.Widget.ValidationCheckbox("checkboxwidget1", {isRequired:false}); </script>

Personnalisation du widget Validation de case à cocher Le fichier SpryValidationCheckbox.css fournit le style par défaut du widget Validation de case à cocher. Vous pouvez personnaliser ce widget en modifiant la règle CSS appropriée. Les règles CSS du fichier SpryValidationCheckbox.css emploient les mêmes noms de classes que les éléments associés du code HTML du widget. Vous pouvez ainsi déterminer aisément quelles règles CSS correspondent au widget et à ses états d'erreur. Le fichier SpryValidationCheckbox.css doit déjà être placé sur votre site Web avant que vous entamiez des activités de personnalisation. Pour plus d'informations, consultez la section « Préparation des fichiers » à la page 3. Définition du style du widget Validation de case à cocher (instructions générales)

1 Ouvrez le fichier SpryValidationCheckbox.css. 2 Accédez à la règle CSS pour la partie du widget à modifier. Par exemple, pour modifier la couleur d'arrière-plan de l'état obligatoire du widget Validation de case à cocher, modifiez la règle .checkboxRequiredState dans le fichier CSS. 3 Apportez les modifications désirées à la règle CSS puis enregistrez le fichier. Le fichier SpryValidationCheckbox.css contient de nombreux commentaires qui expliquent le code et le rôle de certaines règles. Pour plus d'informations, consultez les commentaires dans le fichier. Définition du style du texte de message d'erreur d'un widget Validation de case à cocher

Par défaut, les messages d'erreur du widget Validation de case à cocher s'affichent en rouge, entourés d'un bord plein de 1 pixel d'épaisseur. ❖ Pour modifier le style des messages d'erreur d'un widget Validation de case à cocher, recherchez la règle CSS appropriée dans le tableau suivant, puis modifiez les propriétés par défaut ou ajoutez vos propriétés et valeurs de style du texte. Texte à mettre en forme

Règle CSS pertinente

Propriétés à modifier

Texte de message d'erreur

.checkboxRequiredState .checkboxRequiredMsg, .checkboxMinSelectionsState .checkboxMinSelectionsMsg, .checkboxMaxSelectionsState .checkboxMaxSelectionsMsg

color: #CC3333; border: 1px solid #CC3333;

Personnalisation des noms de classes associées aux états

Bien qu'il soit possible de remplacer des noms de classes associées aux messages d'erreur par des noms personnalisés en modifiant les règles dans le code CSS et les noms des classes dans le code HTML, vous ne pouvez pas modifier ni remplacer des noms de classes associées à des états. Les comportements sont en effet incorporés au cadre applicatif Spry. Vous pouvez toutefois remplacer le nom par défaut d'une classe associée à un état par le nom de votre choix en définissant une nouvelle valeur dans le troisième paramètre du constructeur du widget. ❖ Pour modifier des noms de classes associés à l'état d'un widget, ajoutez l'une des options de remplacement au troisième paramètre du constructeur du widget, puis définissez le nom de votre choix, comme suit : <script type="text/javascript"> var sprycheckbox1 = new Spry.Widget.ValidationCheckbox("sprycheckbox1", {requiredClass:"required"}); </script>


SPRY 80 Guide de l'utilisateur

Le tableau suivant fournit la liste des options que vous pouvez utiliser pour remplacer les noms intégrés des classes associées aux états. Option

Description

requiredClass

Supplante la valeur prédéfinie "checkboxRequiredState".

minSelectionsClass

Supplante la valeur prédéfinie "checkboxMinSelectionsState".

maxSelectionsClass

Supplante la valeur prédéfinie "checkboxMaxSelectionsState".


81

Chapitre 3 : Utilisation des ensembles de données XML Spry Un ensemble de données XML spry est un objet JavaScript qui permet d'afficher, sur une page Web, des données provenant d'un fichier de source de données XML. Vous pouvez ensuite utiliser ces données pour créer des régions principale et de détails sur la page. Ces régions sont mises à jour selon les sélections réalisées par les visiteurs du site.

A propos des ensembles de données XML Spry et des régions dynamiques Notions de base des ensembles de données XML Spry Un ensemble de données Spry est essentiellement un objet JavaScript. En insérant quelques fragments de code dans votre page Web, vous pouvez créer cet objet et y charger des données depuis une source XML lorsque l'utilisateur ouvre une page dans le navigateur. L'ensemble de données produit une plage à plat de données XML qui peut être représentée sous la forme d'un tableau standard contenant lignes et colonnes. Par exemple, supposons que vous disposiez d'un fichier source XML, cafetownsend.xml, qui contient les informations suivantes : <?xml version="1.0" encoding="UTF-8"?> <specials> <menu_item id="1"> <item>Summer Salad</item> <description>organic butter lettuce with apples, blood oranges, gorgonzola, and raspberry vinaigrette.</description> <price>7</price> </menu_item> <menu_item id="2"> <item>Thai Noodle Salad</item> <description>lightly sauteed in sesame oil with baby bok choi, portobello mushrooms, and scallions.</description> <price>8</price> </menu_item> <menu_item id="3"> <item>Grilled Pacific Salmon</item> <description>served with new potatoes, diced beets, Italian parlsey, and lemon zest.</description> <price>16</price> </menu_item> </specials>

En utilisant XPath sur la page Web pour indiquer les données qui vous intéressent (dans cet exemple, le noeud specials/menu_item du fichier XML), l'ensemble de données met les données XML à plat sous la forme d'une plage d'objets (lignes) et de propriétés (colonnes). Cette plage est représentée par le tableau suivant :


SPRY 82 Guide de l'utilisateur

@id

item

description

price

1

Summer salad

organic butter lettuce with apples, blood oranges, gorgonzola, and raspberry vinaigrette.

7

2

Thai Noodle Salad

lightly sauteed in sesame oil with baby bok choi, portobello mushrooms, and scallions.

8

3

Grilled Pacific Salmon

served with new potatoes, diced beets, Italian parlsey, and lemon zest.

16

L'ensemble de données contient une ligne pour chaque élément du menu et les colonnes suivantes : @id, item, description et price. Les colonnes représentent les noeuds enfants du noeud specials/menu_item des données XML, ainsi que tout attribut figurant dans la balise menu_item ou dans les balises enfants de cette dernière. L'ensemble de données contient également une référence de données intégrée, baptisée ds_RowID (non illustrée). Elle peut s'avérer utile par la suite, lors de l'affichage de vos données. L'ensemble de données contient également d'autres références de données intégrées, par exemple ds_RecordCount, ds_CurrentRow, ainsi que d'autres références qui vous permettent de manipuler l'affichage des données. Pour créer un objet d'ensemble de données Spry, utilisez XPath dans le constructeur Spry.Data.XMLDataSet. XPath définit la structure par défaut de l'ensemble de données. Par exemple, si vous utilisez XPath pour sélectionner un noeud XML répété qui comprend trois noeuds enfants, l'ensemble de données comprendra une ligne pour chaque noeud répété et une colonne pour chacun des trois noeuds enfants. Si l'un des noeuds répétés ou des noeuds enfants contient des attributs, l'ensemble de données crée également une colonne pour chaque attribut. Si vous ne définissez pas de XPath, toutes les données de la source XML figureront dans l'ensemble de données. Lorsque l'ensemble de données a été créé, l'objet d'ensemble de données permet d'afficher et de gérer aisément les données. Par exemple, vous pouvez créer un tableau simple qui affiche les données XML, puis employer des méthodes et des propriétés simples pour recharger, trier et filtrer les données, voire les faire défiler. L'exemple suivant crée un ensemble de données Spry nommé dsSpecials et charge les données depuis un fichier XML nommé cafetownsend.xml: <head> <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1" /> <title>Spry Example</title> <!--Link the Spry libraries--> <script type="text/javascript" src="includes/xpath.js"></script> <script type="text/javascript" src="includes/SpryData.js"></script> <!--Create a data set object--> <script type="text/javascript"> var dsSpecials = new Spry.Data.XMLDataSet("data/cafetownsend.xml", "specials/menu_item"); </script> </head> . . . <body> </body>

Remarque : Les exemples figurant dans ce document ne sont proposés qu'à des fins d'illustration et ne sont pas destinés à être exécutés. Vous trouverez des exemples fonctionnels dans le dossier "demos" du dossier Spry du site Adobe Labs. Dans l'exemple, la première balise script associe une bibliothèque XPath libre à la page qui servira à l'affichage final des données XML. La bibliothèque XPath permet de définir un XPath plus complexe lors de la création d'un ensemble de données : <script type="text/javascript" src="includes/xpath.js"></script>

Le deuxième bloc script lie la bibliothèque de données SpryData.js Spry, qui se trouve dans un dossier nommé includes sur le serveur : <script type="text/javascript" src="includes/SpryData.js"></script>


SPRY 83 Guide de l'utilisateur

Comme la bibliothèque de données Spry dépend de la bibliothèque XPath, il importe de toujours établir d'abord un lien vers la bibliothèque XPath. Le troisième bloc script contient l'instruction qui crée l'ensemble de données dsSpecials. Le fichier source XML cafetownsend.xml se trouve dans un dossier nommé data sur le serveur : var dsSpecials = new Spry.Data.XMLDataSet("data/cafetownsend.xml", "specials/menu_item");

Remarque : Les langages JavaScript et XML étant sensibles à la casse, il importe de veiller à harmoniser la capitalisation des noms de scripts et de colonnes que vous indiquez. Dans JavaScript, l'opérateur "new" sert à créer des objets. La méthode Spry.Data.XMLDataSet, dans la bibliothèque de données Spry, est un constructeur qui sert à créer de nouveaux objets d'ensemble de données Spry. Le constructeur emploie deux paramètres : la source des données ("data/cafetownsend.xml", dans ce cas, une URL relative) et une expression XPath qui définit le ou les noeuds dans XML afin de fournir les données ("specials/menu_item"). Vous pouvez également spécifier une URL absolue comme source des données XML, comme suit : var dsSpecials = new Spry.Data.XMLDataSet("http://www.somesite.com/somefolder/cafetownsend.xml", "specials/menu_item");

Remarque : Le choix de l'URL à utiliser (absolue ou relative) dépend du modèle de sécurité du navigateur. Ceci signifie que vous ne pouvez charger des données qu'à partir d'une source XML qui se trouve dans le même domaine de serveur que la page HTML à partir de laquelle vous établissez la liaison. Vous pouvez contourner cette limitation en fournissant un script de service interdomaine. Pour plus d'informations, contactez l'administrateur de votre serveur. Dans l'exemple précédent, le constructeur crée un nouvel objet d'ensemble de données Spry dsSpecials. L'ensemble de données obtient ses données depuis le noeud specials/menu_item (défini par XPath) dans le fichier XML "cafetownsend.xml" et convertit les données en une table à plat d'objets et de propriétés, similaires aux lignes et aux colonnes d'un tableau. Vous trouverez un exemple de tableau au début de cette section. Chaque ensemble de données emploie la notion de ligne actuelle. Par défaut, la ligne actuelle est la première ligne de l'ensemble de données. Vous pouvez par la suite modifier la ligne actuelle par voie de programmation, en appelant la méthode setCurrentRow() de l'objet d'ensemble de données. Pour plus d'informations, consultez la section « Définition ou modification de la ligne actuelle » à la page 111. Remarque : L'ensemble de données ne contient pas de données après sa création à l'aide de l'opérateur JavaScript new. Pour charger des données dans l'ensemble de données, appelez tout d'abord la méthode loadData() de ce dernier. Elle exécute une demande de chargement des données XML. Les régions Spry et les régions de détail le font automatiquement pour les ensembles de données dont elles dépendent. Par contre, si vous n'utilisez pas l'une de ces régions, vous devez appeler manuellement la méthode loadData() dans le code de votre page. Ce chargement s'effectue de manière asynchrone. Il se peut donc que les données ne soient pas disponibles si vous tentez d'y accéder juste après avoir appelé loadData().

Exemples avancés d'ensembles de données XML Spry Les ensembles de données XML spry emploient l'objet XMLHTTPRequest pour charger l'URL spécifiée de manière asynchrone. Lorsque les données XML sont reçues, elles sont en fait en deux formats : un format texte et un format d'arborescence DOM (document object model). Supposons que vous ayez défini “/photos.php?galleryid=2000” comme source de données. Cette source est le chemin d'accès à un service Web qui récupère des données XML. <script type="text/javascript"> var dsPhotos = new Spry.Data.XMLDataSet("/photos.php?galleryid=2000", "/gallery/photos/photo"); </script>

Le code suivant représente les données telles qu'elles parviennent en format texte :


SPRY 84 Guide de l'utilisateur

<gallery id="12345"> <photographer id="4532">John Doe</photographer> <email>john@doe.com</email> <photos id="2000"> <photo path="sun.jpg" width="16" height="16" /> <photo path="tree.jpg" width="16" height="16" /> <photo path="surf.jpg" width="16" height="16" /> </photos> </gallery>

L'exemple suivant représente les données telles qu'elles parviennent en format d'arborescence DOM :

L'ensemble de données emploie ensuite le XPath spécifié dans le constructeur pour naviguer dans l'arborescence DOM XML, de manière à trouver les noeuds spécifiques représentant les données qui vous intéressent. Le code suivant montre, en gras, des données sélectionnées à l'aide du XPath /gallery/photos/photo : <gallery id="12345"> <photographer id="4532">John Doe</photographer> <email>john@doe.com</email> <photos id="2000"> <photo path="sun.jpg" width="16" height="16"/> <photo path="tree.jpg" width="16" height="16"/> <photo path="surf.jpg" width="16" height="16"/> </photos> </gallery>

L'exemple suivant montre la représentation, en arborescence DOM, des noeuds sélectionnés.


SPRY 85 Guide de l'utilisateur

L'ensemble de données met ensuite l'ensemble de noeuds à plat sous forme de tableau, représenté comme suit. @path

@width

@height

sun.jpg

16

16

tree.jpg

16

16

surf.jpg

16

16

Dans cet exemple, Spry dérive les noms des colonnes du tableau à plat à partir des noeuds sélectionnés et de leurs attributs. Toutefois, la façon dont Spry détermine les noms des colonnes peut varier selon le XPath que vous définissez. Spry emploie les principes suivants pour mettre les données à plat et créer des colonnes :

• Si le noeud sélectionné possède des attributs, Spry crée une colonne pour chacun d'eux et place la valeur de chaque attribut dans la colonne correspondante. Les noms de ces colonnes sont ceux des attributs, précédés d'un symbole @. Par exemple, si un noeud possède un attribut id, le nom de la colonne sera @id.

• Si le noeud sélectionné ne possède pas des enfants de type élément et si du texte ou des données CDATA se trouvent sous lui, Spry crée une colonne et y place ce texte ou ces données CDATA. Le nom de cette colonne est le nom de balise du noeud pour les éléments XML normaux.

• Si le noeud sélectionné possède des enfants de type élément, Spry crée une colonne pour la valeur de chaque élément et de ses attributs, mais uniquement pour les éléments enfants qui ne possèdent pas, à leur tour, d'enfants de type élément. Les noms des colonnes sont les noms de balise des enfants de type élément ou, dans le cas de l'attribut d'un élément enfant, ils possèdent le format "nomBaliseEnfant/@nomAttribut".

• Si le noeud sélectionné est un attribut, Spry crée une colonne pour celui-ci ; le nom de la colonne sera le nom de l'attribut précédé d'un symbole @.

• Spry ignore les enfants de type élément qui possèdent à leur tour des enfants de type élément. Les exemples qui suivent fournissent plus d'informations sur le processus de mise à plat et la façon dont Spry génère des noms de colonnes pour les ensembles de données. Exemple de sélection et mise à plat d'un élément avec des attributs et une valeur de texte

Le code suivant montre, en gras, des données sélectionnées à l'aide du XPath /gallery/photographer : <gallery id="12345"> <photographer id="4532">John Doe</photographer> <email>john@doe.com</email> <photos id="2000"> <photo path="sun.jpg" width="16" height="16" /> <photo path="tree.jpg" width="16" height="16" /> <photo path="surf.jpg" width="16" height="16" /> </photos> </gallery>


SPRY 86 Guide de l'utilisateur

Voici la représentation, en arborescence DOM, du noeud sélectionné.

L'ensemble de données met ensuite les données sélectionnées à plat dans le tableau suivant. photographer

@id

John Doe

16

Dans ce cas précis, un seul noeud est sélectionné, si bien que notre ensemble de données ne contiendra qu'une ligne. La valeur du noeud photographer est le texte "John Doe". Une colonne nommée photographer sera dès lors créée pour stocker cette valeur. L'attribut id s'appliquant au noeud photographer, sa valeur est placée dans la colonne @id. Tous les noms d'attributs débutent par un symbole @. Exemple de sélection et mise à plat d'un élément avec des attributs et des enfants de type élément

Le code suivant montre des données sélectionnées à l'aide du XPath /gallery : <gallery id="12345"> <photographer id="4532">John Doe</photographer> <email>john@doe.com</email> <photos id="2000"> <photo path="sun.jpg" width="16" height="16" /> <photo path="tree.jpg" width="16" height="16" /> <photo path="surf.jpg" width="16" height="16" /> </photos> </gallery>


SPRY 87 Guide de l'utilisateur

Voici la représentation, en arborescence DOM, du noeud sélectionné :

L'ensemble de données met ensuite les données sélectionnées à plat dans le tableau suivant. @id

photographer

photographer/@id

email

12345

John Doe

4532

john@doe.com

Comme vous pouvez le constater, les noms des colonnes des attributs des éléments enfants comportent, comme préfixe, le nom de balise de l'élément enfant. Dans ce cas précis, photographer est un élément enfant du noeud gallery sélectionné. Son attribut id débute dès lors par photographer/@. Vous pouvez également constater que rien n'a été ajouté dans le tableau pour l'élément photos, bien qu'il soit un enfant du noeud gallery. En effet, Spry ne met pas à plat les éléments enfants qui contiennent d'autres éléments. Exemple de sélection d'un attribut d'un élément unique et de sa mise à plat

XPath permet également de sélectionner les attributs de noeuds. Le code suivant montre, en gras, des données sélectionnées à l'aide du XPath gallery/photos/photo/@path : <gallery id="12345"> <photographer id="4532">John Doe</photographer> <email>john@doe.com</email> <photos id="2000"> <photo path="sun.jpg" width="16" height="16" /> <photo path="tree.jpg" width="16" height="16" /> <photo path="surf.jpg" width="16" height="16" /> </photos> </gallery>


SPRY 88 Guide de l'utilisateur

Voici la représentation, en arborescence DOM, des noeuds sélectionnés.

L'ensemble de données met ensuite les données sélectionnées à plat dans le tableau suivant. @path sun.jpg tree.jpg surf.jpg

Présentation et structure d'une région dynamique Spry Lorsque vous avez créé un ensemble de données Spry, vous pouvez afficher les données dans une région dynamique Spry. Une région dynamique Spry est une partie d'une page Web liée à un ensemble de données. Cette région affiche les données XML provenant de l'ensemble de données et met automatiquement à jour les données affichées à chaque fois que l'ensemble de données est modifié.


SPRY 89 Guide de l'utilisateur

Les régions dynamiques se régénèrent, car elles s'enregistrent en tant qu'observateurs ou écouteurs des ensembles de données auxquels elles sont liées. Lorsque des données de ces ensembles sont modifiées (chargées, mises à jour, triées, filtrées, etc.), les ensembles de données envoient des notifications à tous leurs observations. Ces notifications déclenchent une régénération automatique par les régions dynamiques qui les écoutent.

Pour déclarer une région dynamique Spry dans une balise conteneur, utilisez l'attribut spry:region. La plupart des éléments HTML peuvent faire office de conteneurs de région dynamique. Les balises suivantes ne peuvent toutefois pas être utilisées :

col

colgroup

frameset

html

iframe

• select •

style

table

tbody

tfoot

thead

title

tr

Bien qu'il ne soit pas possible d'employer l'un des éléments HTML ci-dessus comme conteneurs de régions dynamiques Spry, vous pouvez les utiliser à l'intérieur de tels conteneurs. Remarque : Les régions dynamiques ne peuvent se trouver qu'à l'intérieur de la balise "body". Il est impossible d'ajouter l'attribut spry:region à une balise en dehors de la balise "body".


SPRY 90 Guide de l'utilisateur

Dans l'exemple suivant, le conteneur d'une région dynamique nommée Specials_DIV est créé à l'aide d'une balise div qui comprend un tableau HTML standard. Les tableaux sont les éléments HTML généralement utilisés pour les régions dynamiques. La première ligne du tableau peut en effet contenir des titres et la seconde recevoir les données XML répétées. <!--Create the Spry dynamic region--> <div id="Specials_DIV" spry:region="dsSpecials"> <!--Display the data in a table--> <table id="Specials_Table"> <tr> <th>Item</th> <th>Description</th> <th>Price</th> </tr> <tr spry:repeat="dsSpecials"> <td>{item}</td> <td>{description}</td> <td>{price}</td> </tr> </table> </div>

Dans l'exemple, la balise div qui crée le conteneur de la région dynamique n'a besoin que de deux attributs : un attribut spry:region qui déclare la région dynamique et spécifie l'ensemble de données à y employer, et un attribut id qui définit le nom de la région : <div id="Specials_DIV" spry:region="dsSpecials">

La nouvelle région est un observateur de l'ensemble de données dsSpecials. A chaque fois que l'ensemble de données dsSpecials est modifié, la nouvelle région dynamique est régénérée à l'aide des données mises à jour. Les données sont affichées dans un tableau HTML : <table id="Specials_Table"> <tr> <th>Item</th> <th>Description</th> <th>Price</th> </tr> <tr spry:repeat="dsSpecials"> <td>{item}</td> <td>{description}</td> <td>{price}</td> </tr> </table>

Les valeurs entre accolades dans la deuxième ligne du tableau (les références de données) spécifient les colonnes de l'ensemble de données. Les références de données lient les cellules du tableau aux données dans des colonnes spécifiques de l'ensemble de données. Comme les données XML comportent souvent des noeuds répétés, l'exemple déclare également un attribut spry:repeat dans la balise de la deuxième ligne du tableau. Ainsi, toutes les lignes de l'ensemble de données s'affichent lorsque l'utilisateur charge la page (et pas la seule ligne actuelle de l'ensemble de données).

Présentation et structure d'une région principale et d'une région de détail Spry - Notions de base Lorsque vous utilisez des ensembles de données Spry, vous pouvez créer des régions dynamiques principale et de détail afin d'afficher plus de détails sur vos données. Une région de la page (la région principale) contrôle l'affichage des données dans une autre (la région de détail).


SPRY 91 Guide de l'utilisateur

A. Région principale B. Région de détail

En règle générale, la région principale affiche une représentation abrégée d'un jeu d'enregistrements de l'ensemble de données, et la région de détail affiche plus d'informations au sujet d'un enregistrement sélectionné. Comme la région de détail dépend de la région principale, chaque modification des données dans la région principale entraîne celle des données dans la région de détail. Cette section étudie les relations de base entre région principale et région de détail, dans un cas de figure où ces deux régions dépendent du même ensemble de données. Pour plus d'informations sur les régions principale et de détail qui emploient plusieurs ensembles de données, reportez-vous à la section « Présentation et structure d'une région principale et d'une région de détail Spry - Notions avancées » à la page 93. Dans l'exemple suivant, une région dynamique principale affiche des données depuis l'ensemble de données dsSpecials, et une région dynamique de détail affiche plus d'informations sur la ligne de données sélectionnée dans la région principale : <head> . . . <script type="text/javascript" src="../includes/xpath.js"></script> <script type="text/javascript" src="../includes/SpryData.js"></script> <script type="text/javascript"> var dsSpecials = new Spry.Data.XMLDataSet("data/cafetownsend.xml", "specials/menu_item"); </script> </head> . . . <body> <!--Create a master dynamic region--> <div id="Specials_DIV" spry:region="dsSpecials"> <table id="Specials_Table"> <tr> <th>Item</th> <th>Description</th> <th>Price</th> </tr> <!--User clicks to reset the current row in the data set--> <tr spry:repeat="dsSpecials" spry:setrow="dsSpecials"> <td>{item}</td>


SPRY 92 Guide de l'utilisateur

<td>{description}</td> <td>{price}</td> </tr> </table> </div> <!--Create the detail dynamic region--> <div id="Specials_Detail_DIV" spry:detailregion="dsSpecials"> <table id="Specials_Detail_Table"> <tr> <th>Ingredients</th> <th>Calories</th> </tr> <tr> <td>{ingredients}</td> <td>{calories}</td> </tr> </table> </div> . . . </body>

Remarque : Le fichier XML d'exemple de la section « Notions de base des ensembles de données XML Spry » à la page 81 ne contient pas de noeuds pour les ingrédients ni les calories. Ces noeuds ont été ajoutés à l'ensemble de données de cet exemple. Dans l'exemple, la première balise div contient les attributs id et spry:region qui créent un conteneur pour la région dynamique principale : <div id="Specials_DIV" spry:region="dsSpecials">

La première balise "table-row" de la région principale contient un attribut spry:setrow qui définit la valeur de la ligne actuelle dans l'ensemble de données. <tr spry:repeat="dsSpecials" spry:setrow="dsSpecials">

La deuxième balise div contient les attributs qui créent un conteneur pour la région dynamique de détail : <div id="Specials_Detail_DIV" spry:detailregion="dsSpecials">

Chaque ensemble de données Spry emploie la notion de ligne actuelle. Par défaut, la ligne actuelle est la première ligne de l'ensemble de données. L'attribut spry:detailregion fonctionne exactement comme l'attribut spry:region, à ceci près que lorsque la ligne actuelle de l'ensemble de données change, la région de détail est mise à jour automatiquement. Les expressions de liaison dans la région de détail ({ingredients} et {calories}) affichent des données depuis la ligne actuelle de l'ensemble de données lorsque la page est chargée dans un navigateur. Toutefois, lorsque l'utilisateur clique sur une ligne dans le tableau de la région principale, l'attribut spry:setrow remplace la ligne actuelle de l'ensemble de données par la ligne que l'utilisateur a sélectionnée. La référence de données {ds_RowID} est une partie intégrée du cadre applicatif Spry qui renvoie à un ID unique, généré automatiquement, pour chaque ligne de l'ensemble de données. Reportez-vous à la section « Options de référence de données » à la page 120. Lorsque l'utilisateur sélectionne une ligne dans le tableau de la région principale, l'attribut spry:setrow fournit l'ID unique à la méthode setCurrentRow, qui définit la ligne actuelle dans l'ensemble de données.


SPRY 93 Guide de l'utilisateur

A chaque fois que l'ensemble de données est modifié, toutes les régions dynamiques liées à cet ensemble se régénèrent et affichent les données mises à jour. Etant donné que la région de détail, tout comme la région principale, est un observateur de l'ensemble de données dsSpecials, elle est également mise à jour suite à la modification, et elle affiche les données relatives à la ligne sélectionnée par l'utilisateur (la nouvelle ligne actuelle).

La différence entre spry:region et spry:detailregion réside dans le fait que spry:detailregion est spécifiquement à l'écoute des notifications CurrentRowChange (en plus des notifications DataChanged) provenant de l'ensemble de données, et que cette région se met à jour lorsqu'elle en reçoit une. Par contre, une spry:regions normale ignore la notification CurrentRowChange et ne se met à jour qu'en cas de réception d'une notification DataChanged provenant de l'ensemble de données.

Présentation et structure d'une région principale et d'une région de détail Spry - Notions avancées Dans certains cas, il peut être utile de créer des relations entre région principale et de détail qui impliquent plusieurs ensembles de données. Par exemple, il se peut que vous disposiez d'une liste d'éléments de menu auxquels une grande quantité d'informations détaillées sont associées. Cette section emploie, à titre d'illustration, une liste d'ingrédients. L'obtention de toutes les informations associées à chaque élément du menu via une seule requête peut s'avérer peu efficace en termes d'utilisation de la bande passante. Il peut même être superflu, puisqu'il est probable que de nombreux utilisateurs ne soient pas intéressés par les détails de chaque plat au menu. Au contraire, il est plus efficace de télécharger uniquement


SPRY 94 Guide de l'utilisateur

les données détaillées qui intéressent l'utilisateur lorsque celui-ci en fait la demande, de manière à améliorer les performances tout en réduisant la consommation de bande passante. Cette façon de limiter la quantité de données échangées est une technique couramment utilisée pour améliorer les performances d'applications AJAX. Vous trouverez ci-dessous le code source XML d'un fichier d'exemple nommé cafetownsend.xml : <?xml version="1.0" encoding="UTF-8"?> <specials> <menu_item id="1"> <item>Summer Salad</item> <description>organic butter lettuce with apples, blood oranges, gorgonzola, and raspberry vinaigrette.</description> <price>7</price> <url>summersalad.xml</url> </menu_item> <menu_item id="2"> <item>Thai Noodle Salad</item> <description>lightly sauteed in sesame oil with baby bok choi, portobello mushrooms, and scallions.</description> <price>8</price> <url>thainoodles.xml</url> </menu_item> <menu_item id="3"> <item>Grilled Pacific Salmon</item> <description>served with new potatoes, diced beets, Italian parlsey, and lemon zest.</description> <price>16</price> <url>salmon.xml</url> </menu_item> </specials>

Remarque : Cet exemple de code XML diffère du code utilisé dans la section « Notions de base des ensembles de données XML Spry » à la page 81. Le fichier cafetownsend.xml fournit les données de l'ensemble de données principal. Le noeud url du fichier cafetownsend.xml renvoie à un fichier XML (ou une URL) unique pour chaque élément du menu. Ces fichiers XML uniques contiennent une liste d'ingrédients pour les éléments de menu correspondants. Ainsi, le fichier summersalad.xml pourrait se présenter comme suit : <?xml version="1.0" encoding="iso-8859-1" ?> <item> <item_name>Summer salad</item_name> <ingredients> <ingredient> <name>butter lettuce</name> </ingredient> <ingredient> <name>Macintosh apples</name> </ingredient> <ingredient> <name>Blood oranges</name> </ingredient> <ingredient> <name>Gorgonzola cheese</name> </ingredient> <ingredient> <name>raspberries</name> </ingredient> <ingredient> <name>Extra virgin olive oil</name> </ingredient>


SPRY 95 Guide de l'utilisateur

<ingredient> <name>balsamic vinegar</name> </ingredient> <ingredient> <name>sugar</name> </ingredient> <ingredient> <name>salt</name> </ingredient> <ingredient> <name>pepper</name> </ingredient> <ingredient> <name>parsley</name> </ingredient> <ingredient> <name>basil</name> </ingredient> </ingredients> </item>

Si vous connaissez bien la structure de votre code XML, vous pouvez créer deux ensembles de données, de manière à afficher les données dans des régions dynamiques principale et de détail. Dans l'exemple suivant, une région dynamique principale affiche des données depuis l'ensemble de données dsSpecials, et une région dynamique de détail affiche des données depuis l'ensemble dsIngredients. <head> . . . <script type="text/javascript" src="../includes/xpath.js"></script> <script type="text/javascript" src="../includes/SpryData.js"></script> <script type="text/javascript"> <!--Create two separate data sets--> var dsSpecials = new Spry.Data.XMLDataSet("data/cafetownsend.xml", "specials/menu_item"); var dsIngredients = new Spry.Data.XMLDataSet("data/{dsSpecials::url}", "item/ingredients/ingredient"); </script> </head> . . . <body> <!--Create a master dynamic region--> <div id="Specials_DIV" spry:region="dsSpecials"> <table id="Specials_Table"> <tr> <th>Item</th> <th>Description</th> <th>Price</th> </tr> <!--User clicks to reset the current row in the data set-->


SPRY 96 Guide de l'utilisateur

<tr spry:repeat="dsSpecials" spry:setrow=”dsSpecials”> <td>{item}</td> <td>{description}</td> <td>{price}</td> </tr> </table> </div> <!--Create the detail dynamic region--> <div id="Specials_Detail_DIV" spry:region="dsIngredients"> <table id="Specials_Detail_Table"> <tr> <th>Ingredients</th> </tr> <tr spry:repeat=”dsIngredients”> <td>{name}</td> </tr> </table> </div> . . . </body>

Dans cet exemple, le troisième bloc script contient l'instruction qui crée deux ensembles de données. Le premier est nommé dsSpecials et l'autre dsIngredients: var dsSpecials = new Spry.Data.XMLDataSet("data/cafetownsend.xml", "specials/menu_item"); var dsIngredients = new Spry.Data.XMLDataSet("data/{dsSpecials::url}", "item/ingredients/ingredient");

L'URL du second ensemble de données, dsIngredients, contient une référence de données ({dsSpecials::url}) au premier ensemble, dsSpecials. Plus précisément, elle contient une référence de données à la colonne "url" de l'ensemble de données dsSpecials. Lorsque l'argument URL ou XPath du constructeur qui crée un ensemble de données contient une référence à un autre ensemble de données, l'ensemble créé automatiquement devient observateur de celui auquel il fait référence. Le nouvel ensemble de données dépend de l'ensemble d'origine, et il recharge ses données ou réapplique son XPath à chaque modification des données ou de la ligne actuelle dans l'ensemble de données d'origine. L'exemple suivant présente les relations d'observateur établies entre les ensembles de données et les régions dynamiques principale et de détail. Dans l'exemple précédent, l'ensemble de données dsIngredients (ensemble de données B) est un observateur of de l'ensemble de données dsSpecials (ensemble de données A).

Dans cet exemple, la modification de la ligne actuelle dans l'ensemble de données dsSpecials envoie une notification à l'ensemble de données dsIngredients afin de l'informer qu'il doit lui aussi être modifié. Comme chaque ligne de l'ensemble de données dsSpecials contient une URL distincte dans la colonne "url", l'ensemble de données dsIngredients doit être mis à jour afin de contenir l'URL correcte pour la ligne sélectionnée.


SPRY 97 Guide de l'utilisateur

Par défaut, l'ensemble de données dsIngredients (dont les données sont affichées dans la région de détail) est créé à partir des données obtenues depuis l'URL définie dans le constructeur. Dans ce cas-ci, il s'agit d'une référence aux données de la colonne "url" de l'ensemble de donnéesdsSpecials. La ligne actuelle par défaut de l'ensemble de données dsSpecials (la première ligne) contient un chemin d'accès unique au fichier summersalad.xml. La région détaillée affichera dès lors les informations provenant de ce fichier lorsque la page sera chargée dans un navigateur. Toutefois, lorsque la ligne actuelle de l'ensemble de données dsSpecials est modifiée, l'URL l'est également (par exemple, elle renvoie vers salmon.xml) et l'ensemble de données dsIngredients est mis à jour en conséquence (ainsi que, par association, la région dynamique de détail).

D'un point de vue fonctionnel, ce processus est équivalent à celui qui est illustré dans la section « Présentation et structure d'une région principale et d'une région de détail Spry - Notions de base » à la page 90. Sur le plan technique, il en diffère par le fait que, dans l'exemple avancé, le second ensemble de données (l'ensemble de détail) est à l'écoute des données et des changements de ligne dans l'ensemble de données principal, alors quand dans l'exemple de base, c'est la région de détail qui remplit ce rôle. Dans l'exemple de code, spry:region est utilisé pour la région de détail au lieu de spry:detailregion. La différence entre spry:region et spry:detailregion réside dans le fait que spry:detailregion est spécifiquement à l'écoute des notifications CurrentRowChange (en plus des notifications DataChanged) provenant de l'ensemble de données, et que cette région se met à jour lorsqu'elle en reçoit une. Comme la ligne actuelle de l'ensemble de données dsIngredients ne change jamais (c'est la ligne actuelle de l'ensemble de données dsSpecials qui varie), aucun attribut spry:detailregion n'est requis. L'attribut spry:region, qui définit une région qui n'est à l'écoute que des notifications DataChanged, est suffisant dans ce cas.

Amélioration progressive et accessibilité des ensembles de données Le processus d'amélioration progressive consiste à rédiger le code d'un document pour le plus petit dénominateur commun des fonctionnalités de navigateur, puis à améliorer l'apparence et le comportement de la page à l'aide de code CSS, JavaScript, Flash, Java et SVG, et ainsi de suite. Les pages créées selon ce processus offrent une expérience améliorée dans les navigateurs modernes, mais leurs données sont toujours accessibles et la page toujours fonctionnelles si les technologies de ces navigateurs ne sont pas présentes. Tous les exemples de code Spry figurant jusqu'ici dans ce texte concernaient l'emploi de JavaScript pour charger de manière dynamique des données XML et générer des régions du document. Vous pouvez également utiliser Spry dans un processus d'amélioration progressive à l'aide de la méthodologie Hijax (voir http://domscripting.com/blog/display/41). Cette méthodologie d'amélioration progressive utilise du code JavaScript pour joindre, en toute transparence, des gestionnaires d'événements aux éléments de la page, comme des liens capturant les événements utilisateur (par exemple des clics de souris). Le processus d'amélioration progressive permet également de remplacer des parties de votre document par des fragments de code qui sont fournis de manière asynchrone à partir du serveur, ce qui évite d'exiger le chargement d'une page entière. A titre d'exemple simple de l'utilisation de Spry avec cette méthodologie, vous pourriez commencer par une page HTML remplie de données statiques et de liens :


SPRY 98 Guide de l'utilisateur

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1transitional.dtd"> <html xmlns="http://www.w3.org/1999/xhtml" xmlns:spry="http://ns.adobe.com/spry"> <head> <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1" /> <title>Hijax Demo - Notes 1</title> </head> <body> <a href="notes1.html">Note 1</a> <a href="notes2.html">Note 2</a> <a href="notes3.html">Note 3</a> <div> <p>This is some <b>static content</b> for note 1.</p> </div> </body> </html>

Pour améliorer progressivement cette page avec Spry, de manière à éviter de charger une toute nouvelle page à chaque clic sur un lien, vous allez tout d'abord utiliser XML pour faire en sorte que les fragments de chaque page auxquels les liens font référence soient accessibles. L'exemple suivant montre une manière d'externaliser les données statiques : <?xml version="1.0" encoding="iso-8859-1"?> <notes> <note><![CDATA[<p>This is some <b>dynamic content</b> for note 1.</p>]]></note> <note><![CDATA[<p>This is some <b>dynamic content</b> for note 2.</p>]]></note> <note><![CDATA[<p>This is some <b>dynamic content</b> for note 3.</p>]]></note> </notes>

Vous pouvez ensuite appliquer Spry à la page HTML de la manière suivante : <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1transitional.dtd"> <html xmlns="http://www.w3.org/1999/xhtml" xmlns:spry="http://ns.adobe.com/spry"> <head> <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1" /> <title>Hijax Demo - Notes 1</title> <script language="JavaScript" type="text/javascript" src="includes/xpath.js"></script> <script language="JavaScript" type="text/javascript" src="includes/SpryData.js"></script> <script language="JavaScript" type="text/javascript"> <!-var dsNotes = new Spry.Data.XMLDataSet('data/notes.xml', "/notes/note"); --> </script> </head> <body> <a href="note1.html" onclick="dsNotes.setCurrentRowNumber(0); return false;">Note 1</a> <a href="note2.html" onclick="dsNotes.setCurrentRowNumber(1); return false;">Note 2</a> <a href="note3.html" onclick="dsNotes.setCurrentRowNumber(2); return false;">Note 3</a> <div spry:detailregion="dsNotes" spry:content="{note}"> <p>This is some <b>static content</b> for note 1.</p> </div> </body> </html>

Le code Spry ajouté au code précédent peut sembler familier, mais notez que le bloc div qui contient l'attribut spry:detailregion comprend également un attribut spry:content. Cet attribut spry:content donne à Spry le code de traitement de région dynamique destiné à remplace les données statiques, qui se trouvent actuellement dans la région, par les données représentées par la référence de données dans sa valeur d'attribut, si des données se trouvent dans l'ensemble de données auquel la région est liée. Si cette page est chargée dans un navigateur où JavaScript est désactivé, elle se dégrade, et vous obtenez les mêmes fonctionnalités que la page d'origine, avec son contenu statique et sa navigation traditionnelle à l'aide de liens. Si JavaScript est activé, l'ensemble de données charge les données XML et remplace le contenu statique de la région. Un clic sur les liens entraîne la mise à jour de la région au moyen de code provenant de l'ensemble de données.


SPRY 99 Guide de l'utilisateur

Dans l'exemple précédent, Hijax conseille de joindre, de manière transparente, des gestionnaires d'événements aux liens. L'exemple précédent emploie volontairement des attributs onclick pour illustrer l'utilité de joindre un gestionnaire d'événement JavaScript.

Création de pages dynamiques avec Spry Préparation des fichiers Avant d'entamer la création d'ensembles de données Spry, procurez-vous les fichiers nécessaires (xpath.js et SpryData.js). Le fichier xpath.js permet de spécifier des expressions XPath complexes lors de la création de votre ensemble de données. Le fichier SpryData.js contient la bibliothèque de données Spry. Liez ces deux fichiers à la page HTML que vous créez. 1 Recherchez le fichier ZIP de Spry sur le site Adobe Labs. 2 Téléchargez ce fichier ZIP et décompressez-le sur votre disque dur. 3 Ouvrez le dossier Spry décompressé et recherchez-y le dossier "includes". Ce dossier contient les fichiers xpath.js et SpryData.js nécessaires à l'exécution du cadre applicatif Spry. 4 Copiez le dossier "includes" et collez-en une copie (ou faites-la glisser) dans le répertoire racine de votre site Web. Remarque : Si vous faites glisser le dossier "includes" d'origine à partir du dossier Spry non décompressé, les démos du dossier Spry ne fonctionneront pas correctement. 5 En mode Code (Affichage > Code), liez les fichiers de bibliothèque de données Spry à votre page Web en insérant les balises script suivantes dans la balise "head" de la page : <script type="text/javascript" src="includes/xpath.js"></script> <script type="text/javascript" src="includes/SpryData.js"></script>

Comme le fichier SpryData.js dépend du fichier xpath.js, il importe que le fichier xpath.js soit mentionné en premier lieu dans le code. Lorsque vous avez établi un lien avec la bibliothèque de données Spry, vous pouvez créer un ensemble de données Spry. 6 Ajoutez la déclaration d'espace de noms Spry à la balise HTML, pour donner à cette dernière l'apparence suivante : <html xmlns="http://www.w3.org/1999/xhtml" xmlns:spry="http://ns.adobe.com/spry/">

La déclaration d'espace de noms Spry est nécessaire pour la validation du code. Remarque : Les fonctionnalités de Spry s'exécutent localement tant que les fichiers de bibliothèque de données Spry sont liés à votre page HTML. Pour publier la page HTML sur un serveur en ligne, chargez-y les fichiers xpath.js et SpryData.js sous la forme de fichiers dépendants.

Création d'un ensemble de données XML Spry 1 Ouvrez une nouvelle page HTML ou créez-en une nouvelle. 2 Assurez-vous que vous avez bien lié les fichiers de bibliothèque de données Spry à la page et que vous avez déclaré l'espace de noms Spry. Pour plus d'informations, consultez la section « Préparation des fichiers » à la page 99. 3 Recherchez la source XML de l'ensemble de données. Par exemple, vous pouvez utiliser un fichier XML nommé cafetownsend.xml, situé dans un dossier nommé data dans le dossier racine du site : data/cafetownsend.xml Vous pouvez également spécifier l'URL d'un fichier XML, comme suit : http://www.unsite.com/undossier/cafetownsend.xml


SPRY 100 Guide de l'utilisateur

Remarque : Le choix de l'URL à utiliser (absolue ou relative) dépend du modèle de sécurité du navigateur. Ceci signifie que vous ne pouvez charger des données qu'à partir d'une source XML qui se trouve dans le même domaine de serveur que la page HTML à partir de laquelle vous établissez la liaison. Vous pouvez contourner cette limitation en fournissant un script de service interdomaine. Pour plus d'informations, contactez l'administrateur de votre serveur. 4 Comme vous devez spécifier le noeud XML répété qui fournit les données à l'ensemble de données, veillez à bien comprendre la structure du fichier XML avant de créer l'ensemble de données. Dans l'exemple suivant, le fichier cafetownsend.xml se compose d'un noeud parent nommé specials, qui contient un noeud enfant répété nommé menu_item. <?xml version="1.0" encoding="UTF-8"?> <specials> <menu_item id="1"> <item>Summer Salad</item> <description>organic butter lettuce with apples, blood oranges, gorgonzola, and raspberry vinaigrette.</description> <price>7</price> </menu_item> <menu_item id="2"> <item>Thai Noodle Salad</item> <description>lightly sauteed in sesame oil with baby bok choi, portobello mushrooms, and scallions.</description> <price>8</price> </menu_item> <menu_item id="3"> <item>Grilled Pacific Salmon</item> <description>served with new potatoes, diced beets, Italian parlsey, and lemon zest.</description> <price>16</price> </menu_item> </specials>

5 Pour créer l'ensemble de données, insérez le bloc script suivant après les balises script qui importent la bibliothèque : <script type="text/javascript"> var datasetName = new Spry.Data.XMLDataSet("XMLsource", "XPathToRepeatingChildNode"); </script>

Dans l'exemple Cafe Townsend, vous créez un ensemble de données au moyen de l'instruction suivante : var dsSpecials = new Spry.Data.XMLDataSet("data/cafetownsend.xml", "specials/menu_item");

Cette instruction crée un nouvel ensemble de données nommé dsSpecials, qui récupère des donnée depuis le noeud specials/menu_item du fichier XML spécifié. L'ensenble de données contient une ligne pour chaque élément du menu et les colonnes suivantes : @id, item, description et price, représentées par le tableau suivant. @id

élément

description

price

1

Summer salad

organic butter lettuce with apples, blood 7 oranges, gorgonzola, and raspberry vinaigrette.

2

Thai Noodle Salad

lightly sauteed in sesame oil with baby bok choi, portobello mushrooms, and scallions.

8

3

Grilled Pacific Salmon

served with new potatoes, diced beets, Italian parlsey, and lemon zest.

16

Vous pouvez également spécifier une URL comme source des données XML, comme suit : var dsSpecials = new Spry.Data.XMLDataSet("http://www.somesite.com/somefolder/cafetownsend.xml", "specials/menu_item");

Remarque : Le choix de l'URL à utiliser (absolue ou relative) dépend du modèle de sécurité du navigateur. Ceci signifie que vous ne pouvez charger des données qu'à partir d'une source XML qui se trouve dans le même domaine de serveur que la page HTML à partir de laquelle vous établissez la liaison. Vous pouvez contourner ce problème en fournissant un script de service interdomaine. Pour plus d'informations, contactez l'administrateur de votre serveur.


SPRY 101 Guide de l'utilisateur

L'exemple de code complet pourrait ressembler à ce qui suit : <head> ... <script type="text/javascript" src="includes/xpath.js"></script> <script type="text/javascript" src="includes/SpryData.js"></script> <script type="text/javascript"> var dsSpecials = new Spry.Data.XMLDataSet("data/cafetownsend.xml", "specials/menu_item"); </script> ... </head>

6 (Facultatif) Si les valeurs de votre ensemble de données comprennent des nombres (comme dans cet exemple), réinitialisez les types des colonnes contenant ces valeurs numériques. Cette modification pourra s'avérer importante par la suite si vous voulez trier les données. Pour définir les types des colonnes, ajoutez la méthode d'ensemble de données setColumnType à la balise "head" de votre document, après avoir créé l'ensemble de données, comme suit (en gras) : <script type="text/javascript"> var dsSpecials = new Spry.Data.XMLDataSet("data/cafetownsend.xml", "specials/menu_item"); dsSpecials.setColumnType("price", "number"); </script>

Dans cet exemple, l'expression appelle la méthode setColumnType sur l'objet d'ensemble de données dsSpecials, que vous avez déjà défini. La méthode setColumnType emploie deux paramètres : le nom de la colonne d'ensemble de données dont le type doit être modifié ("price") et le type de données désiré ("number"). Pour plus d'informations, consultez la section « Tri des données par les utilisateurs » à la page 103. Après avoir créé l'ensemble de données, créez une région dynamique de manière à pouvoir afficher les données.

Création d'une région dynamique Spry et affichage des données Après avoir créé un ensemble de données Spry, vous devez y lier une région dynamique Spry. Une région dynamique Spry est une partie de la page qui affiche les données et met à jour automatiquement les données affichées lorsque l'ensemble de données est modifié. 1 Assurez-vous que vous avez bien lié les fichiers de bibliothèque de données Spry à la page, que vous avez déclaré l'espace de noms Spry et que vous avez créé un ensemble de données. Pour plus d'informations, reportez-vous aux sections « Préparation des fichiers » à la page 99 et « Création d'un ensemble de données XML Spry » à la page 99. 2 En mode Code, créez une région dynamique Spry en ajoutant l'attribut spry:region à la balise qui va contenir la région. Cet attribut utilise la syntaxe spry:region="datasetName". Remarque : La plupart des éléments HTML (mais pas tous) peuvent faire office de conteneurs pour régions dynamiques. Pour plus d'informations, consultez la section « Présentation et structure d'une région dynamique Spry » à la page 88. Par exemple, pour utiliser une balise div comme conteneur de la région dynamique qui affiche des données à partir de l'ensemble de données dsSpecials, ajoutez l'attribut spry:region à la balise comme suit : <div id="Specials_DIV" spry:region="dsSpecials"></div>

Remarque : Une région dynamique peut dépendre de plusieurs ensembles de données. Pour ajouter des ensembles de données supplémentaires à une région, ajoutez-les en tant que valeurs supplémentaires à l'attribut spry:region, en les séparant par un espace. Par exemple, vous pouvez créer une région dynamique en utilisant spry:region="dsSpecials dsSpecials2 dsSpecials3". 3 A l'intérieur de la balise contenant la région dynamique (cet exemple emploie une balise div), insérez un élément HTML afin d'afficher la première ligne de l'ensemble de données. Vous pouvez utiliser n'importe quel élément pour afficher des données. Toutefois, l'un des éléments le plus souvent utilisé à cette fin est un tableau HTML à deux lignes, la première contenant les en-têtes de colonnes statiques et la seconde les données :


SPRY 102 Guide de l'utilisateur

<table id="Specials_Table"> <tr> <th>Item</th> <th>Description</th> <th>Price</th> </tr> <tr spry:repeat="dsSpecials"> <td>{item}</td> <td>{description}</td> <td>{price}</td> </tr> </table>

Les valeurs entre accolades dans la deuxième ligne (les références de données) spécifient les colonnes de l'ensemble de données. Les références de données lient les cellules du tableau à des données dans des colonnes spécifiques de l'ensemble de données. Remarque : Si la région Spry dépend de plusieurs ensembles de données, définissez celui auquel vous liez la région dynamique. La syntaxe complète de la référence de données se présente sous la forme {datasetName::columnName}. Par exemple, pour lier la région dynamique à deux ou trois ensembles de données différents, entrez les données de l'exemple précédent comme suit : {dsSpecials::item}, {dsSpecials::description}, et ainsi de suite. Les régions Spry acceptent également les ensembles de données multiples. Vous pouvez les spécifier en ajoutant leurs noms à la valeur de l'attribut, en les séparant par un espace (p.ex. <div spry:region=”ds1 ds2 ds3”>. 4 Forcez l'élément HTML à se répéter automatiquement, pour afficher toutes les lignes de l'ensemble de données, en ajoutant l'attribut et la valeur spry:repeat à la balise de l'élément HTML à l'aide de la syntaxe suivante : spry:repeat="datasetName"

Dans cet exemple, vous ajoutez l'attribut spry:repeat à la balise de ligne de tableau de la manière suivante (en gras) : <tr spry:repeat="dsSpecials"> <td>{item}</td> <td>{description}</td> <td>{price}</td> </tr>

Dans l'exemple, le code complet qui lie la région dynamique à l'ensemble de données se présenterait comme suit : <div id="Specials_DIV" spry:region="dsSpecials"> <table id="Specials_Table"> <tr> <th>Item</th> <th>Description</th> <th>Price</th></tr> <tr spry:repeat="dsSpecials"> <td>{item}</td> <td>{description}</td> <td>{price}</td> </tr> </table> </div>

5 Vous pouvez accroître l'interactivité de la région dynamique en définissant des événements de clic qui permettent aux utilisateurs de trier les données. Pour plus d'informations, consultez la section « Tri des données par les utilisateurs » à la page 103.

Exemple de code : Ensemble de données et région dynamique Spry L'exemple de code suivants crée un ensemble de données et une région dynamique Spry en vue d'afficher une liste de plats à la carte dans un tableau HTML.


SPRY 103 Guide de l'utilisateur

<head> ... <script type="text/javascript" src="includes/xpath.js"></script> <script type="text/javascript" src="includes/SpryData.js"></script> <script type="text/javascript"> var dsSpecials = new Spry.Data.XMLDataSet("data/cafetownsend.xml", "specials/menu_item"); </script> ... </head> <body> ... <div id="Specials_DIV" spry:region="dsSpecials"> <table id="Specials_Table"> <tr> <th>Item</th> <th>Description</th> <th>Price</th> </tr> <tr spry:repeat="dsSpecials"> <td>{item}</td> <td>{description}</td> <td>{price}</td> </tr> </table> </div> ... </body>

Tri des données par les utilisateurs Vous pouvez ajouter des attributs spry:sort à une région dynamique de manière à autoriser les utilisateurs à interagir avec les données. Cette section emploie, à titre d'exemple, le code de tableau étudié dans la section « Création d'une région dynamique Spry et affichage des données » à la page 101. 1 Dans le code, accédez à l'endroit où vous voulez ajouter le ou les attributs spry:sort. Dans cet exemple, ces attributs seront ajoutés aux deux en-têtes de colonnes d'un tableau qui affiche les données XML. 2 Ajoutez un attribut spry:sort aux balises d'en-tête de colonne appropriées, sous la forme suivante : spry:sort="columnName"

La valeur définie dans l'attribut spry:sort indique à l'ensemble de données quelle colonne doit être utilisée pour le tri des données. Par exemple, l'ajout des attributs spry:sort suivants (en gras) aux balises d'en-tête de colonne permet de trier les données de la région dynamique selon la valeur spécifiée à chaque fois que l'utilisateur clique sur un en-tête de colonne sur la page. <div id="Specials_DIV" spry:region="dsSpecials"> <table id="Specials_Table" class="main"> <tr> <th spry:sort="item">Item</th> <th spry:sort="description">Description</th> <th>Price</th> </tr> <tr spry:repeat="dsSpecials"> <td>{item}</td> <td>{description}</td> <td>{price}</td> </tr> </table> </div>

Un clic sur "Item", sur la page, permet de trier les données dans l'ordre alphabétique selon le nom des plats au menu. Un clic sur "Description" permet pour sa part de trier les données dans l'ordre alphabétique selon la description des plats.


SPRY 104 Guide de l'utilisateur

Tri numérique

Par défaut, toutes les données de l'ensemble de données (y compris les nombres) sont considérées comme étant de type texte et sont triées alphabétiquement. Pour trier par ordre numérique (par exemple pour trier selon les prix dans le menu), vous pouvez utiliser la méthode d'ensemble de données setColumnType afin de modifier le type de données de la colonne des prix qui, de texte, deviendra numérique. Cette méthode se présente sous la forme suivante : datasetName.setColumnType("columnName", "number");

Au départ de l'exemple précédent, vous allez ajouter la méthode setColumnType à la balise "head" de votre document après avoir créé l'ensemble de données (en gras) : <script type="text/javascript"> var dsSpecials = new Spry.Data.XMLDataSet("data/cafetownsend.xml", "specials/menu_item"); dsSpecials.setColumnType("price", "number"); </script>

L'expression appelle la méthode setColumnType sur l'objet d'ensemble de données dsSpecials, que vous avez déjà défini. La méthode setColumnType emploie deux paramètres : le nom de la colonne d'ensemble de données dont le type doit être modifié ("price") et le type de données désiré ("number"). Vous pouvez à présent ajouter l'attribut spry:sort à la colonne de prix, de façon à ce que les trois colonnes du tableau HTML puissent être triées lorsque l'utilisateur clique sur l'un de ses en-têtes : <div id="Specials_DIV" spry:region="dsSpecials"> <table id="Specials_Table" class="main"> <tr> <th spry:sort="item">Item</th> <th spry:sort="description">Description</th> <th spry:sort="price">Price</th> </tr> <tr spry:repeat="dsSpecials"> <td>{item}</td> <td>{description}</td> <td>{price}</td> </tr> </table> </div>

Création d'une page principale et une page de détails de base Lorsque vous utilisez des ensembles de données Spry, vous pouvez créer des régions dynamiques principale et de détail afin d'afficher plus de détails sur vos données. Une région de la page (la région principale) contrôle l'affichage des données dans une autre (la région de détail). Vous trouverez une explication du fonctionnement des régions dynamiques principale et de détail de base dans la section « Présentation et structure d'une région principale et d'une région de détail Spry - Notions de base » à la page 90. 1 Créez un ensemble de données. Voir « Création d'un ensemble de données XML Spry » à la page 99. 2 Créez la région principale en ajoutant l'attribut spry:region à l'élément HTML qui fera office de balise conteneur pour la région. Voir « Création d'une région dynamique Spry et affichage des données » à la page 101. Dans l'exemple suivant, une région dynamique principale affiche des données répétées à partir de l'ensemble de données dsSpecials :


SPRY 105 Guide de l'utilisateur

<head> . . . <script type="text/javascript" src="../includes/xpath.js"></script> <script type="text/javascript" src="../includes/SpryData.js"></script> <script type="text/javascript"> var dsSpecials = new Spry.Data.XMLDataSet("data/cafetownsend.xml", "specials/menu_item");</script> </head> . . . <body> <div id="Specials_DIV" spry:region="dsSpecials"> <table id="Specials_Table"> <tr> <th>Item</th> <th>Description</th> <th>Price</th> </tr> <tr spry:repeat="dsSpecials"> <td>{item}</td> <td>{description}</td> <td>{price}</td> </tr> </table> </div> </body>

3 Ajoutez un attribut qui permettra aux utilisateurs de modifier la ligne actuelle dans l'ensemble de données. Dans l'exemple suivant, un attribut spry:setrow (en gras) modifie la ligne actuelle dans l'ensemble de données à chaque fois qu'un utilisateur clique sur une ligne dans le tableau de la région principale : <tr spry:repeat="dsSpecials" spry:setrow="ds_Specials"> <td>{item}</td> <td>{description}</td> <td>{price}</td> </tr>

4 Créez la région dynamique de détail sur la page en ajoutant l'attribut spry:detailregion à la balise qui contiendra cette région. L'attribut utilise la syntaxe suivante : spry:detailregion="datasetName". Dans l'exemple suivant, une balise div contient la région dynamique de détail : <div id="Specials_Detail_DIV" spry:detailregion="dsSpecials"> </div>

5 Dans la balise contenant la région dynamique de détail, insérez un élément HTML qui affichera les données détaillées à partir de la ligne actuelle de l'ensemble de données. Dans l'exemple, un tableau HTML affiche des données détaillées à partir des colonnes {ingredients} et {calories} de l'ensemble de données dsSpecials. <div id="Specials_Detail_DIV" spry:detailregion="dsSpecials"> <table id="Specials_Detail_Table"> <tr> <th>Ingredients</th> <th>Calories</th> </tr> <tr> <td>{ingredients}</td> <td>{calories}</td> </tr> </table> </div>

L'exemple de code complet, qui lie les régions dynamiques principale et de détail à l'ensemble de données dsSpecials, se présenterait comme suit :


SPRY 106 Guide de l'utilisateur

<div id="Specials_DIV" spry:region="dsSpecials"> <table id="Specials_Table"> <tr> <th>Item</th> <th>Description</th> <th>Price</th> </tr> <tr spry:repeat="dsSpecials" spry:setrow="dsSpecials"> <td>{item}</td> <td>{description}</td> <td>{price}</td> </tr> </table> </div> <div id="Specials_Detail_DIV" spry:detailregion="dsSpecials"> <table id="Specials_Detail_Table"> <tr> <th>Ingredients</th> <th>Calories</th> </tr> <tr> <td>{ingredients}</td> <td>{calories}</td> </tr> </table> </div>

Création d'une page principale et une page de détails avancées Vous pouvez créer des relations entre régions principale et de détail qui impliquent plusieurs ensembles de données. Vous trouverez une explication du fonctionnement de telles relations dans la section « Présentation et structure d'une région principale et d'une région de détail Spry - Notions avancées » à la page 93. 1 Examinez attentivement la structure des fichiers XML utilisés pour créer l'ensemble de données. Vous devrez bien comprendre la structure pour rendre un ensemble de données dépendant d'un autre. 2 Créez un ensemble de données en ajoutant le code approprié à l'en-tête de votre document. Pour plus d'informations, consultez la section « Création d'un ensemble de données XML Spry » à la page 99. Il s'agit de l'ensemble de données principal. 3 Créez un deuxième ensemble de données (l'ensemble de détail) juste après l'ensemble principal que vous venez de créer. L'URL ou le XPath dans le constructeur de l'ensemble de données de détail contient une référence de données à une ou plusieurs colonnes de l'ensemble de données principal. La référence de données utilise la syntaxe suivante : {MasterDatasetName::columnName}. Dans l'exemple suivant, le troisième bloc script contient l'instruction qui crée deux ensembles de données. Le premier (principal) est nommé dsSpecials et l'autre (détail) dsIngredients: <head> . . . <script type="text/javascript" src="../includes/xpath.js"></script> <script type="text/javascript" src="../includes/SpryData.js"></script> <script type="text/javascript"> var dsSpecials = new Spry.Data.XMLDataSet("data/cafetownsend.xml", "specials/menu_item"); var dsIngredients = new Spry.Data.XMLDataSet("data/{dsSpecials::url}", "item/ingredients/ingredient"); </script> </head>

L'e chemin au fichier XML de l'ensemble de données de détail, dsIngredients, contient une référence de données ({dsSpecials::url}) à l'ensemble principal, dsSpecials. Plus précisément, elle contient une référence de données à la colonne "url" de l'ensemble de données dsSpecials. Lorsque l'argument URL ou XPath du constructeur qui crée un ensemble de données contient une référence à un autre ensemble de données, l'ensemble créé automatiquement devient observateur de celui auquel il fait référence.


SPRY 107 Guide de l'utilisateur

4 Créez la région principale en ajoutant l'attribut spry:region à l'élément HTML qui fera office de balise conteneur pour la région. Voir « Création d'une région dynamique Spry et affichage des données » à la page 101. Dans l'exemple suivant, une région dynamique principale affiche des données répétées à partir de l'ensemble de données dsSpecials : <body> <div id="Specials_DIV" spry:region="dsSpecials"> <table id="Specials_Table"> <tr> <th>Item</th> <th>Description</th> <th>Price</th> </tr> <tr spry:repeat="dsSpecials"> <td>{item}</td> <td>{description}</td> <td>{price}</td> </tr> </table> </div> </body>

5 Ajoutez un attribut qui permettra aux utilisateurs de modifier la ligne actuelle dans l'ensemble de données principal. Dans l'exemple suivant, un attribut spry:setrow (en gras) modifie la ligne actuelle dans l'ensemble de données dsSpecials à chaque fois qu'un utilisateur clique sur une ligne dans le tableau de la région principale : <tr spry:repeat="dsSpecials" spry:setrow="dsSpecials"> <td>{item}</td> <td>{description}</td> <td>{price}</td> </tr>

6 Créez la région dynamique de détail sur la page en ajoutant l'attribut spry:region à la balise qui contiendra cette région. Cet attribut utilise la syntaxe spry:region="datasetName". Remarque : Lorsque vous créez des relations principale/détail au moyen de plusieurs ensembles de données, il n'est pas nécessaire d'utiliser l'attribut spry:detailregion comme expliqué dans la section « Création d'une page principale et une page de détails de base » à la page 104. Comme la ligne actuelle de l'ensemble de données de détail ne change jamais (c'est la ligne actuelle de l'ensemble de données principal qui varie), l'attribut spry:region est suffisant. Pour plus d'informations, consultez la section « Présentation et structure d'une région principale et d'une région de détail Spry - Notions avancées » à la page 93. Dans l'exemple suivant, une balise div contient la région dynamique de détail : <div id="Specials_Detail_DIV" spry:region="dsSpecials"> </div>

7 Dans la balise contenant la région dynamique de détail, insérez un élément HTML qui affichera les données détaillées à partir de la ligne actuelle de l'ensemble de données principal. Dans l'exemple, un tableau HTML affiche des données détaillées à partir de la colonne {name} de l'ensemble de dsIngredients. L'ensemble de données dsIngredients crée la colonne {name} sur la base des informations qu'il reçoit à partir de l'ensemble de données dsSpecials. <div id="Specials_Detail_DIV" spry:region="dsIngredients"> <table id="Specials_Detail_Table"> <tr> <th>Ingredients</th> </tr> <tr spry:repeat=”dsIngredients”> <td>{name}</td> </tr> </table> </div>

L'exemple de code complet, qui lie la région principale à l'ensemble de données dsSpecials et la région de détail à l'ensemble dsIngredients, se présenterait comme suit :


SPRY 108 Guide de l'utilisateur

<head> . . . <script type="text/javascript" src="../includes/xpath.js"></script> <script type="text/javascript" src="../includes/SpryData.js"></script> <script type="text/javascript"> var dsSpecials = new Spry.Data.XMLDataSet("data/cafetownsend.xml", "specials/menu_item"); var dsIngredients = new Spry.Data.XMLDataSet("data/{dsSpecials::url}", "item/ingredients/ingredient"); </script> </head> . . . <body> <div id="Specials_DIV" spry:region="dsSpecials"> <table id="Specials_Table"> <tr> <th>Item</th> <th>Description</th> <th>Price</th> </tr> <tr spry:repeat="dsSpecials" spry:setrow="dsSpecials"> <td>{item}</td> <td>{description}</td> <td>{price}</td> </tr> </table> </div> <div id="Specials_Detail_DIV" spry:region="dsIngredients"> <table id="Specials_Detail_Table"> <tr> <th>Ingredients</th> </tr> <tr spry:repeat=”dsIngredients”> <td>{name}</td> </tr> </table> </div> . . . </body>

Obtention et manipulation de données Options de récupération d'un ensemble de données Par défaut, les ensembles de données Spry utilisent la méthode HTTP GET pour récupérer les données XML. L'ensemble de données peut également récupérer les données à l'aide de la méthode HTTP POST, en définissant des options de constructeur supplémentaires, comme suit :


SPRY 109 Guide de l'utilisateur

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1transitional.dtd"> <html xmlns="http://www.w3.org/1999/xhtml"> <head> <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1" /> <title>Dynamic Region Example</title> <script type="text/javascript" src="../../includes/xpath.js"></script> <script type="text/javascript" src="../../includes/SpryData.js"></script> <script type="text/javascript"> var dsPhotos = new Spry.Data.XMLDataSet("/photos.php", "/gallery/photos/photo", { method: "POST", postData: "galleryid=2000&offset=20&limit=10", headers: { "Content-Type": "application/x-www-formurlencoded; charset=UTF-8" } }); </script> </head> . . . <body> </body> </html>

Si vous utilisez la méthode POST sans spécifier de type de contenu, le type de contenu par défaut est fixé à "application/xwww-form-urlencoded; charset=UTF-8". Le tableau suivant présente les options de constructeur, relatives à HTTP, que vous pouvez spécifier : Option

Description

method

La méthode HTTP utilisée pour l'obtention des données XML. Il doit s'agir de la chaîne "GET" ou "POST".

postData

Il peut s'agit d'une chaîne contenant des arguments "form urlencode" ou toute valeur prise en charge par l'objet XMLHttpRequest. Si aucun en-tête "Content-Type" n'est défini en combinaison avec l'option postData, le type de contenu "application/x-www-form-urlencoded; charset=UTF-8" est utilisé.

username

Le nom d'utilisateur utilisé pour l'accès aux données XML.

password

Le mot de passe utilisé en combinaison avec "username" pour l'accès aux données XML.

headers

Objet ou plage associative qui utilise le nom de champ de requête HTTP comme sa propriété et sa clé pour le stockage de valeurs.

Désactivation de la mise en cache des données Par défaut, Spry met en cache toutes les données XML qu'un ensemble de données a chargées sur un client. Si un ensemble de données tente de charger les données XML pour une URL qui se trouve déjà en cache, Spry renvoie à l'ensemble une référence aux données mises en cache. Si plusieurs ensembles de données tentent de charger la même URL au même moment, toutes les demandes de chargement sont combinées au sein d'une seule demande HTTP afin d'économiser de la bande passante. L'emploi de la mise en cache des données et de la combinaison des demandes permet d'accroître considérablement les performances, en particulier lorsque plusieurs ensembles de données font référence aux mêmes données XML. Il peut parfois être nécessaire de charger les données directement à partir du serveur (par exemple si une URL est susceptible de renvoyer des données différentes à chaque fois que quelqu'un y accède). ❖ Pour forcer un ensemble de données à charger directement des données XML à partir du serveur, réglez l'option du constructeur XMLDataSet useCache sur "false", comme suit : var dsPhotos = new Spry.Data.XMLDataSet("/photos.php?galleryid=2000", "/gallery/photos/photo", {useCache: false })

Obtention des données Lorsque les données XML ont été chargées, elles sont mises à plat sous forme de tableau. Dans l'ensemble de données, les données sont en fait stockées sous la forme d'une plage d'objets (lignes) possédant des propriétés (colonnes) et des valeurs. L'exemple suivant montre, en gras, des données sélectionnées à l'aide du XPath /gallery/photos/photo :


SPRY 110 Guide de l'utilisateur

<gallery id="12345"> <photographer id="4532">John Doe</photographer> <email>john@doe.com</email> <photos id="2000"> <photo path="sun.jpg" width="16" height="16"/> <photo path="tree.jpg" width="16" height="16"/> <photo path="surf.jpg" width="16" height="16"/> </photos> </gallery>

L'ensemble de données met ensuite l'ensemble de noeuds à plat sous forme de tableau, représenté comme suit. @path

@width

@height

sun.jpg

16

16

tree.jpg

16

16

surf.jpg

16

16

Vous pouvez obtenir toutes les lignes de l'ensemble de données en appelant getData(). Les données sont chargées de manière asynchronse ; il n'est donc possible d'y accéder qu'après leur chargement. Il peut être utile d'enregistrer un observateur afin d'être averti lorsque les données sont prêtes. Pour plus d'informations, consultez la section « Notifications d'observateur » à la page 113. ❖ Utilisez la méthode getData() pour récupérer toutes les lignes de l'ensemble de données. Pour obtenir la valeur d'une

colonne précise, indexez la ligne à l'aide du nom de la colonne. var dsPhotos = new Spry.Data.XMLDataSet("/photos.php?galleryid=2000", "/gallery/photos/photo"); ... var rows = dsPhotos.getData(); // Get all rows. var path = rows[0]["@path"]; // Get the data in the "@path" column of the first row.

Tri des données ❖ Pour trier les lignes d'un ensemble de données sur la base des valeurs d'une colonne précise, appelez la méthode sort()

sur l'ensemble de données : var dsPhotos = new Spry.Data.XMLDataSet("/photos.php?galleryid=2000", "/gallery/photos/photo"); ... dsPhotos.sort("@path"); // Sort the rows of the data set using the "@path" column.

L'appel de la méthode sort() d'un ensemble de données permet de trier les lignes dans l'ordre croissant, sur la base des données figurant dans la colonne indiquée. La méthode sort() emploie deux arguments. Le premier argument peut être le nom de la colonne ou une plage de colonnes à utiliser pour le tri. Si le premier argument est une plage, le premier élément de celle-ci fait office de colonne de tri principale. Chaque colonne qui suit sera employée comme clé de tri secondaire, tertiaire, et ainsi de suite. Le second argument est l'ordre de tri à utiliser, qui doit être l'une des chaînes suivantes : "ascending" (croissant), "descending" (décroissant) ou "toggle" (bascule). Sil e second argument n'est pas spécifié, l'ordre de tri par défaut est "ascending". Le choix de l'ordre de tri "toggle" applique un tri de type "ascending" aux colonnes qui étaient triées en mode "descending", et vice versa. Si la colonne n'a jamais été triée auparavant et que l'ordre de tri utilisé est "toggle", ses données seront dans un premier temps triées en mode "ascending". var dsPhotos = new Spry.Data.XMLDataSet("/photos.php?galleryid=2000", "/gallery/photos/photo"); ... dsPhotos.sort("@path", "toggle"); // Toggle the Sort order of the rows of the data set using the "@path" column.

Pour que les données de l'ensemble de données soient triées automatiquement à chaque fois que des données sont chargées, spécifiez la colonne devant servir de base au tri et l'ordre de tri à utiliser comme options du constructeur de l'ensemble de données. Utilisez l'option "sortOnLoad" du constructeur de l'ensemble de données pour spécifier une colonne devant servir de base au tri. Dans l'exemple suivant, l'ensemble de données est automatiquement trié dans l'ordre décroissant sur la base des données de la colonne @path.


SPRY 111 Guide de l'utilisateur

var dsPhotos = new Spry.Data.XMLDataSet("/photos.php?galleryid=2000", "/gallery/photos/photo", { sortOnLoad: "@path", sortOrderOnLoad: "descending" });

Par défaut, toutes les valeurs de l'ensemble de données sont traitées comme du texte. Cette situation peut s'avérer problématique en cas de tri de valeurs de type numérique ou date. Vous pouvez spécifier le type de données d'une colonne précise en appelant la méthode setColumnType(). var dsPhotos = new Spry.Data.XMLDataSet("/photos.php?galleryid=2000", "/gallery/photos/photo"); dsPhotos.setColumnType("@width", "number"); dsPhotos.setColumnType("@height", "number"); ... dsPhotos.sort("@width"); // Sort the rows of the data set using the "@width" column.

Les types de données actuellement pris en charge sont "number" (numérique), "date" et "string" (chaîne).

Définition ou modification de la ligne actuelle Chaque ensemble de données emploie la notion de ligne actuelle. Par défaut, la ligne actuelle est la première ligne de l'ensemble de données. Pour modifier la ligne actuelle par voie de programmation, appelez la méthode setCurrentRowNumber() et transmettez le numéro de la ligne qui doit devenir la ligne active. L'index de la première ligne est toujours 0. Dès lors, si un ensemble de données contient 10 lignes, l'index de la dernière ligne sera 9. ❖ Utilisez setCurrentRowByNumber() ou setCurrentRow() pour modifier la ligne actuelle : var dsPhotos = new Spry.Data.XMLDataSet("/photos.php?galleryid=2000", "/gallery/photos/photo"); ... dsPhotos.setCurrentRowNumber(2); // Make the 3rd row in the data set the current row.

Chaque ligne de l'ensemble de données reçoit également un ID unique. Cet ID vous permet de faire référence à une ligne précise de l'ensemble de données, même après un changement de l'ordre des lignes dans l'ensemble de données. Vous pouvez obtenir l'ID d'une ligne en accédant à sa propriété "ds_RowID". Vous pouvez également modifier la ligne actuelle en appelant setCurrentRow() puis en transmettant l'ID de la ligne qui doit devenir la ligne active. var dsPhotos = new Spry.Data.XMLDataSet("/photos.php?galleryid=2000", "/gallery/photos/photo"); ... var id = dsPhotos.getData()[2]["ds_RowID"]; // Get the ID of the 3rd row. ... dsPhotos.setCurrentRow(id); // Make the 3rd row the current row by using its ID.

Suppression de lignes en double ❖ La méthode distinct() permet de supprimer les lignes en double d'un ensemble de données : var dsPhotos = new Spry.Data.XMLDataSet("/photos.php?galleryid=2000", "/gallery/photos/photo"); ... dsPhotos.distinct(); // Remove all duplicate rows.

Dans ce contexte, le terme ligne en double fait référence à une situation où chaque colonne de l'ensemble de données contient des informations identiques pour plusieurs lignes. Pour que la méthode distinct() soit exécutée automatiquement à chaque fois que des données sont chargées dans un ensemble de données, utilisez l'option "distinctOnLoad" avec le constructeur. var dsPhotos = new Spry.Data.XMLDataSet("/photos.php?galleryid=2000", "/gallery/photos/photo", { distinctOnLoad: true });

La méthode distinct() est destructrice ; elle supprime toutes les lignes non distinctes. La seule manière de récupérer les données consiste à recharger les données XML.

Filtrage des données Les ensembles de données acceptent les fonctions de filtrage destructrices et non destructrices.


SPRY 112 Guide de l'utilisateur

Avant d'utiliser l'une des méthodes de filtrage, fournissez une fonction de filtrage qui s'applique à un ensemble de données, un objet de ligne et un numéro de ligne. Cette fonction est appelée par les méthodes de filtrage des ensembles de données pour chaque ligne d'un ensemble. La fonction doit renvoyer l'objet de ligne transmis à la fonction ou un nouvel objet de ligne destiné à remplacer la ligne transmise dans la fonction. Pour que la fonction élimine une ligne filtrée, elle doit renvoyer une valeur nulle. La méthode de filtrage destructrice d'un ensemble de données est filterData(). Cette méthode remplace ou supprime les lignes de l'ensemble de données. La seule manière de récupérer les données d'origine consiste à recharger les données XML de l'ensemble de données. ❖ Utilisez la méthode destructrice filterData() pour supprimer définitivement des lignes d'un ensemble de données : ... // Filter out all rows that don't have a path that begins // with the letter 's'. var myFilterFunc = function(dataSet, row, rowNumber) { if (row["@path"].search(/^s/) != -1) return row; // Return the row to keep it in the data set. return null; // Return null to remove the row from the data set. }dsPhotos.filterData(myFilterFunc); // Filter the rows in the data set.

La fonction de filtrage reste active, même en cas de chargement de données XML depuis une autre URL, jusqu'à ce que vous appeliez filterData() avec un argument null. Appelez filterData() avec un argument null pour désactiver votre fonction de filtrage. dsPhotos.filterData(null); // Turn off destructive filtering.

La méthode de filtrage non destructrice d'un ensemble de données est filter(). Contrairement à filterData(), filter() crée une nouvelle plage de lignes qui font référence aux données d'origine. Tant que la fonction de filtrage ne modifie pas l'objet de ligne qui lui est transmis, vous pouvez récupérer les données d'origine en appelant filter() en transmettant un argument null. Utilisez la méthode non destructrice filter() pour filtrer les lignes d'un ensemble de données : var dsPhotos = new Spry.Data.XMLDataSet("/photos.php?galleryid=2000", "/gallery/photos/photo"); ... // Filter out all rows that don't have a path that begins // with the letter 's'. var myFilterFunc = function(dataSet, row, rowNumber) { if (row["@path"].search(/^s/) != -1) return row; // Return the row to keep it in the data set. return null; // Return null to remove the row from the data set. }dsPhotos.filter(myFilterFunc); // Filter the rows in the data set.

Pour récupérer les données d'origine, appelez filter() et transmettez un argumentnull. dsPhotos.filter(null); // Turn off non-destructive filtering.

Actualisation des données Les ensembles de données peuvent recharger leurs données selon un intervalle précis, exprimé en millisecondes. Cette fonctionnalité peut s'avérer pratique lorsque les données d'une URL spécifique changent régulièrement. ❖ Pour ordonner à un ensemble de données de se charger selon un intervalle précis, transmettez l'option facultative loadInterval lors de l'appel du constructeur XMLDataSet : // Load the data every 10 seconds. Turn off the cache to make sure we get it directly from the server. var dsPhotos = new Spry.Data.XMLDataSet("/photos.php?galleryid=2000", "/gallery/photos/photo", { useCache: false, loadInterval: 10000 });

Vous pouvez également activer ce chargement périodique par voie de programmation au moyen de la méthode startLoadInterval() et le désactiver à l'aide de la méthode stopLoadInterval(). dsPhotos.startLoadInterval(10000); // Start loading data every 10 seconds. ... dsPhotos.stopLoadInterval(); // Turn off interval loading.


SPRY 113 Guide de l'utilisateur

Notifications d'observateur Présentation des notifications d'observateur

L'ensemble de données XML prend en charge un mécanisme d'observation qui permet à un objet ou à une fonction de rappel de recevoir des notifications d'événement. Notification

Description

onPreLoad

L'ensemble de données est sur le point d'envoyer une demande de données. Si les données dépendent d'autres ensembles de données, cette notification d'événement ne sera pas envoyée tant qu'ils n'ont pas tous été chargés correctement.

onPostLoad

La demande de données a réussi. Les données sont accessibles.

onLoadError

Une erreur s'est produite lors de la demande des données.

onDataChanged

Les données dans l'ensemble de données ont été modifiées.

onPreSort

Les données dans l'ensemble de données sont sur le point d'être triées.

onPostSort

Les données dans l'ensemble de données ont été triées.

onCurrentRowChanged

La notion de ligne actuelle de l'ensemble de données a été modifiée.

Objets en tant qu'observateurs

Pour recevoir des notifications, un objet doit définir une méthode pour chaque notification dont la réception l'intéresse, puis s'enregistrer en tant qu'observateur de l'ensemble de données. Par exemple, un objet intéressé par les notifications onDataChanged doit définir une méthode onDataChanged() puis appeler addObserver(). var dsPhotos = new Spry.Data.XMLDataSet("/photos.php?galleryid=2000", "/gallery/photos/photo"); ... var myObserver = new Object; myObserver.onDataChanged = function(dataSet, data) { alert("onDataChanged called!"); }; dsPhotos.addObserver(myObserver);

Le premier argument de chaque méthode de notification est l'objet qui envoie la notification. Pour les observateurs d'ensembles de données, il s'agit toujours de l'objet dataSet. Le second argument peut être indéfini ou être un objet qui dépend du type de notification. Notification

Données transmises dans la notification

onPreLoad

non défini

onPostLoad

non défini

onLoadError

L'objet Spry.Utils.loadURL.Request qui a été utilisé pour la demande.

onDataChanged

non défini

onPreSort

Objet possédant les propriétés suivantes : oldSortColumns: Plage de colonnes utilisées au cours du dernier tri. oldSortOrder: Ordre de tri utilisé lors du dernier tri. newSortColumns: Plage de colonnes qui va être utilisée pour le tri. newSortOrder: Ordre de tri sur le point d'être utilisé.


SPRY 114 Guide de l'utilisateur

Notification

Données transmises dans la notification

onPostSort

Objet possédant les propriétés suivantes : oldSortColumns: Plage de colonnes utilisées dans le tri précédent. oldSortOrder: Ordre de tri utilisé lors du tri précédent. newSortColumns: Plage de colonnes utilisée pour le tri. newSortOrder: Ordre de tri utilisé lors pour le tri.

onCurrentRowChanged

Objet possédant les propriétés suivantes : oldRowID: Le ds_RowID de la dernière ligne actuelle. newRowID: Le ds_RowID de la ligne actuelle.

Pour arrêter la réception de notifications par un objet, ce dernier doit être supprimé de la liste d'observateurs par un appel de removeObserver(). var dsPhotos = new Spry.Data.XMLDataSet("/photos.php?galleryid=2000", "/gallery/photos/photo"); ... dsPhotos.removeObserver(myObserver);

Fonctions en tant qu'observateurs

Les fonctions peuvent elles aussi être enregistrées comme observateurs. La principale différence entre les observateurs de type objet et de type fonction est qu'un objet n'est averti que pour les méthodes de notification qu'il définit, alors qu'un observateur de type fonction est appelé pour chaque type de notification d'événement. var dsPhotos = new Spry.Data.XMLDataSet("/photos.php?galleryid=2000", "/gallery/photos/photo"); ... function myObserverFunc(notificationType, dataSet, data) { if (notificationType == "onDataChanged") alert("onDataChanged called!"; else if (notificationType == "onPostSort") alert("onPostSort called!"; }; dsPhotos.addObserver(myObserverFunc);

Un observateur de type fonction est enregistré par le même appel de addObserver. Lorsque la fonction est appelée, le premier argument qui lui est transmis est le type de notification. Il s'agit d'une chaîne qui contient le nom de la notification. Le deuxième argument est le notificateur (dans ce cas, l'ensemble de données) et le troisième contient les données de la notification. Pour arrêter la réception de notifications par un observateur de type fonction, ce dernier doit être supprimé de la liste d'observateurs par un appel de removeObserver(). var dsPhotos = new Spry.Data.XMLDataSet("/photos.php?galleryid=2000", "/gallery/photos/photo"); ... dsPhotos.removeObserver(myObserverFunc);

Utilisation des régions dynamiques Structures de boucle A l'heure actuelle, les régions dynamiques prennent en charge deux structures de boucle. L'une permet de répéter un élément et tout son contenu pour chaque ligne d'un ensemble de données précis (spry:repeat), et l'autre de répéter tous les enfants d'un élément précis pour chaque ligne d'un ensemble de données donné (spry:repeatchildren).


SPRY 115 Guide de l'utilisateur

Pour désigner un élément comme étant répété, ajoutez à ce dernier un attribut spry:repeat dont la valeur est le nom de l'ensemble de données à répéter. L'exemple suivant montre un bloc li qui se répète pour chaque ligne de l'ensemble de donnéesdsPhotos. <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1transitional.dtd"> <html xmlns="http://www.w3.org/1999/xhtml" xmlns:spry="http://ns.adobe.com/spry"> <head> <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1" /> <title>Dynamic Region Example</title> <script type="text/javascript" src="../../includes/xpath.js"></script> <script type="text/javascript" src="../../includes/SpryData.js"></script> <script type="text/javascript"> var dsPhotos = new Spry.Data.XMLDataSet("/photos.php?galleryid=2000", "/gallery/photos/photo"); </script> </head> <body> <div spry:region="dsPhotos"> <ul> <li spry:repeat="dsPhotos">{@path}</li> </ul> </div> </body> </html>

Pour ne répéter que les enfants d'un élément, utilisez plutôt l'attribut spry:repeatchildren. Dans l'exemple suivant, les enfants de la balise ul se répètent pour chaque ligne de l'ensemble de données dsPhotos : <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1transitional.dtd"> <html xmlns="http://www.w3.org/1999/xhtml" xmlns:spry="http://ns.adobe.com/spry"> <head> <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1" /> <title>Dynamic Region Example</title> <script type="text/javascript" src="../../includes/xpath.js"></script> <script type="text/javascript" src="../../includes/SpryData.js"></script> <script type="text/javascript"> var dsPhotos = new Spry.Data.XMLDataSet("/photos.php?galleryid=2000", "/gallery/photos/photo"); </script> </head> <body> <div spry:region="dsPhotos"> <ul spry:repeatchildren="dsPhotos"> <li>{@path}</li> </ul> </div> </body> </html>

Les exemples "spry:repeat" et "spry:repeatchildren" précédents sont équivalents d'un point de vue fonctionnel, mais "spry:repeatchildren" est plus utile pour un emploi en combinaison avec des structures conditionnelles. Les deux exemples donnent le résultat suivant :


SPRY 116 Guide de l'utilisateur

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1transitional.dtd"> <html xmlns="http://www.w3.org/1999/xhtml" xmlns:spry="http://ns.adobe.com/spry"> <head> <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1" /> <title>Dynamic Region Example</title> <script type="text/javascript" src="../../includes/xpath.js"></script> <script type="text/javascript" src="../../includes/SpryData.js"></script> <script type="text/javascript"> var dsPhotos = new Spry.Data.XMLDataSet("/photos.php?galleryid=2000", "/gallery/photos/photo"); </script> </head> <body> <div> <ul> <li>sun.jpg</li> <li>tree.jpg</li> <li>surf.jpg</li> </ul> </div> </body> </html>

Si vous ne voulez pas envoyer le contenu d'une région répétée pour chaque ligne de l'ensemble de données, limitez ce qui est écrit au cours du traitement de la boucle en ajoutant un attributspry:test à l'élément auquel l'attribut spry:repeat or spry:repeatchildren est appliqué. L'exemple suivant montre un bloc li qui n'est produit que si la première lettre de la valeur de{@path} est un s: <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1transitional.dtd"> <html xmlns="http://www.w3.org/1999/xhtml" xmlns:spry="http://ns.adobe.com/spry"> <head> <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1" /> <title>Dynamic Region Example</title> <script type="text/javascript" src="../../includes/xpath.js"></script> <script type="text/javascript" src="../../includes/SpryData.js"></script> <script type="text/javascript"> var dsPhotos = new Spry.Data.XMLDataSet("/photos.php?galleryid=2000", "/gallery/photos/photo"); </script> </head> <body> <div spry:region="dsPhotos"> <ul> <li spry:repeat="dsPhotos" spry:test="'{@path}'.search(/^s/) != -1;">{@path}</li> </ul> </div> </body> </html>

La valeur de cet attribut spry:test peut être n'importe quelle expression JavaScript qui produit zéro,false ou une valeur non nulle. Si l'expression renvoie une valeur non nulle, le contenu est produit. Comme vous employez du code XHTML, tout caractère spécial, tel que &, < ou > susceptible d'être utilisé dans une expression JavaScript doit être converti en entité HTML. Vous pouvez également utiliser des références dans cette expression JavaScript. Le moteur de traitement de région dynamique fournit les valeurs réelles à partir d'un ensemble de données juste avant d'évaluer l'expression spry:test. Le code suivant montre le résultat final de l'exemple précédent :


SPRY 117 Guide de l'utilisateur

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1transitional.dtd"> <html xmlns="http://www.w3.org/1999/xhtml" xmlns:spry="http://ns.adobe.com/spry"> <head> <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1" /> <title>Dynamic Region Example</title> <script type="text/javascript" src="../../includes/xpath.js"></script> <script type="text/javascript" src="../../includes/SpryData.js"></script> <script type="text/javascript"> var dsPhotos = new Spry.Data.XMLDataSet("/photos.php?galleryid=2000", "/gallery/photos/photo"); </script> </head> <body> <div> <ul> <li>sun.jpg</li> <li>surf.jpg</li> </ul> </div> </body> </html>

Structures conditionnelles A l'heure actuelle, les régions dynamiques prennent en charge deux structures conditionnelles. La première est "spry:if". Dans l'exemple suivant, la balise li n'est écrite que si la valeur de {@path} commence par la lettre s: <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1transitional.dtd"> <html xmlns="http://www.w3.org/1999/xhtml" xmlns:spry="http://ns.adobe.com/spry"> <head> <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1" /> <title>Dynamic Region Example</title> <script type="text/javascript" src="../../includes/xpath.js"></script> <script type="text/javascript" src="../../includes/SpryData.js"></script> <script type="text/javascript"> var dsPhotos = new Spry.Data.XMLDataSet("/photos.php?galleryid=2000", "/gallery/photos/photo"); </script> </head> <body> <div spry:region="dsPhotos"> <ul class="spry:repeat"> <li spry:if="'{@path}'.search(/^s/) != -1;">{@path}</li> </ul> </div> </body> </html>

Pour rendre un élément conditionnel, ajoutez-y un attribut spry:if avec une valeur qui est une expression JavaScript renvoyant des valeurs nulles ou non nulles. Une valeur non nulle renvoyée par l'expression JavaScript entraîne l'écriture de l'élément dans le résultat final. Si vous voulez disposer d'une structure "si/alors", optez pour "spry:choose". L'exemple suivant utilise la structure spry:choose pour colorer une balise div sur deux :


SPRY 118 Guide de l'utilisateur

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1transitional.dtd"> <html xmlns="http://www.w3.org/1999/xhtml" xmlns:spry="http://ns.adobe.com/spry"> <head> <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1" /> <title>Dynamic Region Example</title> <script type="text/javascript" src="../../includes/xpath.js"></script> <script type="text/javascript" src="../../includes/SpryData.js"></script> <script type="text/javascript"> var dsPhotos = new Spry.Data.XMLDataSet("/photos.php?galleryid=2000", "/gallery/photos/photo"); </script> </head> <body> <div spry:region="dsPhotos"> <div spry:choose="spry:choose"> <div spry:when="'{@path}' == 'surf.gif'">{@path}</div> <div spry:when="'{@path}' == 'undefined'">Path was not defined.</div> <div spry:default="spry:default">Unexpected value for path!</div> </div> </div> </body> </html>

La structure spry:choose fournit des fonctionnalités équivalentes à une instruction "case" ou une structure "si/alors si/alors". Pour créer une structure spry:choose, ajoutez un attribut spry:choose à un élément. Ensuite, ajoutez un ou plusieurs éléments enfants possédant des attributs spry:when. La valeur d'un attribut spry:when doit être une expression JavaScript renvoyant des valeurs nulles ou des valeurs non nulles. Pour définir un cas par défaut, si toutes les expressions JavaScript pour chaque attribut spry:when renvoient zéro ou false, ajoutez un élément possédant un attribut spry:default. L'attribut spry:default n'exige pas de valeur, mais la norme XHTML stipule que tous les attributs doivent posséder une valeur. Donnez par conséquent à l'attribut une valeur égale à son nom. Le moteur de traitement des régions évalue l'attribut spry:when de chaque noeud selon l'ordre dans lequel ils figurent sous leur élément parent. L'élément spry:default est toujours évalué en dernier lieu, et uniquement si aucune expression spry:when ne renvoie de valeur non nulle.

Etats des régions Spry prend en charge le concept d'états des régions. En d'autres termes, à tout moment, une région peut être en train de charger des données, prête à les afficher ou être en état d'erreur parce qu'un ou plusieurs des ensembles de données auxquels elle est liée n'a pas réussi à charger ses données. Vous pouvez placer un attribut spry:state, avec une valeur "loading" (chargement), "error", (erreur) ou "ready" (prêt) dans des éléments qui se trouvent à l'intérieur d'un conteneur de région, de manière à l'associer à un état de région spécifique. Ce principe peut s'avérer utile pour l'affichage d'un message de chargement, pendant que les données d'une région sont chargées, ou pour avertir l'utilisateur que la région n'a pas réussi à obtenir ses données. A mesure que les états d'une région changent, elle régénère automatiquement son code et affiche les éléments possédant un attribut spry:state qui correspond à l'état actuel. L'exemple suivant utilise l'attribut spry:state pour afficher des messages de chargement et d'erreur : <div spry:region="dsEmployees"> <div spry:state="loading">Loading employee data ...</div> <div spry:state="error">Failed to load employee data!</div> <ul spry:state="ready"> <li spry:repeat="dsEmployees">{firstname} {lastname}</li> </ul> </div>

Tout contenu auquel aucun attribut spry:state ne s'applique, ou qui n'est ni l'enfant ni le descendant d'un élément auquel un tel attribut spry:state s'applique, est toujours inclus dans la sortie lorsque le code est régénéré. De même, les enfants ou les descendants d'un élément possédant l'attribut spry:state ne peuvent pas posséder d'attributs spry:state. En d'autres termes, il n'est pas permis d'imbriquer des éléments possédant des attributs spry:state.


SPRY 119 Guide de l'utilisateur

Notifications d'observateur de région Spry prend en charge un mécanisme d'observateur qui permet au développeur d'enregistrer un object ou une fonction de sorte à ce qu'il reçoive une notification lorsque l'état d'une région change. Ce mécanisme est pratiquement identique à celui utilisé pour les ensembles de données, avec les exceptions suivantes :

• L'ajout et la suppression d'observateurs de région s'effectue à l'aide des fonctions "namespaced" globales Spry.Data.Region.addObserver() et Spry.Data.Region.removeObserver. Ce principe est différent de celui appliqué

aux ensembles de données, dont les observateurs appellent les méthodes addObserver() et removeObserver() qui sont appliquées à l'objet d'ensemble de données. L'emploi de fonctions namespaced globales permet au développeur d'enregistrer un observateur avant le début de l'événement onload du document, et avant que Spry crée l'objet JavaScript qui représente la région. Les régions utilisent des fonctions addObserver et removeObserver, car il se peut que le développeur souhaite enregistrer des observateurs avant que l'objet de région JavaScript existe réellement.

• Les fonctions addObserver() et removeObserver() exigent un ID pour identifier la région que le développeur veut observer. C'est la raison pour laquelle les régions qu'un développeur veut observer doivent posséder un attribut id défini dans leur noeud conteneur de région. Objets en tant qu'observateurs de région

Pour recevoir des notifications, un objet doit définir une méthode pour chaque notification dont la réception l'intéresse, puis s'enregistrer en tant qu'observateur de la région. L'exemple suivant montre un objet qui est enregistré comme observateur d'une région dynamique : <script> ... // Create an observer object and define the methods to receive the notifications // it wants. myObserver = new Object; myObserver.onPostUpdate = function(notifier, data) { alert("onPostUpdate called for " + data.regionID); }; ... // Call addObserver() to register the object as an observer. Spry.Data.Region.addObserver("employeeListRegion", myObserver); ... // You can unregister your object so it stops recieving notifications // with a call to removeObserver(). Spry.Data.Region.removeObserver("employeeListRegion", myObserver); ... </script> ... <ul id="employeeListRegion" spry:region="dsEmployees"> ... </ul>

Le premier argument de chaque méthode de notification est l'objet qui envoie la notification. Pour les observateurs de région, il ne s'agit pas de l'objet de région. Le second argument est un objet qui contient une propriété regionID identifiant la région qui a déclenché la notification. Pour arrêter la réception de notifications par un objet, ce dernier doit être supprimé de la liste d'observateurs par un appel de removeObserver(). Fonctions en tant qu'observateurs de région

Les fonctions peuvent elles aussi être enregistrées comme observateurs. La principale différence entre les observateurs de type objet et de type fonction est qu'un objet n'est averti que pour les méthodes de notification qu'il définit, alors qu'un observateur de type fonction est appelé pour chaque type de notification d'événement. L'exemple suivant montre une fonction qui est enregistrée comme observateur d'une région dynamique :


SPRY 120 Guide de l'utilisateur

<script> ... function myRegionCallback(notificationState, notifier, data) { if (notificationType == "onPreUpdate") alert(regionID + " is starting an update!"); else if (notificationType == "onPostUpdate") alert(regionID + " is done updating!"); } ... // Call addObserver() to register your function as an observer. Spry.Data.Region.addObserver("employeeListRegion", MyRegionCallback); ... // You can unregister your callback function so it stops recieving notifications // with a call to removeObserver(). Spry.Data.Region.removeObserver("employeeListRegion", MyRegionCallback); ... </script> ... <ul id="employeeListRegion" spry:region="dsEmployees"> ... </ul>

Un observateur de type fonction est enregistré par le même appel de addObserver(). Lorsque la fonction est appelée, le premier argument qui lui est transmis est le type de notification. Il s'agit d'une chaîne qui contient le nom de la notification. Le deuxième argument est le notificateur qui, dans ce cas, n'est pas l'objet de région. Le troisième argument est un objet de données possédant une propriété regionID qui indique quelle région a provoqué la notification. Pour arrêter la réception de notifications par un observateur de type fonction, ce dernier doit être supprimé de la liste d'observateurs par un appel de removeObserver(). Les notifications actuellement prises en charge sont présentées dans le tableau ci-dessous. Type de notification de région

Description

onLoadingData

Un ou plusieurs des ensembles de données liés à la région est en train de charger ses données.

onPreUpdate

Tous les ensembles de données liés à la région ont été chargés. La région est sur le point de régénérer son code.

onPostUpdate

La région a régénéré son code et l'a inséré dans le document.

onError

Une erreur s'est produite lors du chargement des données.

Options de référence de données Chaque ensemble de données comprend un jeu de références de données intégrées qui peuvent s'avérer utiles pendant le processus de régénération d'une région dynamique. Comme les noms de colonnes d'un ensemble de données, ces références de données intégrées doivent débuter par le nom de l'ensemble de données si la région dynamique est liée à plusieurs de ces ensembles. Par exemple, pour afficher le numéro de la ligne actuelle de l'ensemble de données lorsque la région est régénérée, ajoutez la référence de données ds_RowNumber à la région dynamique, comme suit : <tr spry:repeat="dsSpecials"> <td>{item}</td> <td>{description}</td> <td>{price}</td> <td>{ds_RowNumber}</td> </tr>

Ces options sont également utiles pour transmettre une valeur dans une méthode JavaScript, comme suit :


SPRY 121 Guide de l'utilisateur

<tr spry:repeat="dsSpecials" onclick="dsSpecials.setCurrentRow('{ds_RowID}')"> <td>{item}</td> <td>{description}</td> <td>{price}</td> </tr>

Le tableau ci-dessous fournit la liste complète des références de données intégrées de Spry. Référence de données

Description

ds_RowID

L'ID d'une ligne dans l'ensemble de données. Cet ID peut être utilisé pour faire référence à un enregistrement précis dans l'ensemble de données. Il ne change pas, même lorsque les données sont triées.

ds_RowNumber

Numéro de la ligne actuelle de l'ensemble de données. Dans une structure en boucle, ce numéro correspond à la position de la ligne en cours d'évaluation.

ds_RowNumberPlus1

Identique à ds_RowNumber, à ceci près que la première ligne débute à la position d'index 1 au lieu de 0.

ds_RowCount

Nombre de lignes dans l'ensemble de données. Si un filtre non destructeur est appliqué à l'ensemble de données, il s'agit du nombre total de lignes après l'application du filtre.

ds_UnfilteredRowCount

Nombre de lignes dans l'ensemble de données avant l'application de tout filtre non destructeur.

ds_CurrentRowID

ID de la ligne actuelle de l'ensemble de données. Cette valeur ne change pas, même en cas d'utilisation dans une structure en boucle.

ds_CurrentRowNumber

Numéro de la ligne actuelle de l'ensemble de données. Cette valeur ne change pas, même en cas d'utilisation dans une structure en boucle.

ds_SortColumn

Nom de la dernière colonne utilisée pour un tri. Si les données de l'ensemble de données n'ont jamais été triées, cette référence renvoie une chaîne vide.

ds_SortOrder

Ordre de tri actuel des données dans l'ensemble de données. Cette référence de données renvoie les mots ascending (croissant), descending (décroissant), ou une chaîne vide.

ds_EvenOddRow

Examine la valeur actuelle de ds_RowNumber et renvoie la chaîne"even" (pair) ou "odd" (impair). Elle peut être utile pour faire alterner la coloration des lignes.

Masquage des références de données Dans certains navigateurs, le chargement de pages via une connexion lente peut entraîner l'affichage momentané des régions et références de données non traitées sur la page avant l'envoi de la notification onload du document. Pour masquer les régions et les références de données non traitées, vous pouvez fournir une règle CSS pour la classe SpryHiddenRegion : <style>.SpryHiddenRegion {visibility:hidden;} </style> ... <div spry:region="dsEmployees" class="SpryHiddenRegion"> ... </div>

Cette technique permet à la règle CSS de masquer les régions Spry possédant cette classe pendant le chargement de la la page. Lorsque le traitement des données Spry est terminé, Spry élimine la classe SpryHiddenRegion, après quoi le contenu Spry terminé s'affiche. Une autre façon de masquer uniquement les références de données, au lieu de la balise entière, consiste à employer l'attribut spry:content comme substitut d'une référence de données. Comme la référence de données est la valeur de l'attribut spry:content, elle n'est pas visible pendant le chargement de la page. L'exemple suivant masque une référence de données avec un attribut spry:content sur un élément :


SPRY 122 Guide de l'utilisateur

<!--Example of a normal region.--> <div spry:region="dsEmployees"> Hello my name is {firstname}. </div> <!--Example of a region using spry:content.--> Hello my name is <span spry:content="{firstname}"></span>. </div>

L'attribut spry:content remplace le contenu entier de la balise div par la valeur de l'attribut. Dans ce cas, la valeur de {firstname} est insérée dans la balise span vide. Le résultat est identique, mais dans ce cas, il n'existe aucune référence de données visible.

Attributs de comportement Vous pouvez appliquer des attributs de comportement à des éléments d'une région dynamique afin d'activer automatiquement des comportements communs qui exigeraient un peu de programmation manuelle. spry:hover

L'attribut spry:hover place un nom de classe sur un élément à chaque fois que le pointeur de la souris entre dans cet élément, et supprime le nom de classe lorsque le pointeur en sort. La valeur de l'attribut spry:hover est le nom de la classe à appliquer à l'élément à chaque fois que le pointeur de la souris y entre ou en sort. <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1transitional.dtd"> <html xmlns="http://www.w3.org/1999/xhtml" xmlns:spry="http://ns.adobe.com/spry"> <head> <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1" /> <title>Behavior Attributes Example</title> <style> .myHoverClass { background-color: yellow; } </style> <script type="text/javascript" src="../../includes/xpath.js"></script> <script type="text/javascript" src="../../includes/SpryData.js"></script><script type="text/javascript"> var dsEmployees = new Spry.Data.XMLDataSet("../../data/employees-01.xml", "/employees/employee"); </script> </head> <body> <div spry:region="dsEmployees"> <ul> <li spry:repeat="dsEmployees" spry:hover="myHoverClass">{username}</li> </ul> </div> </body> </html>

Dans l'exemple précédent, à chaque fois que le pointeur entre dans un élément li, le nom de classe"myHoverClass" est ajouté à l'attribut de classe de cet élément. Il est automatiquement supprimé lorsque le pointeur quitte l'élément. spry:select

L'attribut spry:select place un nom de classe sur un élément à chaque fois que l'utilisateur clique dessus à l'aide de la souris. La valeur de l'attribut spry:select est le nom de la classe à appliquer à l'élément à chaque fois que l'utilisateur clique sur l'élément..


SPRY 123 Guide de l'utilisateur

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1transitional.dtd"> <html xmlns="http://www.w3.org/1999/xhtml" xmlns:spry="http://ns.adobe.com/spry"> <head> <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1" /> <title>Behavior Attributes Example</title> <style> .myHoverClass { background-color: yellow; } .mySelectClass {color: white;background-color: black;} </style> <script type="text/javascript" src="../../includes/xpath.js"></script> <script type="text/javascript" src="../../includes/SpryData.js"></script><script type="text/javascript">var dsEmployees = new Spry.Data.XMLDataSet("../../data/employees-01.xml", "/employees/employee"); </script> </head> <body> <div spry:region="dsEmployees"> <ul> <li spry:repeat="dsEmployees" spry:hover="myHoverClass" spry:select="mySelectClass">{username}</li> </ul> </div> </body> </html>

Dans l'exemple précédent, à chaque fois que l'utilisateur clique sur un élément li, le nom de classemySelectClass est ajouté à l'attribut de classe de cet élément. Si un élément de la page possédant un attribut spry:select était sélectionné précédemment, le nom de classe utilisé comme valeur pour son attribut spry:select est supprimé automatiquement, ce qui a pour effet de désélectionner l'élément. Vous pouvez employer un attribut spry:selectgroup en combinaison avec un attribut spry:select de manière à définir plusieurs groupes de sélections sur une page. Vous trouverez un exemple pratique de ce principe (lecteur RSS) dans le dossier "demos" du dossier Spry d'Adobe Labs.


SPRY 124 Guide de l'utilisateur

<html xmlns="http://www.w3.org/1999/xhtml" xmlns:spry="http://ns.adobe.com/spry"> <head> <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1" /> <title>Behavior Attributes Example</title> <style> .myHoverClass { background-color: yellow; } .mySelectClass {color: white;background-color: black;} .myOtherSelectClass {color: white;background-color: black;} </style> <script type="text/javascript" src="../../includes/xpath.js"></script><script type="text/javascript" src="../../includes/SpryData.js"></script><script type="text/javascript"> var dsEmployees = new Spry.Data.XMLDataSet("../../data/employees-01.xml", "/employees/employee"); </script></head><body><div spry:region="dsEmployees"> <ul> <li spry:repeat="dsEmployees" spry:hover="myHoverClass" spry:select="mySelectClass" spry:selectgroup="username">{username}</li></ul> <ul> <li spry:repeat="dsEmployees" spry:hover="myHoverClass" spry:select="myOtherSelectClass" spry:selectgroup="firstname">{firstname}</li> </ul> </div> </body></html>

La valeur d'un attribut spry:selectgroup est un nom arbitraire. Tout élément qui emploie le même nom pour son attribut spry:selectgroup est automatiquement désélectionné lorsque l'utilisateur clique sur un autre élément possédant le même nom de groupe de sélections. Cette action n'a aucun effet sur les éléments dont les valeurs spry:selectgroup sont différentes.


125

Chapitre 4 : Utilisation des effets Spry A propos des effets Spry A propos des effets Spry Les effets sont des améliorations visuelles que vous pouvez appliquer à pratiquement n'importe quel élément d'une page HTML. Par exemple, un effet pourrait servir à surligner des informations, créer des transitions animées ou modifier visuellement un élément de page pendant un certain délai. Les effets sont une manière simple et élégante d'améliorer l'apparence de votre site Web. Le terme "effets" fait référence à des méthodes et fonctions JavaScript qui résident sur le client et dont le fonctionnement n'exige ni logique côté serveur ni scripts. Ainsi, lorsqu'un utilisateur accède à une page HTML et déclenche un effet, seul l'objet auquel cet effet s'applique est mis à jour. Il n'est pas nécessaire d'actualiser la page entière. Le cadre applicatif Spry pour AJAX comprend les effets suivants : Fondu Fait apparaître ou disparaître lentement un élément. Surlignage Modifie la couleur d'arrière-plan d'un élément. Store monté/Store baissé Simule l'effet d'un store qui monte ou descend pour afficher ou masquer l'élément. Glisser vers le haut/Glisser vers le bas Fait monter ou descendre l'élément. Agrandissement Augmente ou diminue la taille de l'élément. Secouer Donne l'impression que l'élément est secoué de gauche à droite. Ecraser Fait disparaître l'élément dans le coin supérieur gauche de la page.

Adobe a conçu les effets Spry de sorte qu'il soit facile de les mettre en oeuvre sur la page tout en laissant le cadre faire le gros du travail. Il n'est pas nécessaire d'employer de nouvelles alises ni de syntaxes compliquées. L'élément HTML auquel vous appliquez l'effet n'exige pas de balises personnalisées. Remarque : Plusieurs bibliothèques d'effets sont disponibles. Adobe considère comme tout à fait justifiée l'acceptation, par la communauté, de la bibliothèque Script.aculo.us, particulièrement bien conçue. Adobe a dès lors adopté sa liste d'effets ainsi que sa nomenclature, et a mis en oeuvre plusieurs solutions de Script.aculo.us pour les problèmes de navigateur relatives aux effets. Adobe tient à souligner le travail réalisé par Thomas Fuchs, de Script.aculo.us, et espère que la communauté reconnaîtra l'utilité et la viabilité des deux bibliothèques. En outre, Adobe a fait en sorte que les développeurs puissent employer les deux bibliothèques sur une même page.

A propos de la bibliothèque d'effets Spry La bibliothèque d'effets Spry, qui se trouve dans le fichier SpryEffects.js, contient tous les effets Spry disponibles sur le site Adobe Labs. Ce fichier n'a aucune autre dépendance. Avant d'ajouter des effets à une page, vous devez lier le fichier SpryEffects.js dans l'en-tête du document HTML, en procédant comme suit : <script type="text/javascript" src="../includes/SpryEffects.js>"></script>

Remarque : Le chemin d'accès précis du fichier varie selon l'emplacement du fichier SpryEffects.js. Pour que les effets Spry fonctionnent, le fichier JavaScript et le fichier HTML contenant les effets doivent tous deux se trouver sur votre serveur.


SPRY 126 Guide de l'utilisateur

Avant de commencer Préparation des fichiers Avant d'appliquer des effets Spry aux éléments de vos pages Web, téléchargez et liez le fichier approprié. 1 Recherchez le fichier ZIP de Spry sur le site Adobe Labs. 2 Téléchargez ce fichier ZIP et décompressez-le sur votre disque dur. 3 Ouvrez le dossier Spry décompressé et recherchez-y le dossier "includes". Ce dossier contient les fichiers requis pour la liaison d'effets Spry. 4 Ajoutez le fichier SpryEffects.js à votre site Web en procédant d'une des manières suivantes :

• Copiez le dossier "includes" et collez-en une copie (ou faites-la glisser) dans le répertoire racine de votre site Web. Vous disposez ainsi de tous les fichiers nécessaires pour la création d'effets Spry et de jeux de données XML Spry.

• Pour créer un dossier dans votre site Web (par exemple un dossier baptisé SpryAssets), ouvrez le dossier "includes" et copiez le fichier SpryEffects.js dans le nouveau dossier. Remarque : Si vous faites glisser le dossier "includes" d'origine ou des fichiers spécifiques à partir du dossier Spry non décompressé, les démos du dossier Spry ne fonctionneront pas correctement. Copiez et collez ces éléments dans votre site Web au lieu de les manipuler par glisser-déplacer. 5 Lorsque le fichier SpryEffects.js est inclus dans votre site Web, vous pouvez le lier et ajouter des effets Spry à vos pages. Pour plus d'informations sur l'ajout d'un effet spécifique à une page, reportez-vous aux section relatives à chacun d'eux.

Association d'effets Association d'un effet Surlignage L'effet Surlignage modifie la couleur d'arrière-plan d'un élément cible. Vous pouvez associer l'effet Surlignage à tout élément HTML, sauf applet, body, frame, frameset et noframes. 1 Pour lier le fichier SpryEffects.js à la page Web, ajoutez le code suivant à l'en-tête de votre document : <head> . . . <script </head>

src="../includes/SpryEffects.js" type="text/javascript" ></script>

Remarque : Le chemin d'accès précis du fichier varie selon l'emplacement du fichier SpryEffects.js. Le fichier SpryEffects.js se trouve dans le dossier "includes" du dossier Spry téléchargé depuis le site Adobe Labs. Voir « Préparation des fichiers » à la page 126. 2 Assurez-vous que l'élément cible possède bien un ID unique. L'élément cible est l'élément qui est modifié lorsque l'utilisateur interagit avec la page pour déclencher l'effet. <div class="demoDiv" id="highlight1"> Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam nonumy eirmod tempor invidunt ut labore et dolore magna aliquyam erat, sed diam voluptua. At vero eos et accusam et justo duo dolores et ea rebum.</div>

3 Pour créer l'effet, ajoutez un événement JavaScript qui provoque celui-ci lorsque l'utilisateur interagit avec la page. Par exemple, si vous voulez que l'utilisateur clique sur une phrase afin de provoquer la mise en surbrillance d'un autre paragraphe, vous pouvez ajouter l'événement suivant à la balise p de cette phrase : <p><a onclick="Spry.Effect.DoHighlight('highlight1',{duration: 1000, from:'#CCCCCC', to:'#FFCC33',restoreColor: '#FFCC33',toggle:true}); return false;" href="#"> Click here to highlight the below paragraph.</a></p>

Le premier argument de la méthode JavaScript est toujours l'ID de l'élément cible ('highlight1' dans l'exemple précédent). Le code complet ressemble à ce qui suit :


SPRY 127 Guide de l'utilisateur

<head> . . . <script src="../includes/SpryEffects.js" type="text/javascript" ></script> </head> <body> <p><a onclick="Spry.Effect.DoHighlight('highlight1',{duration: 1000, from:'#CCCCCC', to:'#FFCC33',restoreColor: '#FFCC33',toggle:true}); return false;" href="#"> Click here to highlight the below paragraph.</a></p> <div class="demoDiv" id="highlight1"> Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam nonumy eirmod tempor invidunt ut labore et dolore magna aliquyam erat, sed diam voluptua. At vero eos et accusam et justo duo dolores et ea rebum.</div> </body>

Options de l'effet Surlignage

Le tableau suivant présente les options disponibles pour l'effet Surlignage. Option

Description

duration

Durée de l'effet, en millisecondes. La valeur par défaut est 1000.

from

Valeur de la couleur de départ, en format RVB (#RRVVBB). Cette valeur définit la couleur de la première image de la mise en surbrillance. Par défaut, il s'agit de la couleur d'arrière-plan de l'élément cible.

to

Valeur de la couleur de fin, en format RVB (#RRVVBB). Cette valeur définit la couleur de la dernière image de la mise en surbrillance.

toggle

Produit un effet de bascule. La valeur par défaut est false. Si la valeur est fixée à true, l'option restoreColor est ignorée.

transition

Détermine le type de transition : "linear" (la vitesse de transition est constante pendant toute la durée de la transition) ou "sinusoidal" (l'effet débute lentement, accélère puis ralentit de nouveau à la fin). La valeur par défaut est "sinusoidal".

setup

Permet de définir une fonction qui est appelée avant le début de l'effet, p.ex. setup:function (element,effect){/* ... */}.

finish

Permet de définir une fonction qui est appelée après la fin de l'effet, p.ex. finish:function (element,effect){/* ... */}.

Exemple de code : Spry.Effect.DoHighlight('targetID', {duration:1000,from:'#00ff00',to:'#0000ff'});

Association d'un effet Fondu L'effet Fondu fait apparaître ou disparaître lentement un élément. Vous pouvez associer l'effet Fondu à tout élément HTML, sauf applet, body, iframe, object, tr, tbody ou th. 1 Pour lier le fichier SpryEffects.js à la page Web, ajoutez le code suivant à l'en-tête de votre document : <head> . . . <script </head>

src="../includes/SpryEffects.js" type="text/javascript" ></script>

Remarque : Le chemin d'accès précis du fichier varie selon l'emplacement du fichier SpryEffects.js. Le fichier SpryEffects.js se trouve dans le dossier "includes" du dossier Spry téléchargé depuis le site Adobe Labs. Voir « Préparation des fichiers » à la page 126. 2 Assurez-vous que l'élément cible possède bien un ID unique. L'élément cible est l'élément qui est modifié lorsque l'utilisateur interagit avec la page pour déclencher l'effet. <div class="demoDiv" id="fade1">Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam nonumy eirmod tempor invidunt ut labore et dolore magna sea takimata sanctus est Lorem ipsum dolor sit amet.</div>


SPRY 128 Guide de l'utilisateur

3 Pour créer l'effet, ajoutez un événement JavaScript qui provoque celui-ci lorsque l'utilisateur interagit avec la page. Par exemple, si vous voulez que l'utilisateur clique sur une phrase afin de provoquer le fondu d'un autre paragraphe, vous pouvez ajouter l'événement suivant à la balise p de cette phrase : <p><a onclick="Spry.Effect.DoFade('fade1', {duration:1000,from:100,to:20,toggle:true}); return false;" href="#"> Click here to make the paragraph fade from 100% to 20%.</a></p>

Le premier argument de la méthode JavaScript est toujours l'ID de l'élément cible ('fade1' dans l'exemple précédent). Le code complet ressemble à ce qui suit : <head> . . . <script src="../includes/SpryEffects.js" type="text/javascript" ></script> </head> <body> <p><a onclick="Spry.Effect.DoFade('fade1', {duration:1000,from:100,to:20,toggle:true}); return false;" href="#"> Click here to make the paragraph fade from 100% to 20%.</a></p> <div class="demoDiv" id="fade1">Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam nonumy eirmod tempor invidunt ut labore et dolore magna sea takimata sanctus est Lorem ipsum dolor sit amet.</div> </body>

Options de l'effet Fondu

Le tableau suivant présente les options disponibles pour l'effet Fondu. Option

Description

duration

Durée de l'effet, en millisecondes. La valeur par défaut est 1000.

from

Valeur d'opacité de début, en pour cent. La valeur par défaut est 0.

to

Valeur d'opacité de fin, en pour cent. La valeur par défaut est 100.

toggle

Produit un effet de bascule. La valeur par défaut est false.

transition

Détermine le type de transition : "linear" (la vitesse de transition est constante pendant toute la durée de la transition) ou "sinusoidal" (l'effet débute lentement, accélère puis ralentit de nouveau à la fin). La valeur par défaut est "sinusoidal".

setup

Permet de définir une fonction qui est appelée avant le début de l'effet, p.ex. setup:function (element,effect){/* ... */}.

finish

Permet de définir une fonction qui est appelée après la fin de l'effet, p.ex. finish:function (element,effect){/* ... */}.

Exemple de code : Spry.Effect.DoFade('targetID',{duration: 1000,from: 0,to: 100,toggle: true});

Association d'un effet Store monté/Store baissé L'effet Store monté/Store abaissé simule l'effet d'un store qui monte ou descend pour afficher ou masquer l'élément. Son action est similaire à celui de l'effet Glisser, à ceci près que le contenu reste en place. Cet effet ne peut être associé qu'aux éléments HTML suivants : address, dd, div, dl, dt, form, h1, h2, h3, h4, h5, h6, p, ol, ul, li, applet, center, dir, menu et pre. 1 Pour lier le fichier SpryEffects.js à la page Web, ajoutez le code suivant à l'en-tête de votre document : <head> . . . <script </head>

src="../includes/SpryEffects.js" type="text/javascript" ></script>

Remarque : Le chemin d'accès précis du fichier varie selon l'emplacement du fichier SpryEffects.js. Le fichier SpryEffects.js se trouve dans le dossier "includes" du dossier Spry téléchargé depuis le site Adobe Labs. Voir « Préparation des fichiers » à la page 126.


SPRY 129 Guide de l'utilisateur

2 Assurez-vous que l'élément cible possède bien un ID unique. L'élément cible est l'élément qui est modifié lorsque l'utilisateur interagit avec la page pour déclencher l'effet. <div id="blindup1"> <h4>HEADER</h4> <p class="sampleText"> Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam nonumy eirmod tempor invidunt ut labore et dolore magna</p> </div>

3 Pour créer l'effet, ajoutez un événement JavaScript qui provoque celui-ci lorsque l'utilisateur interagit avec la page. Par exemple, si vous voulez que l'utilisateur clique sur une phrase afin de provoquer un effet de Store monté dans un autre paragraphe, vous pouvez ajouter l'événement suivant à la balise p de cette phrase : <p><a onclick="Spry.Effect.DoBlind('blindup1', {duration: 1000, from: '100%', to: '0%', toggle: true}); return false;" href="#" >Click here to blind up from 100% to 0%</a></p>

Le premier argument de la méthode JavaScript est toujours l'ID de l'élément cible ('blindup1' dans l'exemple précédent). Le code complet ressemble à ce qui suit : <head> . . . <script src="../includes/SpryEffects.js" type="text/javascript" > </script> <style type="text/css"> #blindup1{ background-color: #CCCCCC; height: 200px; width: 300px; overflow: hidden; } </style> </head> <body> <p><a onclick="Spry.Effect.DoBlind('blindup1', {duration: 1000, from: '100%', to: '0%', toggle: true}); return false;" href="#" >Click here to blind up from 100% to 0%</a></p> <div id="blindup1"> <h4>HEADER</h4> <p class="sampleText"> Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam nonumy eirmod tempor invidunt ut labore et dolore magna</p> </div> </body>

Options de l'effet Store monté/Store baissé

Le tableau suivant présente les options disponibles pour l'effet Store monté/Store baissé. Option

Description

duration

Durée de l'effet, en millisecondes. La valeur par défaut est 1000.

from

Taille de début, en pour cent ou en pixels. La valeur par défaut est 100%.

to

Taille de fin, en pour cent ou en pixels. La valeur par défaut est 0%.

toggle

Produit un effet de bascule. La valeur par défaut est "false".

transition

Détermine le type de transition : "linear" (la vitesse de transition est constante pendant toute la durée de la transition) ou "sinusoidal" (l'effet débute lentement, accélère puis ralentit de nouveau à la fin). La valeur par défaut est "sinusoidal".

setup

Permet de définir une fonction qui est appelée avant le début de l'effet, p.ex. setup:function (element,effect){/* ... */}.

finish

Permet de définir une fonction qui est appelée après la fin de l'effet, p.ex. finish:function (element,effect){/* ... */}.

Exemple de code : Spry.Effect.DoBlind('targetID',{duration: 1000,from: '100%',to: '0%'});


SPRY 130 Guide de l'utilisateur

Association d'un effet Glisser L'effet Glisser déplace l'élément cible vers le haut ou le bas (ou de gauche à droite). Son action est similaire à celle de l'effet Store, à ceci près que le contenu monte ou descend (ou glisse de gauche à droite) au lieu de rester immobile. Cet effet ne peut être associé qu'aux éléments HTML suivants : blockquote, dd, div, form, center, table, span, input, textarea, select et image. 1 Pour lier le fichier SpryEffects.js à la page Web, ajoutez le code suivant à l'en-tête de votre document : <head> . . . <script </head>

src="../includes/SpryEffects.js" type="text/javascript" ></script>

Remarque : Le chemin d'accès précis du fichier varie selon l'emplacement du fichier SpryEffects.js. Le fichier SpryEffects.js se trouve dans le dossier "includes" du dossier Spry téléchargé depuis le site Adobe Labs. Voir « Préparation des fichiers » à la page 126. 2 Veillez à entourer l'élément cible d'une balise div qui possède un ID unique. L'élément cible est l'élément qui est modifié lorsque l'utilisateur interagit avec la page pour déclencher l'effet. <div id="slide1"> <div> Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam nonumy eirmod tempor invidunt ut labore et dolore magna aliquyam erat, sed diam voluptua.</div> </div>

3 Pour créer l'effet, ajoutez un événement JavaScript qui provoque celui-ci lorsque l'utilisateur interagit avec la page. Par exemple, si vous voulez que l'utilisateur clique sur une phrase afin de provoquer un effet Glisser vers le haut dans un autre paragraphe, vous pouvez ajouter l'événement suivant à la balise p de cette phrase : <p><a onclick="Spry.Effect.DoSlide('slide1',{duration:1000,from:'100%', to:'20%',toggle:true}); return false;" href="#">Click here to slide the paragraph up from 100% to 20%</a></p>

Le premier argument de la méthode JavaScript est toujours l'ID de l'élément cible ('slide1' dans l'exemple précédent). Le code complet ressemble à ce qui suit : <head> . . . <script src="../includes/SpryEffects.js" type="text/javascript" > </script> </head> <body> <p><a onclick="Spry.Effect.DoSlide('slide1',{duration:1000,from:'100%', to:'20%',toggle:true}); return false;" href="#"> Click here to slide the paragraph up from 100% to 20%</a></p> <div id="slide1"> <div> Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam nonumy eirmod tempor invidunt ut labore et dolore magna aliquyam erat, sed diam voluptua.</div> </div> </body>

Options de l'effet Glisser

Le tableau suivant présente les options disponibles pour l'effet Glisser. Option

Description

duration

Durée de l'effet, en millisecondes. La valeur par défaut est 2000.

from

Taille de début, en pour cent ou en pixels. La valeur par défaut est 100%.

to

Taille de fin, en pour cent ou en pixels. La valeur par défaut est 0%.

toggle

Produit un effet de bascule. La valeur par défaut est "false".


SPRY 131 Guide de l'utilisateur

Option

Description

transition

Détermine le type de transition : "linear" (la vitesse de transition est constante pendant toute la durée de la transition) ou "sinusoidal" (l'effet débute lentement, accélère puis ralentit de nouveau à la fin). La valeur par défaut est "sinusoidal".

horizontal

Si cette option a la valeur "true", le contenu glisse à l'horizontale et non à la verticale. La valeur par défaut est "false".

setup

Permet de définir une fonction qui est appelée avant le début de l'effet, p.ex. setup:function (element,effect){/* ... */}.

finish

Permet de définir une fonction qui est appelée après la fin de l'effet, p.ex. finish:function (element,effect){/* ... */}.

Exemple de code : Spry.Effect.DoSlide('targetID',{duration: 1000,from: '100%',to: '0%'});

Association d'un effet Agrandissement L'effet Agrandissement augmente ou diminue la taille de l'élément. Le mouvement peut se faire vers le centre de l'élément ou à partir du centre. Cet effet ne peut être associé qu'aux éléments HTML suivants : address, dd, div, dl, dt, form, p, ol, ul, applet, center, dir, menu, img et pre. 1 Pour lier le fichier SpryEffects.js à la page Web, ajoutez le code suivant à l'en-tête de votre document : <head> . . . <script </head>

src="../includes/SpryEffects.js" type="text/javascript" ></script>

Remarque : Le chemin d'accès précis du fichier varie selon l'emplacement du fichier SpryEffects.js. Le fichier SpryEffects.js se trouve dans le dossier "includes" du dossier Spry téléchargé depuis le site Adobe Labs. Voir « Préparation des fichiers » à la page 126. 2 Assurez-vous que l'élément cible possède bien un ID unique. L'élément cible est l'élément qui est modifié lorsque l'utilisateur interagit avec la page pour déclencher l'effet. <div class="demoDiv" id="shrink1"> <p>Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam nonumy eirmod tempor invidunt ut labore et dolore magna aliquyam erat, sed diam voluptua. At vero eos et accusam et justo duo dolores et ea rebum.</p> </div>

3 Pour créer l'effet, ajoutez un événement JavaScript qui provoque celui-ci lorsque l'utilisateur interagit avec la page. Par exemple, si vous voulez que l'utilisateur clique sur une phrase afin de provoquer la réduction d'un autre paragraphe, vous pouvez ajouter l'événement suivant à la balise p de cette phrase : <p><a onclick="Spry.Effect.DoGrow('shrink1',{duration:700, from:'100%', to:'20%',toggle: true}); return false;" href="#">Click here to shrink the paragraph from 100% to 20%.</a></p>

Le premier argument de la méthode JavaScript est toujours l'ID de l'élément cible ('shrink1' dans l'exemple précédent). Le code complet ressemble à ce qui suit :


SPRY 132 Guide de l'utilisateur

<head> . . . <script src="../includes/SpryEffects.js" type="text/javascript" ></script> </head> <body> <p><a onclick="Spry.Effect.DoGrow('shrink1',{duration:700, from:'100%', to:'20%',toggle: true}); return false;" href="#">Click here to shrink the paragraph from 100% to 20%.</a></p> <div class="demoDiv" id="shrink1"> <p>Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam nonumy eirmod tempor invidunt ut labore et dolore magna aliquyam erat, sed diam voluptua. At vero eos et accusam et justo duo dolores et ea rebum.</p> </div> </body>

Options de l'effet Agrandissement

Le tableau suivant présente les options disponibles pour l'effet Agrandissement. Option

Description

duration

Durée de l'effet, en millisecondes. La valeur par défaut est 500.

from

Taille de début, en pour cent ou en pixels. La valeur par défaut est 0%.

to

Taille de fin, en pour cent ou en pixels. La valeur par défaut est 100%.

toggle

Produit un effet de bascule. La valeur par défaut est "false".

growCenter

Direction d'agrandissement et de réduction de l'élément. La valeur par défaut est true (agrandissement et réduction à partir du centre). Si la valeur est false, l'élément est agrandi ou réduit depuis son coin supérieur gauche.

transition

Détermine le type de transition : "linear" (la vitesse de transition est constante pendant toute la durée de la transition) ou "sinusoidal" (l'effet débute lentement, accélère puis ralentit de nouveau à la fin). La valeur par défaut est "sinusoidal".

setup

Permet de définir une fonction qui est appelée avant le début de l'effet, p.ex. setup:function (element,effect){/* ... */}.

finish

Permet de définir une fonction qui est appelée après la fin de l'effet, p.ex. finish:function (element,effect){/* ... */}.

Exemple de code : Spry.Effect.DoGrow('targetID',{duration: 1000,from: '0%', to: '100%'});

Association d'un effet Ecraser L'effet Ecraser fait disparaître l'élément dans le coin supérieur gauche de la page. L'action de l'effet Ecraser est similaire à celle de l'effet Agrandissement dont l'option growCenter est réglée sur "false"'. Cet effet ne peut être associé qu'aux éléments HTML suivants : address, dd, div, dl, dt, form, img, p, ol, ul, applet, center, dir, menu et pre.

1 Pour lier le fichier SpryEffects.js à la page Web, ajoutez le code suivant à l'en-tête de votre document : <head> . . . <script </head>

src="../includes/SpryEffects.js" type="text/javascript" ></script>

Remarque : Le chemin d'accès précis du fichier varie selon l'emplacement du fichier SpryEffects.js. Le fichier SpryEffects.js se trouve dans le dossier "includes" du dossier Spry téléchargé depuis le site Adobe Labs. Voir « Préparation des fichiers » à la page 126. 2 Assurez-vous que l'élément cible possède bien un ID unique. L'élément cible est l'élément qui est modifié lorsque l'utilisateur interagit avec la page pour déclencher l'effet.


SPRY 133 Guide de l'utilisateur

<div id="squish1"><p>Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam nonumy eirmod tempor invidunt ut labore et dolore magna aliqt</p></div>

3 Pour créer l'effet, ajoutez un événement JavaScript qui provoque celui-ci lorsque l'utilisateur interagit avec la page. Par exemple, si vous voulez que l'utilisateur clique sur une phrase afin de provoquer l'écrasement d'un autre paragraphe, vous pouvez ajouter l'événement suivant à la balise p de cette phrase : <p><a onclick="Spry.Effect.DoSquish('squish1'); return false;" href="#">Click here to squish the paragraph.</a></p>

Le premier argument de la méthode JavaScript est toujours l'ID de l'élément cible ('squish1' dans l'exemple précédent). Le code complet ressemble à ce qui suit : <head> . . . <script src="../includes/SpryEffects.js" type="text/javascript" ></script> </head> <body> <p><a onclick="Spry.Effect.DoSquish('squish1'); return false;" href="#">Click here to squish the paragraph.</a></p> <div id="squish1"><p>Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam nonumy eirmod tempor invidunt ut labore et dolore magna aliqt</p></div> </body>

Options de l'effet Ecraser

Le tableau suivant présente les options disponibles : Option

Description

duration

Durée de l'effet, en millisecondes. La valeur par défaut est 1000.

toggle

Produit un effet de bascule. La valeur par défaut est "false".

setup

Permet de définir une fonction qui est appelée avant le début de l'effet, p.ex. setup:function (element,effect){/* ... */}.

finish

Permet de définir une fonction qui est appelée après la fin de l'effet, p.ex. finish:function (element,effect){/* ... */}.

Exemple de code : Spry.Effect.DoSquish('targetID',{duration: 1000});

Association d'un effet Secouer L'effet Secouer simule un mouvement de secousse rapide de l'élément cible, de 20 pixels de gauche à droite. Cet effet ne peut être associé qu'aux éléments HTML suivants : address, blockquote, dd, div, dl, dt, fieldset, form, h1, h2, h3, h4, h5, h6, iframe, img, object, p, ol, ul, li, applet, dir, hr, menu, pre et table. 1 Pour lier le fichier SpryEffects.js à la page Web, ajoutez le code suivant à l'en-tête de votre document : <head> . . . <script </head>

src="../includes/SpryEffects.js" type="text/javascript" ></script>

Remarque : Le chemin d'accès précis du fichier varie selon l'emplacement du fichier SpryEffects.js. Le fichier SpryEffects.js se trouve dans le dossier "includes" du dossier Spry téléchargé depuis le site Adobe Labs. Voir « Préparation des fichiers » à la page 126. 2 Assurez-vous que l'élément cible possède bien un ID unique. L'élément cible est l'élément qui est modifié lorsque l'utilisateur interagit avec la page pour déclencher l'effet. <div id="shake1">Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam nonumy eirmod tempor invidunt ut labore et dolore magna aliqit amet.</div>


SPRY 134 Guide de l'utilisateur

3 Pour créer l'effet, ajoutez un événement JavaScript qui provoque celui-ci lorsque l'utilisateur interagit avec la page. Par exemple, si vous voulez que l'utilisateur clique sur une phrase afin de secouer un autre paragraphe, vous pouvez ajouter l'événement suivant à la balise p de cette phrase : <p><a onclick="Spry.Effect.DoShake('shake1'); return false;" href="#">Shake it!</a></p>

Le premier argument de la méthode JavaScript est toujours l'ID de l'élément cible ('shake1-' dans l'exemple précédent). Le code complet ressemble à ce qui suit : <head> . . . <script src="../includes/SpryEffects.js" type="text/javascript" ></script> </head> <body> <p><a onclick="Spry.Effect.DoShake('shake1'); return false;" href="#">Shake it!</a></p> <div id="shake1">Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam nonumy eirmod tempor invidunt ut labore et dolore magna aliqit amet.</div> </body>

Options de l'effet Secouer

Le tableau suivant présente les options disponibles pour l'effet Secouer. Option

Description

duration

Fixé à 500 millisecondes dans Spry 1.4. Cette valeur ne peut être modifiée que dans Spry 1.5 et les versions ultérieures.

setup

Permet de définir une fonction qui est appelée avant le début de l'effet, p.ex. setup:function (element,effect){/* ... */}.

finish

Permet de définir une fonction qui est appelée après la fin de l'effet, p.ex. finish:function (element,effect){/* ... */}.

Exemple de code : Spry.Effect.DoShake('targetID');


135

Index A accessibilité 2, 97 Accordéon, widget à propos 4 activation de la navigation au clavier 10 ajout de panneaux 9 définition du panneau ouvert par défaut 10 insertion 7 personnalisation 10 suppression de panneaux 9 Agrandissement, effet 131 attributs de comportement 122 B Barre de menus, widget à propos 30 insertion 33 modification de l'orientation 37 personnalisation 38 bibliothèque d'effets à propos 125

Effet Store monté/Store baissé 128 effets à propos 125 Ensembles de données XML 81

à propos 40 définition du nombre minimal et maximal de caractères 54 D données actualisation 112 désactivation de la mise en cache 109 filtrage 111

cadre applicatif, à propos 1 et Dreamweaver CS3 1 widgets, à propos 2

F Fondu, effet 127 G Glisser, effet 130 J JavaScript, dégradation 2 P Panneau réductible, widget à propos 13 activation de la navigation au clavier 17 définition du panneau ouvert par défaut 17 insertion 16 personnalisation 18 Panneaux à onglet, widget

C Champ de texte de validation, widget

S Spry

à propos 21 activation de la navigation au clavier 26 ajout de panneaux 26

Surlignage, effet 126 V Validation de case à cocher, widget à propos 74 définition d'une plage de sélections minimale et maximale 78 définition du moment de validation 78 insertion 76 modification de l'état obligatoire 79 personnalisation 79 Validation de la sélection, widget à propos 67 définition des valeurs non valides 72 définition du moment de validation 72 insertion 69 modification de l'état obligatoire 72 personnalisation 73 Validation de zone de texte, widget

définition du panneau ouvert par défaut 27

blocage des caractères incorrects 55

insertion 24

création de conseils 55

personnalisation 27

définition des valeurs minimale et maximale 54

suppression de panneaux 26 R régions dynamiques

définition du moment de validation 54 définition du type de validation et du format 45

ligne actuelle, définition et modification 111

affichage de données 101

notifications d'observateur 113

et structures conditionnelles 117

obtention 109

modification de l'état obligatoire 55

et structures de boucle 114

récupération 108

personnalisation 55

états des régions 118

références, masquage 121

notifications d'observateur 119

suppression de lignes en double 111

présentation 88

tri 110 Dreamweaver CS3 1 E Effet Ecraser 132 Effet Secouer 133

création 101

régions principale et de détail

insertion 42

X XML, ensembles de données création 99

création 104, 106

exemples avancés 83

dépendance de plusieurs ensembles de données 93

présentation 81

présentation 90

tri par les utilisateurs 103


INDEX 136

Z Zone de texte de validation, widget à propos 59 ajout d'un compteur de caractères 64 blocage des caractères excédentaires 65 création de conseils 65 définition du moment de validation 63 insertion 61 modification de l'état obligatoire 65 personnalisation 65


test