XML Background"

From Documentation
m
 
(23 intermediate revisions by 3 users not shown)
Line 4: Line 4:
 
This section provides the most basic concepts of XML to work with ZK. If you are familiar with XML, you could skip this section. If you want to learn more, there are a lot of resources on Internet, such as [http://www.w3schools.com/xml/xml_whatis.asp http://www.w3schools.com/xml/xml_whatis.asp] and [http://www.xml.com/pub/a/98/10/guide0.html http://www.xml.com/pub/a/98/10/guide0.html].
 
This section provides the most basic concepts of XML to work with ZK. If you are familiar with XML, you could skip this section. If you want to learn more, there are a lot of resources on Internet, such as [http://www.w3schools.com/xml/xml_whatis.asp http://www.w3schools.com/xml/xml_whatis.asp] and [http://www.xml.com/pub/a/98/10/guide0.html http://www.xml.com/pub/a/98/10/guide0.html].
  
XML is a markup language much like HTML but with stricter and cleaner syntax. It has several characteristics worth to notice.
+
XML is a markup language much like HTML but with stricter and cleaner syntax. It has several characteristics worthwhile to take notes of.
  
= Elements Must Be Well-formed =
+
=Document=
First, each element must be closed. They are two ways to close an element as depicted below. They are equivalent.
 
  
 +
The whole XML content, no matter whether it is in a file or as a string, is called an XML document.
  
{| border="1"
+
== Character Encoding ==
 +
It is, though optional, a good idea to specify the encoding in your XML so that the XML parser can interpret it correctly. Note: it must be on the first line of the XML document.
 +
 
 +
<source lang="xml" >
 +
<?xml version="1.0" encoding="UTF-8"?>
 +
</source>
 +
 
 +
In addition to specifying the correct encoding, you have to make sure your XML editor supports it as well.
 +
 
 +
=Elements=
 +
An XML element is everything from (including) the element's start tag to (including) the element's end tag.
 +
 
 +
An element can contain other elements, let it be simple text or a mixture of both. Elements can also have attributes. For example,
 +
 
 +
<source lang="xml">
 +
<window title="abc">
 +
  <button label="click me"/>
 +
</window>
 +
</source>
 +
 
 +
where both window and button are elements, while title is an attribute of the window element. The button element is nested in the window element. We call the window component the parent element of button, while the button component is a child element of the window.
 +
 
 +
The document root is the topmost element (without any parent element). There is exactly one document root per XML document.
 +
 
 +
== Elements Must Be Well-formed ==
 +
 
 +
First, each element must be closed. There are two ways to close an element as depicted below. They are equivalent.
 +
 
 +
 
 +
{| class='wikitable' | width="100%"
 
! <center>Description</center>
 
! <center>Description</center>
 
! <center>Code</center>
 
! <center>Code</center>
Line 23: Line 52:
  
 
|}
 
|}
 
 
  
 
Second, elements must be properly nested.
 
Second, elements must be properly nested.
  
 
+
{| class='wikitable' | width="100%"
{| border="1" style="width:75%; "
 
 
! <center>Result</center>
 
! <center>Result</center>
 
! <center>Code</center>
 
! <center>Code</center>
Line 55: Line 81:
 
XML treats every tag as a node in a tree. A node without a parent node is a root component, and it is the root of a tree. In each zul file, only '''ONE''' tree is allowed.
 
XML treats every tag as a node in a tree. A node without a parent node is a root component, and it is the root of a tree. In each zul file, only '''ONE''' tree is allowed.
  
For example, for being a whole zul file, the following is allowed, for it has only one root component.
+
For example, for being a whole zul file, the following is allowed as it has only one root component.
 
<source lang="xml" >
 
<source lang="xml" >
 
<button/>
 
<button/>
 
</source>
 
</source>
  
And for being a whole zul file, the following is not allowed, for it has more than one root component.
+
And for being a whole zul file, the following is not allowed as it has more than one root component.
 
<source lang="xml" >
 
<source lang="xml" >
 
<button/>
 
<button/>
Line 66: Line 92:
 
</source>
 
</source>
  
You can solve the problem by simply adding a tag enclosing the whole zul file to serve as the parent node, so the zul file has one single tree again.
+
You can solve the problem simply by adding a tag to enclose the whole zul file to serve as the parent node, so that the zul file has one single tree again.
  
 
<source lang="xml" >
 
<source lang="xml" >
Line 75: Line 101:
 
</source>
 
</source>
  
= Special Character Must Be Replaced =
+
== Special Characters Must Be Replaced ==
XML use <tt><''element-name''></tt> to denote an element, so you have to replace special characters. For example, you have to use <tt>&amp;lt;</tt> to represent the <tt><</tt> character.
+
XML uses <code><''element-name''></code> to denote an element, so you have to use special characters for replacement. For example, you have to use <code>&amp;lt;</code> to represent the <code><</code> character.
  
  
{| border="1"
+
{| class='wikitable' | width="100%"
 
! <center>Special Character</center>
 
! <center>Special Character</center>
 
! <center>Replaced With</center>
 
! <center>Replaced With</center>
 
+
!
 
|-
 
|-
 
| <center><</center>
 
| <center><</center>
 
| <center>&amp;lt;</center>
 
| <center>&amp;lt;</center>
 
+
|
 
|-
 
|-
 
| <center>></center>
 
| <center>></center>
 
| <center>&amp;gt;</center>
 
| <center>&amp;gt;</center>
 
+
|
 
|-
 
|-
 
| <center>&</center>
 
| <center>&</center>
 
| <center>&amp;amp;</center>
 
| <center>&amp;amp;</center>
 
+
|
 
|-
 
|-
 
| <center>"</center>
 
| <center>"</center>
 
| <center>&amp;quot;</center>
 
| <center>&amp;quot;</center>
 
+
|
 
|-
 
|-
 
| <center>'</center>
 
| <center>'</center>
 
| <center>&amp;apos;</center>
 
| <center>&amp;apos;</center>
 +
|
  
 
|-
 
|-
 
| <center>\t (TAB)</center>
 
| <center>\t (TAB)</center>
 
| <center>&amp;#x09;</center>
 
| <center>&amp;#x09;</center>
| Required only if use it in a XML attribute's value
+
| Required only if used in an XML attribute's value
  
 
|-
 
|-
 
| <center>\n (Linefeed)</center>
 
| <center>\n (Linefeed)</center>
 
| <center>&amp;#x0a;</center>
 
| <center>&amp;#x0a;</center>
| Required only if use it in a XML attribute's value
+
| Required only if used in an XML attribute's value
 
|}
 
|}
Alternatively, you could tell XML parser not to interpret a piece of text by using <tt>CDATA</tt> as the following.
+
Alternatively, you could tell XML parser not to interpret a piece of text by using <code>CDATA</code>. See the following:
  
 
<source lang="xml" >
 
<source lang="xml" >
Line 126: Line 153:
 
</source>
 
</source>
 
   
 
   
It is suggested to always add <tt><![CDATA[    ]]></tt> inside your <tt><zscript> </zscript></tt>. Thus you don't have to worry about escape sequences for special characters like "&", "<". In addition, the code is much easier to read and maintain.
+
It is suggested to always add <code><![CDATA[    ]]></code> inside your <code><zscript> </zscript></code>. Thus you don't have to worry about the escape sequences for special characters like "&", "<". In addition, the code can also become much easier to read and maintain.
  
= Attribute Values Must Be Specified and Quoted =
+
== Attribute Values Must Be Specified and Quoted ==
  
{| border="1"
+
{| class='wikitable' | width="100%"
 
! <center>Result</center>
 
! <center>Result</center>
 
! <center>Code</center>
 
! <center>Code</center>
Line 159: Line 186:
  
 
= Comments =
 
= Comments =
A comment is used to leave a note or to temporarily disable a block of XML code. To add a comment in XML, use <tt><nowiki><!--</nowiki></tt> and <tt><nowiki>--></nowiki></tt> to mark the comment body.
+
A comment is used to leave a note or to temporarily disable a block of XML code. To add a comment in XML, use <code><nowiki><!--</nowiki></code> and <code><nowiki>--></nowiki></code> to mark the comment body.
  
 
<source lang="xml" >
 
<source lang="xml" >
Line 167: Line 194:
 
</source>
 
</source>
  
= Character Encoding =
+
=Processing Instruction=
It is, though optional, a good idea to specify the encoding in your XML such that the XML parser can interpret it correctly. Note: it must be on the first line of the file.
+
 
 +
A processing instruction is used to carry out the instruction to the program that processes the XML document. A processing instruction is enclosed with &lt;? and ?&gt;. For example,
  
<source lang="xml" >
+
<source lang="xml">
<?xml version="1.0" encoding="UTF-8"?>
+
<?page title="Foo"?>
 
</source>
 
</source>
  
In addition to specify the correct encoding, you have to make sure your XML editor supports it as well.
+
Processing instructions may occur anywhere in an XML document. However, most ZUML processing instructions must be specified at the topmost level (the same level as the document root).
  
 
{{ZKDevelopersReferencePageFooter}}
 
{{ZKDevelopersReferencePageFooter}}

Latest revision as of 07:38, 22 January 2024

Overview

This section provides the most basic concepts of XML to work with ZK. If you are familiar with XML, you could skip this section. If you want to learn more, there are a lot of resources on Internet, such as http://www.w3schools.com/xml/xml_whatis.asp and http://www.xml.com/pub/a/98/10/guide0.html.

XML is a markup language much like HTML but with stricter and cleaner syntax. It has several characteristics worthwhile to take notes of.

Document

The whole XML content, no matter whether it is in a file or as a string, is called an XML document.

Character Encoding

It is, though optional, a good idea to specify the encoding in your XML so that the XML parser can interpret it correctly. Note: it must be on the first line of the XML document.

 <?xml version="1.0" encoding="UTF-8"?>

In addition to specifying the correct encoding, you have to make sure your XML editor supports it as well.

Elements

An XML element is everything from (including) the element's start tag to (including) the element's end tag.

An element can contain other elements, let it be simple text or a mixture of both. Elements can also have attributes. For example,

<window title="abc">
  <button label="click me"/>
</window>

where both window and button are elements, while title is an attribute of the window element. The button element is nested in the window element. We call the window component the parent element of button, while the button component is a child element of the window.

The document root is the topmost element (without any parent element). There is exactly one document root per XML document.

Elements Must Be Well-formed

First, each element must be closed. There are two ways to close an element as depicted below. They are equivalent.


Description
Code
Close by an end tag:
<window></window>
Close without an end tag:
<window/>

Second, elements must be properly nested.

Result
Code
Correct:
<window>
	<groupbox>
		Hello World!
	</groupbox>
</window>
Wrong:
<window>
	<groupbox>
		Hello World!
	</window>
</groupbox>

XML treats every tag as a node in a tree. A node without a parent node is a root component, and it is the root of a tree. In each zul file, only ONE tree is allowed.

For example, for being a whole zul file, the following is allowed as it has only one root component.

<button/>

And for being a whole zul file, the following is not allowed as it has more than one root component.

<button/>
<button/>

You can solve the problem simply by adding a tag to enclose the whole zul file to serve as the parent node, so that the zul file has one single tree again.

<window>
	<button />
	<button />
</window>

Special Characters Must Be Replaced

XML uses <element-name> to denote an element, so you have to use special characters for replacement. For example, you have to use &lt; to represent the < character.


Special Character
Replaced With
<
&lt;
>
&gt;
&
&amp;
"
&quot;
'
&apos;
\t (TAB)
&#x09;
Required only if used in an XML attribute's value
\n (Linefeed)
&#x0a;
Required only if used in an XML attribute's value

Alternatively, you could tell XML parser not to interpret a piece of text by using CDATA. See the following:

 <zscript>
 <![CDATA[
 void myfunc(int a, int b) {
     if (a < 0 && b > 0) {
         //do something
     }
 ]]>
 </zscript>

It is suggested to always add <![CDATA[ ]]> inside your <zscript> </zscript>. Thus you don't have to worry about the escape sequences for special characters like "&", "<". In addition, the code can also become much easier to read and maintain.

Attribute Values Must Be Specified and Quoted

Result
Code
Correct:
  
width="100%"
checked="true"
Wrong:
  
width=100%
checked

Both the single quote (') and the double quote (") can be used, so if the value has double quotes, you could use the single quote to enclose it. For example,

<button onClick='alert("Hello, There")'/>

Of course, you can always use &quot; to denote a double quote.

Comments

A comment is used to leave a note or to temporarily disable a block of XML code. To add a comment in XML, use <!-- and --> to mark the comment body.

 <window>
 <!-- this is a comment and ignored by ZK -->
 </window>

Processing Instruction

A processing instruction is used to carry out the instruction to the program that processes the XML document. A processing instruction is enclosed with <? and ?>. For example,

<?page title="Foo"?>

Processing instructions may occur anywhere in an XML document. However, most ZUML processing instructions must be specified at the topmost level (the same level as the document root).



Last Update : 2024/01/22

Copyright © Potix Corporation. This article is licensed under GNU Free Documentation License.