Author: achiumenti Date: Thu Apr 10 02:08:57 2008 New Revision: 37
Modified: trunk/doc/chapters/getting-started.texinfo trunk/doc/chapters/writing-components.texinfo trunk/doc/claw.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 Thu Apr 10 02:08:57 2008 @@ -1,97 +1,4 @@ @node Getting Started @comment node-name, next, previous, up -@chapter Getting started with @value{claw} +@chapter Getting started with @value{claw}, your first application
-Now that you know how to write pages in @value{claw}, lets move to a further step: writing components. - -A real @value{claw} web application is made of a lisplet, several pages and resources, and, of course, many reusable -components that go into pages. - -Using reusable components, may dramatically improve your productivity. You can then create custom components libraries -that will give to your web application a crystal clear style, and speed up the creation of repetitive piece -of HTML code, as page templates for instance. - -So said, let's create our first @value{claw} component, a site template. -@cartouche -@lisp -(defcomponent site-template () ()) - -(defmethod wcomponent-parameters ((o site-template)) - (list :title :required :home-page "/claw/test/index.html")) - -(defmethod wcomponent-template ((o site-template)) - (html> - (head> - (title> - (wcomponent-parameter-value o :title))) - (body> - (wcomponent-informal-parameters o) - (div> - :style "background-color: #DBDFE0;padding: 3px;" - (a> :href (wcomponent-parameter-value o :home-page) "home")) - (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...
Modified: trunk/doc/chapters/writing-components.texinfo ============================================================================== --- trunk/doc/chapters/writing-components.texinfo (original) +++ trunk/doc/chapters/writing-components.texinfo Thu Apr 10 02:08:57 2008 @@ -1,3 +1,97 @@ @node writing components @comment node-name, next, previous, up @chapter Creating a web application by writing reusable components + +Now that you know how to write pages in @value{claw}, lets move to a further step: writing components. + +A real @value{claw} web application is made of a lisplet, several pages and resources, and, of course, many reusable +components that go into pages. + +Using reusable components, may dramatically improve your productivity. You can then create custom components libraries +that will give to your web application a crystal clear style, and speed up the creation of repetitive piece +of HTML code, as page templates for instance. + +So said, let's create our first @value{claw} component, a site template. +@cartouche +@lisp +(defcomponent site-template () ()) + +(defmethod wcomponent-parameters ((o site-template)) + (list :title :required :home-page "/claw/test/index.html")) + +(defmethod wcomponent-template ((o site-template)) + (html> + (head> + (title> + (wcomponent-parameter-value o :title))) + (body> + (wcomponent-informal-parameters o) + (div> + :style "background-color: #DBDFE0;padding: 3px;" + (a> :href (wcomponent-parameter-value o :home-page) "home")) + (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...
Modified: trunk/doc/claw.texinfo ============================================================================== --- trunk/doc/claw.texinfo (original) +++ trunk/doc/claw.texinfo Thu Apr 10 02:08:57 2008 @@ -48,13 +48,12 @@ * Server:: * Lisplets:: * Pages:: -* Getting Started:: -* i18n:: +* writing components:: * forms:: * validation:: -* writing components:: -* advanced components:: +* i18n:: * login access:: +* Getting Started:: * Advanced techniques:: * Function index:: @c * Starting and Stopping:: @@ -71,13 +70,12 @@ @include chapters/server.texinfo @include chapters/lisplets.texinfo @include chapters/pages.texinfo -@include chapters/getting-started.texinfo -@include chapters/i18n.texinfo +@include chapters/writing-components.texinfo @include chapters/forms.texinfo @include chapters/validation.texinfo -@include chapters/writing-components.texinfo -@include chapters/advanced-components.texinfo +@include chapters/i18n.texinfo @include chapters/access.texinfo +@include chapters/getting-started.texinfo @include chapters/advanced-techniques.texinfo
@node Function index