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