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. + +@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: +@itemize @minus +@item +@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 +@code{wocomponent-parameters}, but that are present in the constructor function. +@item +@code{htcomponent-body} renders the body of the component +@end itemize + +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" :class "foo" + (p> + Hello world)) +@end lisp +@end cartouche + +and will render as +@cartouche +@example +@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> +@end format +@end example +@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...