1 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> 2 <html xmlns="http://www.w3.org/1999/xhtml"> 3 <head> 4 5 <meta content="text/html;charset=ISO-8859-1" http-equiv="Content-Type" /> 6 <title>Creating Applications: Add Selectors</title> 7 8 9 <meta name="generator" content="amaya 8.1a, see http://www.w3.org/Amaya/" /> 10 11 <link href="styles.css" rel="stylesheet" type="text/css" /> 12 13 </head> 14 15 16 <body> 17 18 <h1>Creating Applications: Add Selectors</h1> 19 20 <p>In the previous activity we annotated the template 21 with 22 <a href="structure.html">structural information</a>, 23 and these annotations should be sufficient in 24 presenting XML documents as Web pages for users to interact with. 25 However, in our design, we also wanted to be able to add and remove 26 list items from the example hierarchy:</p> 27 28 <ul> 29 30 <li>A list of editable items, each containing...<br /> 31 32 <ul> 33 34 <li>A list of editable items.</li> 35 36 </ul> 37 38 </li> 39 40 </ul> 41 42 <p>What we want to do is to have buttons beside each 43 list item 44 (and subitem) which remove only that particular item. In addition, we 45 also want buttons which add items only to the particular list each 46 button appears beneath.<br /> 47 48 </p> 49 50 <h2>Introducing Selectors</h2> 51 52 <p>So, we need to add buttons to the Web form which, 53 upon being pressed, provide information about their context to 54 the XSLForms framework and subsequently to the application, so that we 55 know which part of the form is to be altered. To make sure that such 56 contextual information is available in the Web form, we must include 57 such references in the descriptions of these buttons in the template.</p> 58 59 <p>The concept of a "selector" is a reference which is expressed 60 in a special notation in the template, converted to concrete references 61 in the final output, and can be interpreted when a user submits a form 62 such that the associated section of the XML document version of the 63 form data can be identified in connection with an action. In other 64 words, we write a special value into the definition of a button in a 65 Web form which can automatically be used to refer to other form data 66 when the form is submitted.</p> 67 68 <p>Taking the HTML example from before, we add some 69 additional annotations to the template to produce something 70 like this:</p> 71 72 <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> 73 74 <h3>The Remove Buttons</h3> 75 76 <p>Some of the attributes in the original HTML code have been 77 changed:</p> 78 79 <ul> 80 81 <li>The <code>input</code> element for the 82 first <code>Remove</code> button (mapping 83 to <code>item</code> elements in the XML document) 84 has a modified <code>name</code> attribute, 85 containing the special <code>remove={template:this-position()}</code> 86 value.</li> 87 88 <li>The <code>input</code> element for the second <code>Remove</code> 89 button (mapping to <code>subitem</code> elements in the 90 XML document) has a modified <code>name</code> 91 attribute, containing the special <code>remove2={template:this-position()}</code> 92 value.</li> 93 94 </ul> 95 96 <p>What these amendments provide is a means for the XSLForms 97 framework 98 to connect together the usage of a button in the Web form with an XML 99 document element.</p> 100 101 <ul> 102 103 <li>The first <code>Remove</code> button 104 appears within the <code>p</code> element which is 105 annotated as mapping onto the <code>item</code> 106 element in the XML document. This means that the special value added 107 above will, in the final output, refer to that specific list item from 108 the XML document.</li> 109 110 <li>The second <code>Remove</code> button appears 111 within the <code>p</code> element which is 112 annotated as mapping onto the <code>subitem</code> 113 element in the XML document. This means that the special value added 114 above will, in the final output, refer to that specific list (sub)item 115 from 116 the XML document.</li> 117 118 </ul> 119 120 <h3>The Add Buttons</h3> 121 122 <p>Some additional sections have been added to the original HTML 123 code:</p> 124 125 <ul> 126 127 <li>An extra paragraph appears below the <code>subitem</code> 128 paragraph, containing an <code>input</code> 129 element which employs the special <code>add2={template:this-position()}</code> 130 value in the <code>name</code> attribute to 131 represent an <code>Add subitem</code> button.</li> 132 133 <li>An extra paragraph appears below the <code>item</code> 134 section, containing an <code>input</code> element 135 which employs the special <code>add={template:this-position()}</code> 136 value in the <code>name</code> attribute to 137 represent an <code>Add item</code> button.</li> 138 139 </ul> 140 141 <p>What these amendments provide is also a means for the XSLForms 142 framework to connect these buttons to parts of the XML document.</p> 143 144 <ul> 145 146 <li>The <code>Add subitem</code> button appears 147 outside the <code>p</code> element mapping onto 148 the <code>subitem</code> element in the XML 149 document. Instead, it appears within the <code>p</code> 150 element mapping onto the <code>item</code> 151 element in the XML document. This means that the special value added 152 above will, in the final output, refer to a specific <code>item</code> 153 from 154 the XML document, and the consequence of adding a <code>subitem</code> 155 will be the extension of that list of <code>subitem</code> 156 elements within that <code>item</code> element.</li> 157 158 <li>The <code>Add item</code> button 159 appears outside the <code>p</code> 160 element mapping onto the <code>item</code> 161 element in the XML document. Instead, it appears within the <code>body</code> 162 element mapping onto the top-level <code>structure</code> 163 element in the XML document. This means that the special value added 164 above will, in the final output, refer to the top-level <code>structure</code> 165 element in 166 the XML document, and the consequence of adding an <code>item</code> will 167 be the extension of the main list of <code>item</code> 168 elements.</li> 169 170 </ul> 171 172 <div class="WebStack"> 173 <h3>Selector Annotation</h3> 174 175 <p>Special values of the following form can be used to connect 176 parts of the template with elements in the XML document representation 177 of a form:</p> 178 179 <dl> 180 181 <dt><code>selector={template:this-position()}</code></dt> 182 183 <dd>Given a selector name (<code>selector</code> in 184 this example), this special value produces a reference to an XML 185 document element (or attribute) in the final output. The referenced 186 element or attribute is defined by those <code>template:element</code> 187 and <code>template:attribute</code> annotations on 188 template elements which surround the template element within 189 which this special value is used.</dd> 190 191 </dl> 192 193 <p>The <a href="reference.html">reference guide</a> 194 provides a complete list of special values for use in template 195 annotations.</p> 196 197 </div> 198 199 <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> 200 201 </body> 202 </html>