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

[Andrea Chiumenti]

Author: achiumenti
Date: Wed Dec 17 14:49:02 2008
New Revision: 157

Log:
manual update

Modified:
   trunk/doc/chapters/claw-html.texinfo

Modified: trunk/doc/chapters/claw-html.texinfo
==============================================================================
--- trunk/doc/chapters/claw-html.texinfo	(original)
+++ trunk/doc/chapters/claw-html.texinfo	Wed Dec 17 14:49:02 2008
@@ -167,7 +167,9 @@
    (head>
     (title> "Home test page")
     (link> :rel "stylesheet" :href "docroot/screen.css" :type "text/css"))
-   (body> :class "sampleBody"
+   (body> 
+    :id "theBody"
+    :class "sampleBody"
     (div> :class "topHeader" "top header")
     (div> :class "mainContent"
           (h1> "Hello world")))))
@@ -269,15 +271,82 @@
      (html>
       (head>
        (title> title-value))
-      (body> (wcomponent-informal-parameters obj)
+      (body> :static-id (htcomponent-client-id obj) 
+             (wcomponent-informal-parameters obj)
              (htcomponent-body obj)))))
 @end smalllisp
 @sp 2
 
-Here there are three points to highlight. Firstly the @code{HTCOMPONENT-BODY}, here we are informing the the component will render its child
+Here there are three points to highlight. Firstly the @code{HTCOMPONENT-BODY}, here we are informing that the component will render its child
 at this position. Then the @code{WCOMPONENT-INFORMAL-PARAMETERS} is a method that informs the component to render tag parameters not directly specified into
 the class specification, making it possible to specify any tag parameter to the tag function.
 
-The last thing to notice is the absence of the link to the css file. This was made because each componoent can inject into the page its own css or js definitions
-both at class level and at instance level, that in @code{claw-html} are injected by the component directly into the containing page.
-To add a css or a js file at class definition level you have to implement @code{HTCOMPONENT-SCRIPT-FILES} and @code{HTCOMPONENT-STYLESHEET-FILES} while 
+ at code{CALW-HTML} can control the id of each component so that when a component is put into a page, its id is not duplicated. You can avoid this checking using the
+ at code{STATIC-ID} attribute, so when writing a component you can use the id given to your component through @code{HTCOMPONENT-CLIENT-ID} method an render it into the 
+component template (or other component methods of course). This is a great point of strenght for @code{claw-html} compared to other frameworks, infact when you put 
+your component into a collecting loop without beeing worry, about id duplications, a situation that mhight occur for example when creating table row components.
+
+
+The last thing to note is the absence of the link to the css file. This was made because each componoent can inject into the page its own css or js files or definitions.
+
+To add a css or a js file at class definition level you have to implement @code{HTCOMPONENT-SCRIPT-FILES} and @code{HTCOMPONENT-STYLESHEET-FILES} while to add javascript or 
+css directives into the page you have to use @code{HTCOMPONENT-CLASS-INITSCRIPTS}, @code{HTCOMPONENT-INSTANCE-INITSCRIPT} and @code{HTCOMPONENT-INITSTYLES}
+
+In our case it's simply sufficient to override the @code{HTCOMPONENT-STYLESHEET-FILES} method as described 
+
+ at sp 2
+ at smalllisp
+(defmethod htcomponent-stylesheet-files ((obj site-template))
+  (list "docroot/screen.css"))
+ at end smalllisp
+ at sp 2
+
+So now that the site template component is ready for our simple example you can now use it into your previous page; do change 
+the page-content method definition in the @code{src/index.lisp} file:
+
+ at sp 2
+ at smalllisp
+(defmethod page-content ((o index-page))
+  (site-template> 
+    :id "theBody"
+    :class "sampleBody"
+    :title "Home test page"
+    (div> :class "topHeader" "top header")
+    (div> :class "mainContent"
+          (h1> "Hello world"))))
+ at end smalllisp
+ at sp 2
+
+That will produce the same result of the 'long form' @code{PAGE-CONTENT} implementation!
+
+So, you may have now no repetitions of the html tag elements between application pages, a shorter @code{PAGE-CONTENT} implementation,
+and no problems about forgetting to import common stylesheet files (and .js files if you need one).
+
+For curiosity here it is the html source output:
+
+ at sp 1
+ at image{images/idxpage-src,150mm,,,png}
+ at sp 2
+
+ at subsection Component scripts injection
+
+You have just seen how components can inject css files into your page, as already said for javascript files, this is accomplished by 
+overriding the component method @code{HTCOMPONENT-SCRIPT-FILES}, nothing more.
+
+Some words must be spent to describe what happens if you want to inject css dirsctives and javascript commands into the page inside 
+<style> and <scripts> tags.
+
+When you want to inject css directives into a <style> tag you have to override @code{HTCOMPONENT-INITSTYLES} method.
+This method returns a list of strings (containing css directives). The framework removes uplicate strings and subsequently renders
+inside the <head> tag the <style> tag. The removal of duplicates gives you the possibility of using your component inside loops
+without being worried about duplicating injection
+
+When you want to inject javascript commands (and functions too) the story is a slightly different.
+Firstly commands are injected into a <script> tag that is positioned as the last <body> tag.
+
+Then there are two different methods: @code{HTCOMPONENT-CLASS-INITSCRIPTS} and @code{HTCOMPONENT-INSTANCE-INITSCRIPT}.
+
+ at code{HTCOMPONENT-CLASS-INITSCRIPTS} is used to render scripts that are not tied to a particular instance, but come with the component, 
+it's usually used to render javascript functions and global variabes.
+
+ at code{HTCOMPONENT-INSTANCE-INITSCRIPT} render scripts that are executed on <body> onload event, so no function definitions sould be put inside.