1.1 --- a/docs/selectors.html Tue Jul 19 12:31:03 2005 +0000
1.2 +++ b/docs/selectors.html Tue Jul 19 13:31:55 2005 +0000
1.3 @@ -1,202 +1,104 @@
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 <meta content="text/html;charset=ISO-8859-1" http-equiv="Content-Type" />
1.9 <title>Creating Applications: Add Selectors</title>
1.10 -
1.11 -
1.12 - <meta name="generator" content="amaya 8.1a, see http://www.w3.org/Amaya/" />
1.13 -
1.14 + <meta name="generator"
1.15 + content="amaya 8.1a, see http://www.w3.org/Amaya/" />
1.16 <link href="styles.css" rel="stylesheet" type="text/css" />
1.17 -
1.18 </head>
1.19 -
1.20 -
1.21 <body>
1.22 -
1.23 <h1>Creating Applications: Add Selectors</h1>
1.24 -
1.25 <p>In the previous activity we annotated the template
1.26 with
1.27 <a href="structure.html">structural information</a>,
1.28 and these annotations should be sufficient in
1.29 presenting XML documents as Web pages for users to interact with.
1.30 However, in our design, we also wanted to be able to add and remove
1.31 -list items from the example hierarchy:</p>
1.32 -
1.33 -<ul>
1.34 -
1.35 - <li>A list of editable items, each containing...<br />
1.36 -
1.37 - <ul>
1.38 -
1.39 - <li>A list of editable items.</li>
1.40 -
1.41 - </ul>
1.42 -
1.43 - </li>
1.44 -
1.45 -</ul>
1.46 -
1.47 -<p>What we want to do is to have buttons beside each
1.48 -list item
1.49 -(and subitem) which remove only that particular item. In addition, we
1.50 -also want buttons which add items only to the particular list each
1.51 -button appears beneath.<br />
1.52 -
1.53 -</p>
1.54 -
1.55 +list items from the form data structure, and we added some buttons in
1.56 +the template to be used for this purpose.</p>
1.57 <h2>Introducing Selectors</h2>
1.58 -
1.59 -<p>So, we need to add buttons to the Web form which,
1.60 -upon being pressed, provide information about their context to
1.61 -the XSLForms framework and subsequently to the application, so that we
1.62 -know which part of the form is to be altered. To make sure that such
1.63 -contextual information is available in the Web form, we must include
1.64 -such references in the descriptions of these buttons in the template.</p>
1.65 -
1.66 -<p>The concept of a "selector" is a reference which is expressed
1.67 -in a special notation in the template, converted to concrete references
1.68 -in the final output, and can be interpreted when a user submits a form
1.69 -such that the associated section of the XML document version of the
1.70 -form data can be identified in connection with an action. In other
1.71 -words, we write a special value into the definition of a button in a
1.72 -Web form which can automatically be used to refer to other form data
1.73 -when the form is submitted.</p>
1.74 -
1.75 -<p>Taking the HTML example from before, we add some
1.76 -additional annotations to the template to produce something
1.77 +<p>The buttons in the template are implicitly associated with
1.78 +specific items and subitems, and when such buttons are pressed - for
1.79 +example, to remove an item from the list - our application will want to
1.80 +know on which item the removal action is to take place. In order to
1.81 +connect the buttons with specific parts of the form data structure, a
1.82 +special notation is used, and such notation turns elements such as
1.83 +buttons into "selectors" - things which select parts of the structure
1.84 +so that an operation can be carried out on those parts.</p>
1.85 +<p>Taking the example HTML code from before, we add some of these
1.86 +selector annotations to the template to produce something
1.87 like this:</p>
1.88 -
1.89 -<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 /><form action="" method="POST"><br /><br /><!-- Template text between the start and the interesting part. --><br /><br /><div template:element="item"><br /> <p><span style="font-weight: bold;"></span><br /> <span template:attribute="value"><br /> Some item: <input name="{template:field-name()}" type="text" value="{$this-value}" /><br /> </span><br /> <span style="font-weight: bold;"> <input name="remove={template:this-position()}" type="submit" value="Remove" /></span><br /> </p><br /> <p><br /> Itself containing more items:<br /> </p><br /> <p template:element="subitem"><br /> <span template:attribute="subvalue"><br /> Sub-item: <input name="{template:field-name()}" type="text" value="{$this-value}" /><br /> </span><br /> <span style="font-weight: bold;"> <input name="remove2={template:this-position()}" type="submit" value="Remove" /></span><br /> </p><br /> <span style="font-weight: bold;"> <p></span><br style="font-weight: bold;" /><span style="font-weight: bold;"> <input name="add2={template:this-position()}" type="submit" value="Add subitem" /></span><br style="font-weight: bold;" /><span style="font-weight: bold;"> </p></span><br /></div><br /><span style="font-weight: bold;"><p></span><br style="font-weight: bold;" /><span style="font-weight: bold;"> <input name="add={template:this-position()}" type="submit" value="Add item" /></span><br style="font-weight: bold;" /><span style="font-weight: bold;"></p></span><br /><br /><!-- Template text between the interesting part and the end. --><br /><br /></form><br /></body><br /></html></pre>
1.90 -
1.91 +<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 /><form action="" method="POST"><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="<span
1.92 + style="font-weight: bold;">remove={template:this-position()}</span>" 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="<span
1.93 + style="font-weight: bold;">remove2={template:this-position()}</span>" type="submit" value="Remove" /><br /> </p><br /> <p><br /> <input name="<span
1.94 + style="font-weight: bold;">add2={template:this-position()}</span>" type="submit" value="Add subitem" /><br /> </p><br /></div><br /><p><br /> <input name="<span
1.95 + style="font-weight: bold;">add={template:this-position()}</span>" type="submit" value="Add item" /><br /></p><span
1.96 + style="font-weight: bold;"></span><br /><br /><!-- Template text between the interesting part and the end. --><br /><br /></form><br /></body><br /></html></pre>
1.97 <h3>The Remove Buttons</h3>
1.98 -
1.99 -<p>Some of the attributes in the original HTML code have been
1.100 +<p>Some of the attributes in the previous HTML code have been
1.101 changed:</p>
1.102 -
1.103 <ul>
1.104 -
1.105 <li>The <code>input</code> element for the
1.106 -first <code>Remove</code> button (mapping
1.107 -to <code>item</code> elements in the XML document)
1.108 -has a modified <code>name</code> attribute,
1.109 -containing the special <code>remove={template:this-position()}</code>
1.110 -value.</li>
1.111 -
1.112 +first <code>Remove</code> button has a modified <code>name</code>
1.113 +attribute,
1.114 +containing a special value.</li>
1.115 <li>The <code>input</code> element for the second <code>Remove</code>
1.116 -button (mapping to <code>subitem</code> elements in the
1.117 -XML document) has a modified <code>name</code>
1.118 -attribute, containing the special <code>remove2={template:this-position()}</code>
1.119 -value.</li>
1.120 -
1.121 +button has a modified <code>name</code>
1.122 +attribute, containing a special value.</li>
1.123 </ul>
1.124 -
1.125 <p>What these amendments provide is a means for the XSLForms
1.126 framework
1.127 -to connect together the usage of a button in the Web form with an XML
1.128 -document element.</p>
1.129 -
1.130 +to connect together these buttons with a specific element in the
1.131 +form data.</p>
1.132 <ul>
1.133 -
1.134 <li>The first <code>Remove</code> button
1.135 -appears within the <code>p</code> element which is
1.136 -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 +appears within the <code>div</code> element which maps onto items
1.142 +in the form data. This means that each button will refer to a
1.143 +specific item in the form being edited.</li>
1.144 <li>The second <code>Remove</code> button appears
1.145 -within the <code>p</code> element which is
1.146 -annotated as mapping onto the <code>subitem</code>
1.147 -element in the XML document. This means that the special value added
1.148 -above will, in the final output, refer to that specific list (sub)item
1.149 -from
1.150 -the XML document.</li>
1.151 -
1.152 +within the <code>p</code> element which maps onto subitems in the
1.153 +form data. This means that each button will refer to a
1.154 +specific subitem in the form being edited.</li>
1.155 </ul>
1.156 -
1.157 <h3>The Add Buttons</h3>
1.158 -
1.159 -<p>Some additional sections have been added to the original HTML
1.160 +<p>Some other attributes have been changed in the previous HTML
1.161 code:</p>
1.162 -
1.163 <ul>
1.164 -
1.165 - <li>An extra paragraph appears below the <code>subitem</code>
1.166 -paragraph, containing an <code>input</code>
1.167 -element which employs the special <code>add2={template:this-position()}</code>
1.168 -value in the <code>name</code> attribute to
1.169 -represent an <code>Add subitem</code> button.</li>
1.170 -
1.171 - <li>An extra paragraph appears below the <code>item</code>
1.172 -section, containing an <code>input</code> element
1.173 -which employs the special <code>add={template:this-position()}</code>
1.174 -value in the <code>name</code> attribute to
1.175 -represent an <code>Add item</code> button.</li>
1.176 -
1.177 + <li>The <code>input</code> element for the
1.178 +first <code>Add</code> button has a modified <code>name</code>
1.179 +attribute,
1.180 +containing a special value.</li>
1.181 + <li>The <code>input</code> element for the second <code>Add</code>
1.182 +button has a modified <code>name</code>
1.183 +attribute, containing a special value.</li>
1.184 </ul>
1.185 -
1.186 +<ul>
1.187 +</ul>
1.188 <p>What these amendments provide is also a means for the XSLForms
1.189 -framework to connect these buttons to parts of the XML document.</p>
1.190 -
1.191 +framework to connect these buttons to specific parts of the form data.</p>
1.192 <ul>
1.193 -
1.194 <li>The <code>Add subitem</code> button appears
1.195 -outside the <code>p</code> element mapping onto
1.196 -the <code>subitem</code> element in the XML
1.197 -document. Instead, it appears within the <code>p</code>
1.198 -element mapping onto the <code>item</code>
1.199 -element in the XML document. This means that the special value added
1.200 -above will, in the final output, refer to a specific <code>item</code>
1.201 -from
1.202 -the XML document, and the consequence of adding a <code>subitem</code>
1.203 -will be the extension of that list of <code>subitem</code>
1.204 -elements within that <code>item</code> element.</li>
1.205 -
1.206 +outside the <code>p</code> element which maps onto subitems in the
1.207 +form data. Instead, it appears within the <code>p</code>
1.208 +element which maps onto items. This means that each button will refer
1.209 +to a specific item in the form being edited, and the consequence of
1.210 +adding a subitem will be the extension of that item's list of subitems.</li>
1.211 <li>The <code>Add item</code> button
1.212 appears outside the <code>p</code>
1.213 -element mapping onto the <code>item</code>
1.214 -element in the XML document. Instead, it appears within the <code>body</code>
1.215 -element mapping onto the top-level <code>structure</code>
1.216 -element in the XML document. This means that the special value added
1.217 -above will, in the final output, refer to the top-level <code>structure</code>
1.218 +element which maps onto items in the form data. Instead, it appears
1.219 +within the <code>body</code>
1.220 +element which maps onto the top-level <code>structure</code>
1.221 +element in the form data. This means that each button will refer to the
1.222 +top-level <code>structure</code>
1.223 element in
1.224 -the XML document, and the consequence of adding an <code>item</code> will
1.225 -be the extension of the main list of <code>item</code>
1.226 -elements.</li>
1.227 -
1.228 +the form being edited, and the consequence of adding an item will
1.229 +be the extension of the main list of items in the form.</li>
1.230 </ul>
1.231 -
1.232 -<div class="WebStack">
1.233 -<h3>Selector Annotation</h3>
1.234 -
1.235 -<p>Special values of the following form can be used to connect
1.236 -parts of the template with elements in the XML document representation
1.237 -of a form:</p>
1.238 -
1.239 -<dl>
1.240 -
1.241 - <dt><code>selector={template:this-position()}</code></dt>
1.242 -
1.243 - <dd>Given a selector name (<code>selector</code> in
1.244 -this example), this special value produces a reference to an XML
1.245 -document element (or attribute) in the final output. The referenced
1.246 -element or attribute is defined by those <code>template:element</code>
1.247 -and <code>template:attribute</code> annotations on
1.248 -template elements which surround the template element within
1.249 -which this special value is used.</dd>
1.250 -
1.251 -</dl>
1.252 -
1.253 -<p>The <a href="reference.html">reference guide</a>
1.254 -provides a complete list of special values for use in template
1.255 -annotations.</p>
1.256 -
1.257 -</div>
1.258 -
1.259 -<p>Whilst many forms consist only of text fields and action buttons, other types of data are very likely to also be used. <a href="multiple.html">Multiple-choice or enumerated value fields</a> in forms are covered in the next activity in the development <a href="overview.html">process</a>.</p>
1.260 -
1.261 +<p>Whilst many forms consist only of text fields and action buttons,
1.262 +other types of data are very likely to also be used. <a
1.263 + href="multiple.html">Multiple-choice or enumerated value fields</a> in
1.264 +forms are covered in the next activity in the development <a
1.265 + href="overview.html">process</a>.</p>
1.266 </body>
1.267 </html>