XML Tutorial/fr: what changed

Revision 1 to 2. Removed lines have a minus sign; added lines have a plus sign.

Old	New		Line
1	1		## Introduction
2	2
3	3		Le langage de balises extensible (eXtensible Markup Language) est un langage recommandé par le [W3C](http://www.w3.org/) créé pour l'échange d'informations entre différents systèmes. Il propose le stockage d'informations sous forme de texte. Les langages modernes d'échanges de données comme le XHTML, tout comme la plupart des technologies WebServices, sont fondés sur le XML.
4	4
5	5		Il existe actuellement un ensemble d'unités qui offrent le support du XML à Free Pascal. Ces unités appelées XMLRead, XMLWrite et DOM font partie de la Free Component Library (FCL) du compilateur Free Pascal. La FCL est déjà sur le chemin de recherche par défaut du compilateur de Lazarus : vous n'avez donc qu'à ajouter ces unités à votre clause uses pour obtenir l'accès au XML. La FCL n'étant que partiellement documentée à ce jour (mai 2015), ce petit tutoriel vise à introduire l'utilisation minimale du XML en utilisant ces unités.
6	6
7	7		Le DOM XML (Document Object Model) est un ensemble d'objets standardisés offrant une interface similaire pour l'utilisation du XML avec différents langages et systèmes. Le standard spécifie uniquement les méthodes, propriétés et autres parties d'interface de l'objet, laissant l'implémentation libre pour les différents langages. La FCL supporte totalement le [XML DOM 2.0](http://www.w3.org/TR/2000/REC-DOM-Level-2-Core-20001113/) et un sous-ensemble du [XML DOM 3.0](http://www.w3.org/TR/2004/REC-DOM-Level-3-Core-20040407/) détaillé [[dom\|ici]].
8	8
9	9		## Exemples
10	10
11	11		Ci-dessous figure une série d'exemples de manipulations de données XML dont la complexité va en croissant.
12	12
13	13		## Unités dans la clause uses : Unicode ou Ansi
14	14
15	15		FPC est accompagné d'unités XML fondées sur des routines dont le codage correspond à la norme ANSI si bien que les résultats sur différentes plateformes peuvent ne pas être homogènes et en particulier non Unicode. Lazarus fournit un ensemble complémentaire d'unités XML avec le paquet LazUtils qui supporte totalement le codage Unicode UTF-8 pour toutes les plateformes. Toutes ces unités sont compatibles : pour passer de l'une à l'autre, il suffit d'adapter la clause uses en conséquence.
16	16
17	17		Les unités proposées par FPC pour le traitement du XML sont (chaînes encodées selon l'encodage du système) :
18	18
19		-	~~` ``DOM`\~~
20		-	~~` ``XMLRead`\~~
21		-	~~` ``XMLWrite`\~~
22		-	~~` ``XMLCfg`\~~
23		-	~~` ``XMLUtils`\~~
24		-	~~` ``XMLStreaming`` `~~
	19	+	```text
	20	+	DOM
	21	+	XMLRead
	22	+	XMLWrite
	23	+	XMLCfg
	24	+	XMLUtils
	25	+	XMLStreaming
	26	+	```
25	27
26	28		Les unités proposées par Lazarus pour le traitement du XML sont (chaînes avec support de l'Unicode UTF-8 sur toutes les plateformes) :
27	29
28		-	~~` ``laz2_DOM`\~~
29		-	~~` ``laz2_XMLRead`\~~
30		-	~~` ``laz2_XMLWrite`\~~
31		-	~~` ``laz2_XMLCfg`\~~
32		-	~~` ``laz2_XMLUtils`\~~
33		-	~~` ``laz_XMLStreaming`` `~~
	30	+	```text
	31	+	laz2_DOM
	32	+	laz2_XMLRead
	33	+	laz2_XMLWrite
	34	+	laz2_XMLCfg
	35	+	laz2_XMLUtils
	36	+	laz_XMLStreaming
	37	+	```
34	38
35	39		Toutes ces unités ne sont pas nécessaires pour chacun des exemples qui suivent. Vous aurez toutefois toujours besoin de l'unité DOM (ou laz2_DOM) dans la mesure où elle définit plusieurs types dont TXMLDocument.
36	40
37	41		### Lire un nœud de texte
38	42
39	43		Pour les programmeurs Delphi : notez que lorsque vous travaillez avec TXMLDocument, le texte à l'intérieur d'un nœud est considéré comme un nœud de texte séparé. Vous devez donc accéder à une valeur texte d'un nœud comme à un nœud séparé.
40	44
41	45		Par exemple, considérez le XML suivant :
42	46
43	47		``` xml
44	48		<?xml version="1.0"?>
45	49		<request>
46	50		<request_type>PUT_FILE</request_type>
47	51		<username>123</username>
48	52		<password>abc</password>
49	53		</request>
50	54		```
51	55
52	56		L'exemple de code suivant montre la bonne et la mauvaise façon d'obtenir la valeur du texte du nœud :
53	57
54	58		``` pascal
55	59		var
56	60		PassNode: TDOMNode;
57	61		Doc: TXMLDocument;
58	62		begin
59	63		// Lit le fichier xml depuis le disque
60	64		ReadXMLFile(Doc, 'c:\xmlfiles\test.xml');
61	65		// Récupère le nœud "password"
62	66		PassNode := Doc.DocumentElement.FindNode('password');
63	67		// Ecrit la valeur du nœud sélectionné
64	68		WriteLn(PassNode.NodeValue); // ce sera vide
65	69		// Le texte du nœud est réellement un nœud enfant distinct
66	70		WriteLn(PassNode.FirstChild.NodeValue); // affiche correctement "abc"
67	71		```
68	72
69	73		### Afficher les noms des nœuds
70	74
71	75		L'exemple suivant montre comment afficher les noms des nœud dans un TMemo placé sur une fiche.
72	76
73	77		Ci-dessous le fichier XML appelé 'C:\Programs\test.xml' :
74	78
75	79		``` xml
76	80		<?xml version="1.0"?>
77	81		<images directory="mydir">
78	82		<imageNode URL="graphic.jpg" title="">
79	83		<Peca DestinoX="0" DestinoY="0">Pecacastelo.jpg1.swf</Peca>
80	84		<Peca DestinoX="0" DestinoY="86">Pecacastelo.jpg2.swf</Peca>
81	85		</imageNode>
82	86		</images>
83	87		```
84	88
85	89		Et ci-après le code Pascal pour exécuter la tâche :
86	90
87	91		``` pascal
88	92		var
89	93		Document: TXMLDocument;
90	94		i, j: Integer;
91	95		begin
92	96		ReadXMLFile(Document, 'C:\Programs\test.xml');
93	97		Memo.Lines.Clear;
94	98		with Document.DocumentElement.ChildNodes do
95	99		begin
96	100		for i := 0 to (Count - 1) do
97	101		begin
98	102		Memo.Lines.Add(Item[i].NodeName + ' ' + Item[i].Attributes.Item[0].NodeValue);
99	103		for j := 0 to (Item[i].ChildNodes.Count - 1) do
100	104		begin
101	105		Memo.Lines.Add(Item[i].ChildNodes.Item[j].NodeName + ' '
102	106		+ Item[i].ChildNodes.Item[j].FirstChild.NodeValue);
103	107		end;
104	108		end;
105	109		end;
106	110		Document.Free;
107	111		end;
108	112		```
109	113
110	114		Ce qui affichera:
111	115
112	116		imageNode graphic.jpg
113	117		Peca Pecacastelo.jpg1.swf
114	118		Peca Pecacastelo.jpg1.swf
115	119
116	120		### Peupler un TreeView avec XML
117	121
118	122		Une utilisation courante des fichers XML est de les analyser et d'afficher leur contenu sous forme d'arborescence. Pour ce faire, vous pouvez utiliser le composant TTreeView présent sous l'onglet Common Controls de Lazarus.
119	123
120	124		La procédure ci-dessous va prendre un document XML précédemment chargé depuis un fichier ou généré par code, avant de peupler un TreeView avec son contenu. La légende de chaque nœud de l'arbre sera le contenu du premier attribut de chaque nœud du document XML.
121	125
122	126		``` pascal
123	127		procedure TForm1.XML2Tree(tree: TTreeView; XMLDoc: TXMLDocument);
124	128		var
125	129		iNode: TDOMNode;
126	130
127	131		procedure ProcessNode(Node: TDOMNode; TreeNode: TTreeNode);
128	132		var
129	133		cNode: TDOMNode;
130	134		s: string;
131	135		begin
132	136		if Node = nil then Exit; // Stoppe si on a atteint une feuille
133	137
134	138		// Ajoute un nœud à l'arbre s'il existe
135	139		if Node.HasAttributes and (Node.Attributes.Length>0) then
136	140		s := Node.Attributes[0].NodeValue
137	141		else
138	142		s := '';
139	143		TreeNode := tree.Items.AddChild(TreeNode, s);
140	144
141	145
142	146		// Va au nœud enfant
143	147		cNode := Node.ChildNodes.Item[0];
144	148
145	149		// Traite tous les nœuds enfants
146	150		while cNode <> nil do
147	151		begin
148	152		ProcessNoDe(cNode, TreeNode);
149	153		cNode := cNode.NextSibling;
150	154		end;
151	155		end;
152	156
153	157		begin
154	158		iNode := XMLDoc.DocumentElement.ChildNodes.Item[0];
155	159		while iNode <> nil do
156	160		begin
157	161		ProcessNode(iNode, nil); // Procédure récursive
158	162		iNode := iNode.NextSibling;
159	163		end;
160	164		end;
161	165		```
162	166
163	167		### Modifier un document XML
164	168
165	169		La première chose à se rappeler est que TDOMDocument est le "handle" vers le DOM. Vous pouvez obtenir une instance de cette classe en créant ou en chargeant un document XML.
166	170
167	171		D'un autre côté, les nœuds ne peuvent être créés comme des objets classiques. Vous devez utiliser les méthodes mises à disposition par TDOMDocument pour les créer puis utiliser d'autres méthodes pour les placer correctement dans l'arbre. Cela est dû au fait que les nœuds doivent être "possédés" par un document spécifique du DOM.
168	172
169	173		Ci-dessous sont indiquées quelques méthodes particulièrement utiles de TDOMDocument :
170	174
171	175		``` pascal
172	176		function CreateElement(const tagName: DOMString): TDOMElement; virtual;
173	177		function CreateTextNode(const data: DOMString): TDOMText;
174	178		function CreateCDATASection(const data: DOMString): TDOMCDATASection;
175	179		virtual;
176	180		function CreateAttribute(const name: DOMString): TDOMAttr; virtual;
177	181		```
178	182
179	183		CreateElement crée un nouvel élément.
180	184
181	185		CreateTextNode crée un noeud texte.
182	186
183	187		CreateAttribute crée un noeud attribut.
184	188
185	189		CreateCDATASection crée une section CDATA : les caractères de marquage particuliers à XML tels que \<\> ne sont pas intrepréts au sein d'une section CDATA.
186	190
187	191		Une façon plus facile de manipuler les attributs consiste à utiliser la méthode TDOMElement.SetAttribute (elle est par ailleurs la propriété par défaut de TDOMElement) :
188	192
189	193		``` pascal
190	194		// these two statements are equivalent
191	195		Element.SetAttribute('name', 'value');
192	196		Element['name'] := 'value';
193	197		```
194	198
195	199		Et ci-après un exemple de méthode qui localise l'élément sélectionné dans un TTreeView avant d'insérer un nœud enfant au document XML qu'il représente. Le TreeView doit être précédement rempli avec le contenu du fichier XML en utilisant la [[XML Tutorial\|fonction XML2Tree]].
196	200
197	201		``` pascal
198	202		procedure TForm1.actAddChildNode(Sender: TObject);
199	203		var
200	204		Posicao: Integer;
201	205		NovoNo: TDomNode;
202	206		begin
203	207		{*******************************************************************
204	208		* Détection de l'élément sélectionné
205	209		*******************************************************************}
206	210		if TreeView1.Selected = nil then Exit;
207	211
208	212		if TreeView1.Selected.Level = 0 then
209	213		begin
210	214		Posicao := TreeView1.Selected.Index;
211	215
212	216		NovoNo := XMLDoc.CreateElement('item');
213	217		TDOMElement(NovoNo).SetAttribute('nome', 'Item');
214	218		TDOMElement(NovoNo).SetAttribute('arquivo', 'Arquivo');
215	219		XMLDoc.DocumentElement.ChildNodes.Item[Posicao].AppendChild(NovoNo);
216	220
217	221		{*******************************************************************
218	222		* Mise à jour du TreeView
219	223		*******************************************************************}
220	224		TreeView1.Items.Clear;
221	225		XML2Tree(TreeView1, XMLDoc);
222	226		end
223	227		else if TreeView1.Selected.Level >= 1 then
224	228		begin
225	229		{*******************************************************************
226	230		* Cette fonction n'est opérante qu'au premier niveau de l'arbre,
227	231		* mais peut facilement être modifiée pour fonctionner avec plusieurs niveaux
228	232		*******************************************************************}
229	233		end;
230	234		end;
231	235		```
232	236
233	237		### Créer un TXMLDocument à partir d'une chaîne
234	238
235	239		Étant donné un fichier XML dans MyXmlString, le code suivant va créer son DOM :
236	240
237	241		``` pascal
238	242		Var
239	243		S : TStringStream;
240	244		XML : TXMLDocument;
241	245
242	246		begin
243	247		S:= TStringStream.Create(MyXMLString);
244	248		Try
245	249		S.Position:=0;
246	250		XML:=Nil;
247	251		ReadXMLFile(XML,S); // Document XML complet
248	252		// Autre possibilité
249	253		ReadXMLFragment(AParentNode,S); // Lit uniquement un fragment XML.
250	254		Finally
251	255		S.Free;
252	256		end;
253	257		end;
254	258		```
255	259
256	260		## Liens Externes
257	261
258	262		- [W3Schools](http://www.w3schools.com/xml/default.asp) Tutoriel XML
259	263
260	264		- [Thomas Zastrow article](http://www.thomas-zastrow.de/texte/fpcxml/index.php) FPC et XML
261	265
262	266		---
263	267		From the Free Pascal wiki, page "XML Tutorial/fr", as it stood on 2020-03-02 after a change by Trev, out of the wiki's dump of 2024-05-26. Copyright stays with the author who wrote it, according to the old wiki's [[Licensing]] page. If you have concerns about this material, [message the admin](/wiki-contact).

Back to history