[claw-cvs] r39 - trunk/doc/chapters

[achiumenti at common-lisp.net]

Author: achiumenti
Date: Tue Apr 15 13:48:02 2008
New Revision: 39

Modified:
   trunk/doc/chapters/writing-components.texinfo
Log:
updating user manual

Modified: trunk/doc/chapters/writing-components.texinfo
==============================================================================
--- trunk/doc/chapters/writing-components.texinfo	(original)
+++ trunk/doc/chapters/writing-components.texinfo	Tue Apr 15 13:48:02 2008
@@ -44,8 +44,8 @@
 object, and is meant to be used just like any other standard function tag.
 
 The overriding of the method @code{wocomponent-parameters} must return an associative list where, if the key value is @code{:REQUIRED},
-it means that is is mandatory for the constructor function. In our case study a call to @code{SITE-TEMPLATE>} must contains also the 
-keyword @code{:TITLE} followed by its value. If the @code{:TITLE} is not provided an error will be signaled during the component 
+it means that it is mandatory for the constructor function. In our case study, a call to @code{SITE-TEMPLATE>} must contains also the 
+keyword @code{:TITLE} followed by its value. If the @code{:TITLE} is not provided, an error is signaled during the component 
 instantiation.
 
 The overriding of the method @code{wocomponent-template} is in charge for the graphic aspect of the component, as you can imagine.
@@ -55,12 +55,12 @@
 @code{wcomponent-parameter-value} is used to retrieve a parameter passed to the constructor function.
 @item
 @code{wcomponent-informal-parameters} renders as an associative list of all the parameters not directly declared with the method
- at code{wocomponent-parameters}, but that are present in the constructor function.
+ at code{wocomponent-parameters}, but are present in the constructor function, such as may be a @code{:CLASS} attribute.
 @item
- at code{htcomponent-body} renders the body of the component
+ at code{htcomponent-body} renders the content body of the component
 @end itemize
 
-So a call to the constructor function of our new fresh component might have this shape:
+So, a call to the constructor function of our new fresh component, might have this shape:
 @cartouche
 @lisp
 (site-template> :title "this is the page title" 
@@ -94,12 +94,13 @@
 
 Ouch, this is nearly what we expected, but it seems there are two extraneous tags, do you see them?
 
-They are the meta and the script tags.
+They are the <meta> and the <script> tags.
 
-The meta tag is inserted by the @code{HTHEAD} component, that we have instantiated with @code{HEAD>}. 
-The value of the content attribute, is taken from the @code{PAGE-CONTENT-TYPE} slot method, whose default is @code{HUNCHENTOOT:*DEFAULT-CONTENT-TYPE*}.
+The <meta> tag is inserted by the @code{HTHEAD} component, that we have instantiated with @code{HEAD>}. 
+The value of the @code{content} attribute is taken from the @code{PAGE-CONTENT-TYPE} slot method of the @code{PAGE} class, whose default is @code{HUNCHENTOOT:*DEFAULT-CONTENT-TYPE*}.
+It is recomended to have ti value set to @code{"text/html; charset=UTF-8"}.
 
-The script tag is used when @value{claw} components want to inject their instance javascripts.
+The <script> tag is used when @value{claw} components want to inject their instance javascripts.
 So, for example, we could create a component that, when clicked, it shows a js alert containing the html
 component of another component:
 
@@ -111,12 +112,14 @@
   (list :id :required :ref-id :required))
 
 (defmethod wcomponent-template ((inspector inspector))
-  (div> :static-id (htcomponent-client-id inspactor) 
-        (htcomponent-body o)))
+  (div> :static-id (htcomponent-client-id inspector) 
+        (htcomponent-body inspector)))
 
 (defmethod htcomponent-instance-initscript ((inspector inspector))
-  (format nil "document.getElementById('~a').onclick = 
-          function () @{alert(document.getElementById('~a').innerHTML);@};"
+  (format nil "document.getElementById\('~a').onclick = 
+          function \() @{
+            alert\(document.getElementById\('~a').innerHTML);
+            @};"
           (htcomponent-client-id inspector)
           (wcomponent-parameter-value inspector :ref-id)))
 
@@ -129,11 +132,45 @@
 @lisp
 (defmethod page-content ((some-page some-page))
   (let ((hidden-component-id (generate-id "hidden"))
-        (rnd-value (prin1-to-string (random 10000)))
+        (rnd-value (prin1-to-string (random 10000))))
     (site-template> :title "this is the page title" 
                 :class "foo"
                 (p>
-                  (div> :static-id hidden-component-id rnd-value)
-                  (inspector> :id "inspector" "Show value"))))))
+                  (div> :static-id hidden-component-id 
+                        :style "display: none;" rnd-value)
+                  (inspector> :id "inspector" 
+                              :ref-id hidden-component-id "Show value")))))
 @end lisp
 @end cartouche
+
+and will render as:
+ at cartouche
+ at example
+ at format
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" 
+          "http://www.w3.org/TR/html4/strict.dtd">
+<html>
+  <head>
+    <meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
+    <title>this is the page title</title>
+  </head>
+  <body class="foo">
+    <p>
+      <div id="hiddenComp" style="display: none;">2351</div>
+      <div id="inspector">Show value</div>
+    </p>
+    <script type="text/javascript">
+//<!--
+document.addEventListener('DOMContentLoaded', function(e) @{
+document.getElementById('inspector').onclick = 
+          function () @{
+            alert(document.getElementById('hiddenComp').innerHTML);
+            @};
+@}, false);
+//-->
+    </script>
+  </body>
+</html>
+ at end format
+ at end example
+ at end cartouche