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

Wed Apr 9 21:13:20 UTC 2008

Author: achiumenti
Date: Wed Apr  9 17:13:20 2008
New Revision: 36

Modified:
   trunk/doc/chapters/getting-started.texinfo
Log:
user manual update


Modified: trunk/doc/chapters/getting-started.texinfo
==============================================================================

--- trunk/doc/chapters/getting-started.texinfo	(original)
+++ trunk/doc/chapters/getting-started.texinfo	Wed Apr  9 17:13:20 2008
@@ -23,12 +23,7 @@
   (html> 
    (head>
     (title> 
-     (wcomponent-parameter-value o :title))
-    (style> :type "text/css"
-"input.error {
-  background-color: #FF9999;
-}
-"))
+     (wcomponent-parameter-value o :title)))
    (body>      
     (wcomponent-informal-parameters o)
     (div>
@@ -37,5 +32,66 @@
     (htcomponent-body o))))
 @end lisp
 @end cartouche
+
 Thought this is not the best template you can do, it's a nice starting point to explain how components are created
 (and used).
+
+First let's analyze the @code{defcomponent} instruction: this macro has the same signature of the @code{defclass} macro,
+except that it creates a class that is always a @code{WOCOMPONENT} subclass.
+
+ at code{defcomponent} also creates a function whose symbol is
+the name of the component plus the character '>', @code{SITE-TEMPLATE>} in the specific case, that instantiate the corresponding
+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 
+instantiation.
+
+The overriding of the method @code{wocomponent-template} is in charge for the graphic aspect of the component, as you can imagine.
+Inside this method we have used calls to other three very important component methods:
+ at itemize @minus
+ at item 
+ at code{wcomponent-parameter-value} is used to retrieve a parameter passed to the constructor function.
+ at item
+ at 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 item
+ at code{htcomponent-body} renders the body of the component
+ at end itemize
+
+So a call to the constructor function of our new fresh component might have this shape:
+ at cartouche
+ at lisp
+(site-template> :title "this is the page title" :class "foo"
+                (p>
+                  Hello world))
+ at end lisp
+ at end cartouche
+
+and will render as
+ at cartouche
+ at example
+ at format
+<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>Hello world</p>
+    <script type="text/javascript">
+//<!--
+document.addEventListener('DOMContentLoaded', function(e) @{@}, false);
+//-->
+    </script>
+  </body>
+</html>
+ at end format
+ at end example
+ at end cartouche
+
+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.
+...continue...

