1.1 --- a/docs/in-page-updates.html Sat Sep 08 16:53:18 2007 +0000
1.2 +++ b/docs/in-page-updates.html Sat Sep 08 16:53:34 2007 +0000
1.3 @@ -1,8 +1,8 @@
1.4 +<?xml version="1.0" encoding="iso-8859-1"?>
1.5 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
1.6 <html xmlns="http://www.w3.org/1999/xhtml"><head>
1.7 <meta content="text/html;charset=ISO-8859-1" http-equiv="Content-Type" />
1.8 -
1.9 - <title>Creating Applications: In-Page Updates</title><meta name="generator" content="amaya 8.1a, see http://www.w3.org/Amaya/" />
1.10 + <title>Creating Applications: In-Page Updates</title>
1.11 <link href="styles.css" rel="stylesheet" type="text/css" /></head>
1.12 <body>
1.13 <h1>Creating Applications: In-Page Updates</h1>
1.14 @@ -14,8 +14,8 @@
1.15 <p>Consider the addition of a comment field to our application. Here is
1.16 how the HTML code might look:</p>
1.17 <pre><div template:element="item"><br /> <p><br /> Some item: <input template:attribute-field="value" name="..." type="text" value="..." /><br /> <input name="..." template:selector-field="remove" type="submit" value="Remove" /><br /> </p><br /> <p><br /> Item type:<br /> <select template:multiple-choice-list-field="type,type-enum,value" name="..." multiple="multiple"><br /> <option template:multiple-choice-list-value="type-enum,value,selected" value="..." /><br /> </select><br /> </p><br /> <span style="font-weight: bold;"><p template:element="options"></span><br style="font-weight: bold;" /><span style="font-weight: bold;"> <span </span><span style="font-weight: bold;">template:element="comment"></span><span style="font-weight: bold;">Comment:</span><br style="font-weight: bold;" /><span style="font-weight: bold;"> <textarea template:attribute-area="value,insert" name="..." cols="40" rows="3"></span><br style="font-weight: bold;" /><span style="font-weight: bold;"> Some comment</span><br style="font-weight: bold;" /><span style="font-weight: bold;"> </textarea><br /> </span><br style="font-weight: bold;" /></span><span style="font-weight: bold;"> </p></span><br /> <p><br /> Itself containing more items:<br /> </p><br /> <p template:element="subitem"><br /> Sub-item: <input template:attribute-field="subvalue" name="..." type="text" value="..." /><br /> <input name="..." template:selector-field="remove2" type="submit" value="Remove" /><br /> </p><br /> <p><br /> <input name="..." template:selector-field="add2,subitem" type="submit" value="Add subitem" /><br /> </p><br /></div></pre>
1.18 -<p>Here, a <code>textarea</code> element has been added with a special <code>template:attribute-area</code> annotation being used to state that the contents of the element are to be mapped to the <code>value</code> attribute, and that the attribute contents are to be inserted inside the <code>textarea</code> element (replacing the <code>Some Comment</code> text).</p><p>The newly-added <code>textarea</code> field might actually be
1.19 -presented in the application in its current state, despite the lack of any <code>options</code> or <code>comment</code>
1.20 +<p>Here, a <code>textarea</code> element has been added with a special <code>template:attribute-area</code> annotation being used to state that the contents of the element are to be mapped to the <code>value</code> attribute, and that the attribute contents are to be inserted inside the <code>textarea</code> element (replacing the <code>Some Comment</code> text).</p><p>The newly-added <code>textarea</code> field might actually be
1.21 +presented in the application in its current state, despite the lack of any <code>options</code> or <code>comment</code>
1.22 elements
1.23 manipulated by the
1.24 application, due to the document initialisation mechanism employed by
1.25 @@ -24,9 +24,9 @@
1.26 document had a certain value or state.</p>
1.27 <p>Let us imagine that if the type of an item was set to "Personal",
1.28 the comment field would appear and permit the recording of some text
1.29 -for that item. One approach that would make this possible is to
1.30 +for that item. One approach that would make this possible is to
1.31 add a transformation which checks the type values set for each of the
1.32 -items and removes the <code>options</code> and <code>comment</code> elements for items which do not qualify. In the Web resource, we make the following
1.33 +items and removes the <code>options</code> and <code>comment</code> elements for items which do not qualify. In the Web resource, we make the following
1.34 changes:</p>
1.35 <pre> transform_resources = {<br /> "comments" : ["structure_comments.xsl"]<br /> }</pre>
1.36 <p>What this does is to state that when we carry out the <code>comments</code>
1.37 @@ -37,11 +37,11 @@
1.38 <ol>
1.39 <li>Descend into the form data structure, copying all elements,
1.40 attributes and text that the stylesheet is not programmed to recognise.</li>
1.41 - <li>When encountering an <code>item</code> element (which the
1.42 + <li>When encountering an <code>item</code> element (which the
1.43 stylesheet is programmed to recognise), do the following:<br />
1.44 <ol>
1.45 - <li>Copy the element "skeleton" and its attributes so that
1.46 -the <code>value</code> attribute is retained.</li>
1.47 + <li>Copy the element "skeleton" and its attributes so that
1.48 +the <code>value</code> attribute is retained.</li>
1.49 <li>Produce a new <code>options</code> element and process it.</li>
1.50 </ol>
1.51 </li>
1.52 @@ -49,9 +49,9 @@
1.53 following:<br />
1.54 <ol>
1.55 <li>Inside this new <code>options</code> element, investigate
1.56 -the values associated with the <code>type</code> element.</li>
1.57 +the values associated with the <code>type</code> element.</li>
1.58 <li>If any of the selected type values represents the "Personal" category, make a new <code>comment</code>
1.59 -element, then add any attributes that may be found on
1.60 +element, then add any attributes that may be found on
1.61 existing <code>comment</code> elements within the current <code>type</code>
1.62 element.</li>
1.63 </ol>
1.64 @@ -60,7 +60,7 @@
1.65 <p>Since this stylesheet is used after the document initialisation,
1.66 we may (and even must) take advantage of the results of that activity, including noting that selected values on <code>type-enum</code>
1.67 elements are marked with the <code>value-is-set</code> attribute.</p>
1.68 -<p>The stylesheet source code can be found in <code>examples/Common/VerySimple/Resources/structure_comments.xsl</code>.</p>
1.69 +<p>The stylesheet source code can be found in <code>examples/Common/VerySimple/Resources/structure_comments.xsl</code>.</p>
1.70 <h2>Limitations and Enhancements</h2>
1.71 <p>Whilst the above modifications adds a comment field for each item
1.72 with a type of "Personal", and whilst the comment field will appear and
1.73 @@ -68,7 +68,7 @@
1.74 when items and subitems are added and removed. We could add an update
1.75 button to the page which performs an explicit refresh of the page
1.76 without adding or removing anything, and for the sake of usability, we
1.77 -probably should add such a button (just below the <code>Add item</code>
1.78 +probably should add such a button (just below the <code>Add item</code>
1.79 button):</p>
1.80 <pre><p><br /> <input name="update" type="submit" value="Update" /><br /></p></pre>
1.81 <p>However, we could also add an in-page update to make each comments
1.82 @@ -84,21 +84,21 @@
1.83 surrounding the comment field, annotating the paragraph with the
1.84 following attributes:</p>
1.85 <ul>
1.86 - <li>The <code>template:id</code> attribute is used to define a
1.87 + <li>The <code>template:id</code> attribute is used to define a
1.88 template fragment used only to prepare the updated part of the Web
1.89 page. Here we define the fragment or region as being just this
1.90 paragraph.</li>
1.91 - <li>The standard HTML <code>id</code> attribute is used to
1.92 + <li>The standard HTML <code>id</code> attribute is used to
1.93 define which part of the active Web page will be replaced when
1.94 performing an in-page update. This attribute needs to have a unique
1.95 value, but the easiest basis for such a value is a selector-style
1.96 -reference to the <code>options</code> element within which the <code>comment</code>
1.97 +reference to the <code>options</code> element within which the <code>comment</code>
1.98 element resides.</li>
1.99 </ul>
1.100 -<p>Another change has been to put the <code>template:element</code>
1.101 +<p>Another change has been to put the <code>template:element</code>
1.102 annotation inside the above fragment or region annotations. Had we not
1.103 -done this, the lack of a <code>comment</code> element in the form
1.104 -data could have prevented the <code>id</code> attribute from
1.105 +done this, the lack of a <code>comment</code> element in the form
1.106 +data could have prevented the <code>id</code> attribute from
1.107 appearing in the Web page, this preventing any hope of an in-page
1.108 update since there would be no way of knowing where such an update
1.109 should be applied.</p>
1.110 @@ -107,7 +107,7 @@
1.111 references to scripts must also be added to the template, as shown in
1.112 the following excerpt:</p>
1.113 <pre><head><br /> <title>Example</title><br /> <span style="font-weight: bold;"><script type="text/javascript" src="scripts/sarissa.js"> </script></span><br style="font-weight: bold;" /><span style="font-weight: bold;"> <script type="text/javascript" src="scripts/XSLForms.js"> </script></span><br /></head></pre>
1.114 -<p>These special script files can be found in <code>examples/Common/VerySimple/Resources/scripts</code>.</p>
1.115 +<p>These special script files can be found in <code>examples/Common/VerySimple/Resources/scripts</code>.</p>
1.116 <p>Now we can concentrate on adding the event which triggers an in-page
1.117 update. Since it is the type values that cause each comment field to be
1.118 added or removed, we add an event attribute on the form field
1.119 @@ -128,15 +128,15 @@
1.120 'value')}'</span></dt>
1.121 <dd>The fields which are going to be used in the processing of the
1.122 update. Since the presence of the comment field depends on a
1.123 -specific <code>type</code> element and its <code>type-enum</code>
1.124 -elements' <code>value</code> attributes, we specify the names of
1.125 +specific <code>type</code> element and its <code>type-enum</code>
1.126 +elements' <code>value</code> attributes, we specify the names of
1.127 the fields which yield these values.</dd>
1.128 <dt><span style="font-weight: bold;">'{template:other-elements(../options)}'</span></dt>
1.129 <dd>The region which is to be updated. Here, we recall that we
1.130 defined the region using a special reference to the <code>options</code>
1.131 -element holding <code>comment</code> element. Thus, we use a
1.132 +element holding <code>comment</code> element. Thus, we use a
1.133 special value which also refers to that element from the context of
1.134 -the <code>type</code> element.</dd>
1.135 +the <code>type</code> element.</dd>
1.136 <dt><span style="font-weight: bold;">'{template:child-attribute('value',
1.137 template:child-element('comment', 1,
1.138 template:other-elements(../options)))}'</span></dt>
1.139 @@ -178,7 +178,7 @@
1.140 stylesheet filename that will be generated to produce the page
1.141 fragments for such comment regions, along with the region marker that
1.142 we defined above.</p>
1.143 -<p>The <code>respond_to_form</code> method now also includes some
1.144 +<p>The <code>respond_to_form</code> method now also includes some
1.145 additional code:</p>
1.146 <pre> def respond_to_form(self, trans, form):<br /><br /> """<br /> Respond to a request having the given transaction 'trans' and the given<br /> 'form' information.<br /> """<br /><br /> <span style="font-weight: bold;">in_page_resource = self.get_in_page_resource(trans)</span><br style="font-weight: bold;" /><span style="font-weight: bold;"> parameters = form.get_parameters()</span><br /> documents = form.get_documents()<br /></pre>
1.147 <p>Here, we find out whether an in-page update is requested, along with
1.148 @@ -191,7 +191,7 @@
1.149 <p>The significant changes begin when presenting the result of the
1.150 request processing:</p>
1.151 <pre> # Start the response.<br /><br /> trans.set_content_type(WebStack.Generic.ContentType("application/xhtml+xml", self.encoding))<br /><br /><span style="font-weight: bold;"></span><span style="font-weight: bold;"> # Ensure that an output stylesheet exists.</span><br style="font-weight: bold;" /><br style="font-weight: bold;" /><span style="font-weight: bold;"> if in_page_resource in self.in_page_resources.keys():</span><br style="font-weight: bold;" /><span style="font-weight: bold;"> trans_xsl = self.prepare_fragment(in_page_resource)</span><span style="font-weight: bold;"></span><br style="font-weight: bold;" /><span style="font-weight: bold;"> stylesheet_parameters = self.prepare_parameters(parameters)</span><br style="font-weight: bold;" /><span style="font-weight: bold;"> else:</span><br style="font-weight: bold;" /><span style="font-weight: bold;"> trans_xsl = self.prepare_output("structure")<br /></span> <span style="font-weight: bold;"></span><span style="font-weight: bold;"> stylesheet_parameters = {}</span></pre>
1.152 -<p>Instead of just obtaining a stylesheet for the <code>structure</code>
1.153 +<p>Instead of just obtaining a stylesheet for the <code>structure</code>
1.154 document, we instead check to see if an in-page update is being
1.155 requested and, if so, prepare the stylesheet representing the fragment
1.156 of the Web form to be presented. Additionally, we obtain special
1.157 @@ -203,7 +203,7 @@
1.158 <pre><span style="font-weight: bold;"> # Complete the response.<br /><br /> self.send_output(trans, [trans_xsl], structure<span style="font-weight: bold;">, stylesheet_parameters</span>)</span></pre>
1.159 <p>In order to introduce the infrastructure mentioned above which
1.160 separates requests for Web pages from requests for JavaScript files, we
1.161 -need to provide a more sophisticated implementation of the <code>get_site</code>
1.162 +need to provide a more sophisticated implementation of the <code>get_site</code>
1.163 function:</p>
1.164 <pre><span style="font-weight: bold;"># Site map initialisation.</span><br style="font-weight: bold;" /><br style="font-weight: bold;" /><span style="font-weight: bold;">def get_site():</span><br style="font-weight: bold;" /><br style="font-weight: bold;" /><span style="font-weight: bold;"> "Return a simple Web site resource."</span><br style="font-weight: bold;" /><br style="font-weight: bold;" /><span style="font-weight: bold;"> # Get the main resource and the directory used by the application.</span><br style="font-weight: bold;" /><br style="font-weight: bold;" /><span style="font-weight: bold;"> very_simple_resource = VerySimpleResource()</span><br style="font-weight: bold;" /><span style="font-weight: bold;"> directory = very_simple_resource.resource_dir</span><br style="font-weight: bold;" /><br style="font-weight: bold;" /><span style="font-weight: bold;"> # Make a simple Web site.</span><br style="font-weight: bold;" /><br style="font-weight: bold;" /><span style="font-weight: bold;"> resource = MapResource({</span><br style="font-weight: bold;" /><span style="font-weight: bold;"> # Static resources:</span><br style="font-weight: bold;" /><span style="font-weight: bold;"> "scripts" : DirectoryResource(os.path.join(directory, "scripts"), {"js" : "text/javascript"}),</span><br style="font-weight: bold;" /><span style="font-weight: bold;"> # Main page and in-page resources:</span><br style="font-weight: bold;" /><span style="font-weight: bold;"> None : very_simple_resource</span><br style="font-weight: bold;" /><span style="font-weight: bold;"> })</span><br style="font-weight: bold;" /><br style="font-weight: bold;" /><span style="font-weight: bold;"> return resource</span></pre>
1.165 <p>What this does is to create a resource for the application, as
1.166 @@ -211,9 +211,9 @@
1.167 which examines the path or URL on the incoming requests and directs
1.168 such requests according to the following scheme:</p>
1.169 <ul>
1.170 - <li>If the request mentions something under <code>scripts</code>
1.171 + <li>If the request mentions something under <code>scripts</code>
1.172 in its URL, we employ the WebStack <code>DirectoryResource</code> to
1.173 -send the file from the <code>scripts</code> subdirectory of the
1.174 +send the file from the <code>scripts</code> subdirectory of the
1.175 application's <code>Resources</code> directory.</li>
1.176 <li>Otherwise, we pass the request on to our application resource in
1.177 order to produce a Web page for the user.</li>
1.178 @@ -222,4 +222,4 @@
1.179 script file; otherwise it gets a Web page showing either all of the
1.180 form (if a normal request is received), or a part of the form (if an
1.181 in-page request is received).</p>
1.182 -</body></html>
1.183 \ No newline at end of file
1.184 +</body></html>