Préremplissage des listes déroulantes dans des formulaires PDF dynamiques à partir d’une source de données principale au moyen de LiveCycle ES2.5

Connaissances préalables

Une connaissance pratique de LiveCycle Designer ES2 et de la base de données de votre choix (ce tutoriel est centré sur MySQL).

Autres produits nécessaires

Base de données MySQL
Un éditeur de texte comme Notepad ++

Niveau de l’utilisateur

Intermédiaire

Le caractère dynamique des formulaires électroniques constitue leur atout principal. Un formulaire n’a pas besoin d’être créé avec un seul ensemble de données, puis laissé tel quel sans jamais être modifié. Un formulaire électronique connecté à une source de données principale peut être mis à jour de manière dynamique, et ce à tout moment. Cette pratique est souvent employée pour insérer une liste déroulante dans un fichier PDF dynamique prérempli avec des données provenant d’une base de données.

Pour illustrer la procédure, nous allons créer un tableau simple dans une base de données MySql. Nous ajouterons ensuite trois lignes au tableau de la base de données, puis nous créerons un formulaire PDF simple dans Designer qui comportera une liste déroulante automatiquement préremplie par cette source de données.

Ce tutoriel décrit l’utilisation d’une base de données MySql en tant que source de données principale, bien que les principes généraux de liaison de cette source de données au formulaire soient identiques, quelle que soit la base de données principale compatible avec LiveCycle que vous décidez d’utiliser. Ce tutoriel part également du principe que vous savez créer et modifier des tableaux dans MySql et ne s’attardera pas sur ces sujets, le principal objectif de ce tutoriel étant de décrire la liaison de ces sources de données à l’objet de liste déroulante du formulaire.

Création d’un tableau dans votre base de données (MySQL)

La première étape consiste à créer un tableau dans votre base de données. Ce tableau stocke les valeurs qui finiront par apparaître dans l’objet de liste déroulante :

use adobe;

drop table testUsers;
delimiter $$
CREATE TABLE `testUsers` (
  `id` int(11) NOT NULL AUTO_INCREMENT,
  `name` varchar(45) DEFAULT NULL,
  `complete` int(11) DEFAULT NULL,
  PRIMARY KEY (`id`),
  UNIQUE KEY `id_UNIQUE` (`id`)
) ENGINE=InnoDB AUTO_INCREMENT=106 DEFAULT CHARSET=utf8$$


insert testUsers values (100, 'Jim Jones', 0);
insert testUsers values (200, 'Sally', 0);
insert testUsers values (300, 'Fred Fennel', 0);

select * from testUsers

Création d’un schéma XSD à l’aide de LiveCycle Workbench

L’étape suivante consiste à créer un document de schéma XSD. Il existe deux façons de procéder.  Quelle que soit la manière dont vous effectuez cette tâche, la première étape consiste à créer un dossier « schéma » dans votre hiérarchie de projet LiveCycle dans Workbench. Une fois le dossier créé, effectuez l’une des actions suivantes pour créer un schéma :

  • Option n° 1 :  cliquez avec le bouton droit de la souris sur le dossier « schéma » nouvellement créé et choisissez de créer un nouveau fichier de schéma XML.  Workbench ouvrira l’éditeur de texte par défaut associé à Workbench, et le nouveau fichier (un fichier texte) sera doté de l’instruction doctype adéquate ainsi que de la structure de balise de schéma de base prête pour un schéma XML. Vous pouvez ensuite utiliser l’éditeur pour écrire le reste du code du schéma, puis enregistrer le document de schéma (en veillant à définir l’extension de fichier sur « .xsd »).
  • Option n° 2 : créez le document de schéma à l’aide d’un éditeur tiers comme Notepad ++. L’utilisation d’un éditeur tel que Notepad++ présente l’avantage de placer l’instruction doctype XML en haut du document texte dans l’éditeur. Le texte devient alors coloré pour faciliter le codage. Une fois le fichier créé, donnez un nom approprié au schéma et veillez à l’enregistrer en définissant l’extension de fichier sur « .xsd ». À ce stade, vous devez faire glisser le fichier XSD (depuis l’endroit où vous l’avez enregistré après l’avoir modifié) et glisser-déposer le document dans votre dossier de schéma.

Dans les deux cas, vous devez créer un document de schéma simple tel qu’affiché dans le schéma ci-dessous. 

Remarque : bien que les éléments firstName et lastName soient affichés dans le schéma représenté, ils ne sont pas nécessaires au remplissage des listes déroulantes. Pour ce tutoriel, l’élément testerList est primordial dans le code du schéma. 

Remarque supplémentaire : cet élément est de type complexType et possède une séquence de sous-éléments « Tester ». De la même manière, ce type « Tester » est quant à lui de type complexType et contient une série de valeurs qui incluent l’« id » et le « name » des objets qui finiront par apparaître dans la liste déroulante.

<?xml version="1.0" encoding="UTF-8" ?>
<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema">

<xs:element name="FormSchema">
    <xs:complexType>
	<xs:sequence>
		<xs:element name="firstName" type="string" />
		<xs:element name="lastName" type="string" />
		<xs:element name="selectedTester" type="string"/>
		<xs:element name="testerList">
			<xs:complexType>
				<xs:sequence>
					<xs:element name="Tester" maxOccurs="unbounded">
						<xs:complexType>
							<xs:sequence>
								<xs:element name="id" />
								<xs:element name="name" />
							</xs:sequence>
						</xs:complexType>
					</xs:element>
				</xs:sequence>
			</xs:complexType>
		</xs:element>
	</xs:sequence>
    </xs:complexType>  
  </xs:element> 
</xs:schema>

Créer un nouveau formulaire lié à ce schéma

Par souci de concision, ce tutoriel part du principe que le lecteur est en mesure de créer un nouveau formulaire au moyen de Designer depuis Workbench ou directement dans Designer. À ce stade de la procédure, créez un nouveau formulaire (ou ouvrez le formulaire existant auquel vous souhaitez lier les données principales) puis ouvrez le formulaire afin de le modifier dans Designer. 

Lier la connexion de données du schéma XSD au formulaire

Une fois le formulaire souhaité ouvert, cliquez sur l’onglet « Afficher les données ». Par défaut, cet onglet se trouve sur le côté gauche de l’EDI de Designer, à deux onglets de la section « Hiérarchie ».

Cliquez avec le bouton droit de la souris sur l’espace vide de cet onglet « Afficher les données », puis cliquez sur Nouvelle connexion de données. 

Dans la fenêtre qui s’affiche (voir l’illustration n° 1), donnez un nom adéquat à votre nouvelle connexion (bien qu’il ne soit pas obligatoire que le nom de cet objet ait un rapport quelconque avec la tâche en question), sélectionnez le bouton radio « Schéma XML » et appuyez sur le bouton « Suivant ».

Il suffit ensuite d’indiquer l’emplacement du document de schéma. Si vous respectez scrupuleusement les étapes de ce tutoriel, cet emplacement correspond au dossier « schéma » de votre hiérarchie Workbench (voir l’illustration n° 2).

Si vous avez toutefois décidé de créer un nouveau formulaire au moyen de Designer depuis Workbench, vous avez la possibilité de spécifier le modèle de données de formulaire, ce qui vous permet de simplement indiquer ce schéma (voir l’illustration n° 3).

Acceptez les valeurs par défaut des visualisations restantes dans l’Assistant.

Faire glisser un objet de liste déroulante sur le formulaire

Créez une liste déroulante en glissant-déposant l’objet de liste déroulante sur le corps du formulaire depuis la palette Bibliothèque d’objets (voir l’illustration n° 4).

Une fois que l’objet déroulant a été glissé sur le formulaire, cliquez sur le menu « Outils » situé en haut de l’EDI de Designer. Sous ce menu « Outils », sélectionnez « Options ». Dans la fenêtre contextuelle « Options » qui apparaît, accédez à la sélection « Liaison de données » dans le menu de gauche. Vérifiez que l’option « Afficher les propriétés dynamiques » est cochée, puis cliquez sur le bouton « OK » (voir l’illustration n° 5).

Lier l’objet de liste déroulante à l’élément répétable du schéma

Revenez à la liste déroulante dans le corps du formulaire et cliquez dessus. Dans la palette « Objet »de la liste déroulante (qui se trouve par défaut dans l’angle inférieur droit de l’EDI de Designer, à deux onglets de la section « Disposition »), accédez au sous-onglet « Champ » (voir l’illustration n° 6).  

Au milieu de cet onglet, cliquez sur l’objet de lien vert « ListItems: ».

Sur la ligne « Éléments », cliquez sur l’objet « navigation » à droite du champ de saisie « Éléments ».  Accédez au niveau de hiérarchie « Tester ». Le champ d’entrée de données doit être rempli avec la valeur suivante :  $record.testerList.Tester[*]

Remarquez la convention « [*] » utilisée ici : cette convention est utilisée dès qu’un élément de schéma est destiné à être répété plusieurs fois. Souvenez-vous : l’un des segments du schéma ressemblait à celui-ci (voir l’illustration n° 7) :

Lorsque nous lions ce schéma à l’objet de liste déroulante, nous le lions au niveau « Tester » de la hiérarchie du schéma. Remarquez également la manière dont la valeur d’attribut maxOccurs de cet élément est définie sur unbounded (illimitée). Cette valeur d’attribut doit être définie dans le schéma pour que la convention « [*] » fonctionne dans LiveCycle.

Enfin, remarquez qu’il n’existe que deux valeurs d’élément : une pour « name » et une autre pour « id » dans le schéma. Ces éléments sont liés à la section « testUsers » de la base de données qui se présentait de la manière suivante : valeurs testUsers (100, ’Jim Jones’, 0). Souvenez-vous : la base de données comportait trois utilisateurs testUsers (Jim, Sally et Fred), mais ici, un seul élément « Tester » est présent, qui contient les éléments « id » et « name ». Ces éléments correspondent aux valeurs « 100 » (id) et « Jim Jones » (name) de la base de données (nous expliquerons la manière dont le schéma est connecté à la base de données dans la section suivante). Il vous suffit de comprendre que lorsqu’elle est liée à l’élément maxOccurs="unbounded" dans le schéma de données, la convention « [*] » effectue une itération dans le tableau de la base de données et que « pour chaque » élément qu’elle réitère dans le tableau, elle saisit cette valeur, l’adapte aux normes de données que le schéma XSD définit, puis se sert de la liaison de schéma pour remplir le champ de liste déroulante de façon adéquate.

Il reste quelques étapes supplémentaires à suivre pour terminer la procédure de liaison. L’étape suivante consiste à cliquer sur l’onglet « Liaison » sous la palette « Objet ».  Près du champ de saisie « Liaison de données », cliquez de nouveau sur l’icône « navigation » à droite. Placez le pointeur de la souris sur l’élément « Utiliser la connexion de données » (voir l’illustration n° 8). Une fenêtre contextuelle latérale apparaît, remplie avec les valeurs des éléments du schéma. 

Lorsque l’utilisateur sélectionne un élément dans la liste déroulante, cette liaison stocke l’identifiant choisi dans l’élément « selectedTester ». Cliquez donc sur ce nom dans la liste.

Dans la fenêtre contextuelle « Propriétés de liaison » qui s’affiche (voir l’illustration n° 9), sélectionnez les propriétés que vous souhaitez mettre à jour dans l’élément de liste déroulante.  Dans la plupart des cas, vous pouvez choisir de ne mettre à jour aucune propriété ou, comme nous l’avons décidé ici, de mettre à jour le champ « Nom » de l’objet de formulaire LiveCycle (simplement par souci de cohérence entre les noms d’objet de formulaire et les noms d’élément du schéma). 

Dans l’ensemble, nous laissons LiveCycle gérer les informations relatives à la légende et au type ; si vous laissez ces cases cochées, les données du formulaire LiveCycle seront écrasées. Par exemple, si vous attribuez un champ « Date » de type « Date » à un élément de schéma dont l’élément « Date » est converti en « xs:string » et que vous laissez l’option « Type » cochée dans cette boîte de dialogue, les informations de type de l’objet « Date » seront remplacées par une chaîne. Les éléments de schéma sont souvent conservés sous la forme de valeurs « xs:string » afin de permettre au schéma d’être un peu plus indulgent lors de la saisie des données et de laisser la structure des données aux outils de saisie et de validation des données intégrés dans Designer.

À ce stade, enregistrez le formulaire et quittez Designer.

Création de la procédure principale dans Workbench

Nous allons maintenant créer une procédure principale dans Workbench, puis une procédure de prérendu dans laquelle nous exécuterons une recherche dans notre base de données. C’est de cette manière que la base de données interagira avec l’objet de liste déroulante du formulaire par le biais du schéma.

Dans Workbench, cliquez avec le bouton droit de la souris sur l’emplacement de votre choix dans votre hiérarchie et créez une nouvelle procédure (c.-à-d. dans un dossier « procédures ») à l’aide de l’assistant « Nouvelle procédure » (voir l’illustration n° 10). Suivez l’assistant pour créer une nouvelle procédure, en lui demandant de créer un point de départ dans Workspace.

Remarque :

Comme il s’agit d’un exemple simple, nous n’avons pas utilisé de sous-dossier « procédures » dans l’application « PrepopulationExample », mais à mesure que des applications plus volumineuses et plus robustes sont développées, il vous est recommandé d’organiser les procédures et autres ressources en conséquence pour en faciliter l’utilisation.

Acceptez les valeurs par défaut pour les étapes restantes dans l’assistant.

Désignation du point de départ et préparation de la procédure des données

Dans le concepteur de procédures, sélectionnez le « Point de départ » vert, puis dans le volet Propriétés, cliquez sur le bouton à droite du Profil d’action comme indiqué ici (voir l’illustration n° 11) :

Dans la boîte de dialogue qui s’affiche, cliquez sur le bouton près de « Préparer la procédure des données » pour ouvrir la boîte de dialogue « Nouvelle procédure de préparation des données » (voir l’illustration n° 12).

Acceptez les valeurs par défaut et cliquez deux fois sur le bouton « OK » pour fermer les boîtes de dialogue et revenir à Workbench.

Ajout et configuration d’une activité JDBC pour la procédure

Dans la procédure « NewForm1PrepareData », ajoutez une activité JDBC (Java Database Connector) de type « Requête pour plusieurs rangs en tant que XML ». La source de données est automatiquement définie sur votre source de données principale (voir l’illustration n° 13).

Cliquez sur le bouton « Instruction Sql » et remplissez la boîte de dialogue (voir l’illustration n° 14) :

Pour voir si vous avez réussi à établir la connexion, appuyez sur le bouton « Test ». Les résultats « id » et « name » devraient être renvoyés (comme illustré ci-dessus) ; cela indique que la requête est correcte.

Attribuer les colonnes de la base de données aux éléments du schéma XSD

Une fois de plus, revenez à la visualisation de la création de procédures, cliquez sur l’objet « JDBC » puis sur « Informations XML » dans le volet de droite pour afficher la boîte de dialogue illustrée ci-dessous, qui doit être remplie de la même manière (voir l’illustration n° 15) :

Une fois la partie supérieure de cette boîte de dialogue remplie, appuyez sur le bouton « Test » pour vérifier la bonne qualité de la connexion. Le XML illustré dans la partie inférieure blanche constitue le résultat souhaité. Comme vous pouvez le constater, nous attribuons les « colonnes » de la base de données aux « éléments » XML, et dans notre cas, nous ne modifions pas les noms bien que cela soit tout à fait possible.

Création d’une nouvelle variable XML

Maintenant que la connexion de données a été établie et liée au schéma, nous devons créer une variable afin de manipuler plus facilement les données renvoyées.  Pour ce faire, appuyez sur le bouton Ajouter une variable (« + » ) près de « Sortie », créez une variable de « Type : XML » et nommez-la « Testers » (voir l’illustration n° 16). Cette variable va désormais stocker les valeurs XML résultant de la requête envoyée vers la base de données.

Création d’une activité « Attribuer une valeur »

Ensuite, créez une activité « Attribuer une valeur », qui servira à déplacer la sortie XML hors de notre requête dans la variable XML « Testers » qui sera ensuite utilisée pour remplir le formulaire.  Connectez cette activité « Attribuer une valeur » à l’objet JDBC comme illustré ci-dessous (voir l’illustration n° 17).

Cliquez sur l’objet « Activité » et dans le volet des propriétés, cliquez sur l’icône de modification « Crayon » dans la section « Mappages » pour ouvrir la boîte de dialogue de modification. Ici, nous affectons la variable « Testers » à l’emplacement approprié dans notre variable de sortie, de la manière suivante (voir l’illustration n° 18) :

L’emplacement de destination est le suivant :

/process_data/xmlPrepareData/xdp/datasets/data/FormSchema/testerList

Maintenant, enregistrez la procédure.

Déploiement de l’application

Vous êtes maintenant prêt à déployer l’application. En l’exécutant dans Workspace, la liste déroulante remplie s’affiche dans le formulaire, de la manière suivante (voir l’illustration n° 19) :

En d’autres termes, vous avez correctement rempli la liste déroulante avec les valeurs de la base de données.

Test de la variable « selectedTester »

Si vous souhaitez prouver que la variable « selectedTester » est définie par le choix de l’utilisateur dans la liste déroulante, vous pouvez temporairement créer une entrée de texte en revenant dans Designer et en faisant glisser ce champ depuis l’Affichage des données vers le formulaire (voir l’illustration n° 20) :

Enregistrez le formulaire, déployez l’application et relancez l’exécution. Vous verrez que le champ Testeur sélectionné reflètera l’identifiant de l’utilisateur que vous sélectionnez dans la liste déroulante (voir l’illustration n° 21).

L’étape suivante peut consister à utiliser les données saisies ou sélectionnées par l’utilisateur et à les insérer dans un tableau de base de données.

Et maintenant ?

Le tutoriel ci-dessus a présenté le principe qui sous-tend la création d’un tableau de base de données, sa liaison à un schéma, la liaison du schéma à un formulaire et la création de variables XML pour stocker les données renvoyées.

Pour en savoir plus sur des sujets similaires, consultez Liaison d’un document de schéma XML (XSD) à des éléments de sous-formulaire répétés au moyen d’Adobe LiveCycle Designer.