|
|
| (2 intermediate revisions by one other user not shown) |
| Line 1: |
Line 1: |
| | {{ZKDevelopersGuidePageHeader}} | | {{ZKDevelopersGuidePageHeader}} |
| | | | |
| − | == Overview ==
| + | This section outlines the XML conventions which the ZK user interface markup language follows |
| − | 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.
| + | {{ZKDevelopersGuideHeadingToc}} |
| | | | |
| − | == Elements Must Be Well-formed ==
| + | {{ZKDevelopersGuidePageFooter}} |
| − | First, each element must be closed. They are two ways to close an element as depicted below. They are equivalent.
| |
| − | | |
| − | | |
| − | {| border="1"
| |
| − | ! <center>Description</center>
| |
| − | ! <center>Code</center>
| |
| − | | |
| − | |-
| |
| − | | Close by an end tag:
| |
| − | | <source lang="xml" ><window></window></source>
| |
| − | | |
| − | |-
| |
| − | | Close without an end tag:
| |
| − | | <source lang="xml" ><window/></source>
| |
| − | | |
| − | |}
| |
| − | | |
| − | | |
| − | | |
| − | Second, elements must be properly nested.
| |
| − | | |
| − | | |
| − | {| border="1" style="width:75%; "
| |
| − | ! <center>Result</center>
| |
| − | ! <center>Code</center>
| |
| − | | |
| − | |-
| |
| − | | Correct:
| |
| − | |<source lang="xml" style="width:75%" >
| |
| − | <window>
| |
| − | <groupbox>
| |
| − | Hello World!
| |
| − | </groupbox>
| |
| − | </window>
| |
| − | </source>
| |
| − | |-
| |
| − | | Wrong:
| |
| − | | <source lang="xml" >
| |
| − | <window>
| |
| − | <groupbox>
| |
| − | Hello World!
| |
| − | </window>
| |
| − | </groupbox>
| |
| − | </source>
| |
| − | |}
| |
| − | | |
| − | 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.
| |
| − | <source lang="xml" >
| |
| − | <button/>
| |
| − | </source>
| |
| − | | |
| − | And for being a whole zul file, the following is not allowed, for it has more than one root component.
| |
| − | <source lang="xml" >
| |
| − | <button/>
| |
| − | <button/>
| |
| − | </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.
| |
| − | | |
| − | <source lang="xml" >
| |
| − | <window>
| |
| − | <button />
| |
| − | <button />
| |
| − | </window>
| |
| − | </source>
| |
| − | | |
| − | == Special Character 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>&lt;</tt> to represent the <tt><</tt> character.
| |
| − | | |
| − | | |
| − | {| border="1"
| |
| − | ! <center>Special Character</center>
| |
| − | ! <center>Replaced With</center>
| |
| − | | |
| − | |-
| |
| − | | <center><</center>
| |
| − | | <center>&lt;</center>
| |
| − | | |
| − | |-
| |
| − | | <center>></center>
| |
| − | | <center>&gt;</center>
| |
| − | | |
| − | |-
| |
| − | | <center>&</center>
| |
| − | | <center>&amp;</center>
| |
| − | | |
| − | |-
| |
| − | | <center>"</center>
| |
| − | | <center>&quot;</center>
| |
| − | | |
| − | |-
| |
| − | | <center>'</center>
| |
| − | | <center>&apos;</center>
| |
| − | | |
| − | |-
| |
| − | | <center>\t (TAB)</center>
| |
| − | | <center>&#x09;</center>
| |
| − | | Required only if use it in a XML attribute's value
| |
| − | | |
| − | |-
| |
| − | | <center>\n (Linefeed)</center>
| |
| − | | <center>&#x0a;</center>
| |
| − | | Required only if use it in a 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.
| |
| − | | |
| − | <source lang="xml" >
| |
| − | <zscript>
| |
| − | <![CDATA[
| |
| − | void myfunc(int a, int b) {
| |
| − | if (a < 0 && b > 0) {
| |
| − | //do something
| |
| − | }
| |
| − | ]]>
| |
| − | </zscript>
| |
| − | </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.
| |
| − | | |
| − | == Attribute Values Must Be Specified and Quoted ==
| |
| − | | |
| − | {| border="1"
| |
| − | ! <center>Result</center>
| |
| − | ! <center>Code</center>
| |
| − | | |
| − | |-
| |
| − | | Correct:
| |
| − | |
| |
| − | <source lang="xml" >
| |
| − | width="100%"
| |
| − | checked="true"
| |
| − | </source>
| |
| − | |-
| |
| − | | Wrong:
| |
| − | |
| |
| − | <source lang="xml" >
| |
| − | width=100%
| |
| − | checked
| |
| − | </source>
| |
| − | |}
| |
| − | == 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.
| |
| − | | |
| − | <source lang="xml" >
| |
| − | <window>
| |
| − | <!-- this is a comment and ignored by ZK -->
| |
| − | </window>
| |
| − | </source>
| |
| − | | |
| − | == Character Encoding ==
| |
| − | 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.
| |
| − | | |
| − | <source lang="xml" >
| |
| − | <?xml version="1.0" encoding="UTF-8"?>
| |
| − | </source>
| |
| − | | |
| − | In addition to specify the correct encoding, you have to make sure your XML editor supports it as well.
| |
| − | | |
| − | == Quiz ==
| |
| − | Fix the following code, make it runnable.
| |
| − | | |
| − | <source lang="xml" >
| |
| − | <!- Typo is common, this is a comment ->
| |
| − | <button label=click onClick="alert("hello")"/>
| |
| − | <button label="click2" onClick="alert("hello)"">
| |
| − | </source>
| |
| − | | |
| − | {{ ZKDevelopersGuidePageFooter}} | |
This documentation is for an older version of ZK. For the latest one, please click here.