1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/docs/selectors.html Sun Jul 17 19:18:51 2005 +0000
1.3 @@ -0,0 +1,205 @@
1.4 +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
1.5 +<html xmlns="http://www.w3.org/1999/xhtml">
1.6 +<head>
1.7 +
1.8 +
1.9 +
1.10 +
1.11 +
1.12 +
1.13 +
1.14 +
1.15 + <meta content="text/html;charset=ISO-8859-1" http-equiv="Content-Type" />
1.16 +
1.17 +
1.18 +
1.19 +
1.20 +
1.21 +
1.22 +
1.23 +
1.24 +
1.25 +
1.26 +
1.27 +
1.28 + <title>Creating Applications: Add Selectors</title>
1.29 + <meta name="generator" content="amaya 8.1a, see http://www.w3.org/Amaya/" />
1.30 +
1.31 +
1.32 +
1.33 +
1.34 +
1.35 +
1.36 +
1.37 +
1.38 + <link href="styles.css" rel="stylesheet" type="text/css" />
1.39 +</head>
1.40 +
1.41 +
1.42 +<body>
1.43 +
1.44 +
1.45 +
1.46 +
1.47 +<h1>Creating Applications: Add Selectors</h1>
1.48 +
1.49 +
1.50 +
1.51 +
1.52 +<p>In the previous activity we annotated the template with
1.53 +structural information, and these annotations should be sufficient in
1.54 +presenting XML documents as Web pages for users to interact with.
1.55 +However, in our design, we also wanted to be able to add and remove
1.56 +list items from the example hierarchy:</p>
1.57 +
1.58 +<ul>
1.59 +
1.60 + <li>A list of editable items, each containing...<br />
1.61 +
1.62 +
1.63 +
1.64 +
1.65 +
1.66 +
1.67 + <ul>
1.68 +
1.69 +
1.70 +
1.71 + <li>A list of editable items.</li>
1.72 +
1.73 +
1.74 +
1.75 +
1.76 +
1.77 +
1.78 + </ul>
1.79 +
1.80 +
1.81 +
1.82 + </li>
1.83 +
1.84 +
1.85 +
1.86 +</ul>
1.87 +
1.88 +<p>What we want to do is to have buttons beside each list item
1.89 +(and subitem) which remove only that particular item. In addition, we
1.90 +also want buttons which add items only to the particular list each
1.91 +button appears beneath.<br />
1.92 +
1.93 +
1.94 +
1.95 +</p>
1.96 +
1.97 +
1.98 +
1.99 +<h2>Introducing Selectors</h2>
1.100 +
1.101 +
1.102 +
1.103 +<p>Taking the HTML example from before, we add some additional annotations to the template to produce something like this:</p>
1.104 +
1.105 +
1.106 +
1.107 +<pre><html xmlns="http://www.w3.org/1999/xhtml"<br /> xmlns:template="http://www.boddie.org.uk/ns/xmltools/template"><br /><head><br /> <title>Example</title><br /></head><br /><body template:element="structure"><br /><br /><!-- Template text between the start and the interesting part. --><br /><br /><div template:element="item"><br /> <p><br /> Some item: <input template:attribute="value" name="{template:field-name()}" type="text" value="{$this-value}" /><br /> <input name="remove={template:this-position()}" type="submit" value="Remove" /><br /> </p><br /> <p><br /> Itself containing more items:<br /> </p><br /> <p template:element="subitem"><br /> Sub-item: <input template:attribute="subvalue" name="{template:field-name()}" type="text" value="{$this-value}" /><br /> <input name="remove2={template:this-position()}" type="submit" value="Remove" /><br /> </p><br /> <p><br /> <input name="add2={template:this-position()} type="submit" value="Add subitem" /><br /> </p><br /></div><br /><p><br /> <input name="add={template:this-position()} type="submit" value="Add item" /><br /></p><br /><br /><!-- Template text between the interesting part and the end. --><br /><br /></body><br /></html></pre>
1.108 +
1.109 +<h3>The Remove Buttons</h3>
1.110 +<p>Some of the attributes in the original HTML code have been changed:</p>
1.111 +
1.112 +
1.113 +
1.114 +<ul>
1.115 +
1.116 +
1.117 +
1.118 + <li>The <code>input</code> element for the first <code>Remove</code> button (mapping to <code>item</code> elements in the XML document) has a modified <code>name</code> attribute, containing the special <code>remove={template:this-position()}</code> value.</li>
1.119 +
1.120 + <li>The <code>input</code> element for the second <code>Remove</code> button (mapping to <code>subitem</code> elements in the XML document) has a modified <code>name</code> attribute, containing the special <code>remove2={template:this-position()}</code> value.</li>
1.121 +
1.122 +
1.123 +
1.124 +
1.125 +
1.126 +</ul>
1.127 +
1.128 +
1.129 +
1.130 +<p>What these amendments provide is a means for the XSLForms framework
1.131 +to connect together the usage of a button in the Web form with an XML
1.132 +document element.</p>
1.133 +
1.134 +<ul>
1.135 +
1.136 + <li>The first <code>Remove</code> button appears within the <code>p</code> element which is annotated as mapping onto the <code>item</code>
1.137 +element in the XML document. This means that the special value added
1.138 +above will, in the final output, refer to that specific list item from
1.139 +the XML document.</li>
1.140 +
1.141 + <li>The second <code>Remove</code> button appears within the <code>p</code> element which is annotated as mapping onto the <code>subitem</code>
1.142 +element in the XML document. This means that the special value added
1.143 +above will, in the final output, refer to that specific list (sub)item from
1.144 +the XML document.</li>
1.145 +
1.146 +</ul>
1.147 +
1.148 +<h3>The Add Buttons</h3>
1.149 +<p>Some additional sections have been added to the original HTML code:</p>
1.150 +
1.151 +<ul>
1.152 +
1.153 + <li>An extra paragraph appears below the <code>subitem</code> paragraph, containing an <code>input</code> element which employs the special <code>add2={template:this-position()}</code> value in the <code>name</code> attribute to represent an <code>Add subitem</code> button.</li>
1.154 +
1.155 + <li>An extra paragraph appears below the <code>item</code> section, containing an <code>input</code> element which employs the special <code>add={template:this-position()}</code> value in the <code>name</code> attribute to represent an <code>Add item</code> button.</li>
1.156 +
1.157 +</ul>
1.158 +
1.159 +<p>What these amendments provide is also a means for the XSLForms framework to connect these buttons to parts of the XML document.</p>
1.160 +
1.161 +<ul>
1.162 +
1.163 + <li>The <code>Add subitem</code> button appears outside the <code>p</code> element mapping onto the <code>subitem</code> element in the XML document. Instead, it appears within the <code>p</code> element mapping onto the <code>item</code>
1.164 +element in the XML document. This means that the special value added
1.165 +above will, in the final output, refer to a specific <code>item</code> from
1.166 +the XML document, and the consequence of adding a <code>subitem</code> will be the extension of that list of <code>subitem</code> elements within that <code>item</code> element.</li>
1.167 +
1.168 + <li>The <code>Add item</code> button appears outside the <code>p</code> element mapping onto the <code>item</code>
1.169 +element in the XML document. Instead, it appears within the <code>body</code> element mapping onto the top-level <code>structure</code>
1.170 +element in the XML document. This means that the special value added
1.171 +above will, in the final output, refer to the top-level <code>structure</code>
1.172 +element in
1.173 +the XML document, and the consequence of adding an <code>item</code> will be the extension of the main list of <code>item</code> elements.</li>
1.174 +
1.175 +</ul>
1.176 +<div class="WebStack">
1.177 +<h3>Selector Annotation</h3>
1.178 +
1.179 +
1.180 +
1.181 +<p>Special values of the following form can be used to connect parts of
1.182 +the template with elements in the XML document representation of a form:</p>
1.183 +
1.184 +
1.185 +
1.186 +<dl>
1.187 + <dt><code>selector={template:this-position()}</code></dt>
1.188 +
1.189 +
1.190 +
1.191 + <dd>Given a selector name (<code>selector</code> in this example),
1.192 +this special value produces a reference to an XML document element (or
1.193 +attribute) in the final output. The referenced element or attribute is
1.194 +defined by those <code>template:element</code> and <code>template:attribute</code> annotations on template elements which surround the template element within which this special value is used.</dd>
1.195 +
1.196 +
1.197 +
1.198 +</dl>
1.199 +
1.200 +
1.201 +
1.202 +<p>The <a href="reference.html">reference guide</a> provides a complete list of special values for use in template annotations.</p>
1.203 +
1.204 +
1.205 +
1.206 +</div>
1.207 +</body>
1.208 +</html>