Author: achiumenti Date: Fri Dec 19 11:35:13 2008 New Revision: 161
Log: go straight with documentation
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 Fri Dec 19 11:35:13 2008 @@ -2,10 +2,10 @@ @comment node-name, next, previous, up @chapter The web framework
-@code{CLAW-HTML} is one of the most advanced web aplication framework available, complitely object oriented (see @url{http://en.wikipedia.org/wiki/Common_Lisp_Object_System, CLOS}), +@code{CLAW-HTML} is one of the most advanced web application framework available, completely object oriented (see @url{http://en.wikipedia.org/wiki/Common_Lisp_Object_System, CLOS}), it is based on the concept of pages and components.
-Pages are containers for components that provide the request-response business logic. They pervent html elements from duplicating their id, that is very important in component based applications, +Pages are containers for components that provide the request-response business logic. They prevent html elements from duplicating their id, that is very important in component based applications, they are able to handle form requests, and to render components themselves of course.
Components are highly reusable building blocks that make easy and fast the creation of a web application. @@ -17,7 +17,7 @@
If you don't have any idea of what asdf is, please read about it at the @url{http://constantly.at/lisp/asdf/, asdf Manual}.
-Create a directory named @code{clhtml-sample1} and begin writing the @code{clhtml-sample1.asd} file and create a symolic link +Create a directory named @code{clhtml-sample1} and begin writing the @code{clhtml-sample1.asd} file and create a symbolic link into the asdf system directory.
@sp 2 @@ -145,7 +145,7 @@ @section Your first @code{claw-html} page
It's time to create your first page using @code{claw-html} this is done creating a @code{PAGE} subclass, override its -@code{page-content} mathod and finally registering it using the @code{make-page-renderer} function. +@code{page-content} method and finally registering it using the @code{make-page-renderer} function.
In this very basic example we will not use any of the component feature of the framework, just basic tag functions.
@@ -157,10 +157,7 @@ (in-package :clhtml-sample1)
(defclass index-page (page) - ((username :initform nil - :accessor index-page-username) - (passwd :initform nil - :accessor index-page-password))) + ())
(defmethod page-content ((o index-page)) (html> @@ -214,7 +211,7 @@ @end smallexample @sp 2
-If you have done all properly inyour Slime REPL, after the following commands: +If you have done all properly in your Slime REPL, after the following commands:
@sp 2 @smallexample @@ -237,13 +234,13 @@ the framework potentialities. Effectively this is nothing more then what other framework offers.
So let's do what is usually done by component-based frameworks: create the first component. -This will be the site template component, shurely you don't want to write every page to be +This will be the site template component, surely you don't want to write every page to be different from each other, so you'll create the site template.
This component will provide a tag function similar to any other standard like @code{html>, body>, div>} and so on.
-The first thing you'll have to do is to create a class that subcleasses @code{WCOMPONENT} (the name stands for +The first thing you'll have to do is to create a class that subclasses @code{WCOMPONENT} (the name stands for web component) and with metaclass @code{METACOMPONENT}. Giving such metaclass to your component definition makes the framework to automatically create a tag function for this component whose name will be the component name plus a @code{>} at the end. @@ -283,11 +280,11 @@
@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 @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. +component template (or other component methods of course). This is a great point of strength for @code{claw-html} compared to other frameworks, in fact when you put +your component into a collecting loop without being worry, about id duplications, a situation that might 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. +The last thing to note is the absence of the link to the css file. This was made because each component 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-GLOBAL-INITSCRIPTS}, @code{HTCOMPONENT-INITSCRIPTS} and @code{HTCOMPONENT-INITSTYLES} @@ -333,11 +330,11 @@ 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 +Some words must be spent to describe what happens if you want to inject css directives 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 +This method returns a list of strings (containing css directives). The framework removes duplicated 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
@@ -347,11 +344,11 @@ Then there are two different methods: @code{HTCOMPONENT-GLOBAL-INITSCRIPTS} and @code{HTCOMPONENT-INITSCRIPTS}.
@code{HTCOMPONENT-GLOBAL-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. +it's usually used to render javascript functions and global variables.
-@code{HTCOMPONENT-INITSCRIPTS} renders scripts that are executed on <body> onload event, so no function definitions sould be put inside. +@code{HTCOMPONENT-INITSCRIPTS} renders scripts that are executed on <body> onload event, so no function definitions should be put inside.
-For example, suppose that you want to create a component that displays current client time and refresshes it every second; +For example, suppose that you want to create a component that displays current client time and refreshes it every second; you'll create a global js variable that will sore the component DOM node. You won't initialize it into the global section because you must be sure that the DOM tree is ready, so you'll inject it the with initialization method @code{HTCOMPONENT-INITSCRIPTS}.
@@ -401,7 +398,7 @@ @end smalllisp @sp 2
-As you can see, once inserted into your component no more javascrpt is needed, the injection system will do all needed for you! +As you can see, once inserted into your component no more javascript is needed, the injection system will do all needed for you!
Here it is how the page will look like:
@@ -409,7 +406,7 @@ @image{images/idxpage-showtime,150mm,,,png} @sp 2
-@code{claw-html} will let you to safely insert the ame component multiple times because it will coorectly handle injections and id +@code{claw-html} will let you to safely insert the name component multiple times because it will correctly handle injections and id generations.
For example try to put two times the @code{SHOW-TIME>} tag function inside the page content like the following: @@ -432,9 +429,111 @@ @end smalllisp @sp 2
-As you can see from the following source code css and javascript @code{SHOW-TIME} injection are correctly handled and not -duplicated as for the id generations that will not create conflicts. +As you can see from the following source code css and javascript @code{SHOW-TIME} injections are correctly handled and not +duplicated as it is for the id generations that do not create conflicts.
@sp 1 @image{images/idxpage-showtime-src,150mm,,,png} @sp 2 + +@section Working with forms + +Though you can use @code{FORM>, INPUT>, SELECT>}, etc. tag functions, @code{claw-html} shows its full power when you +use its own library of form components. + +First you must know that @code{claw-html} is a component based framework, not an action based one (like Java Apache Struts for example). + +@code{claw-html} form components directly interact with their containing page, so that, when a form action is fired, +input components may 'automatically' read and write the form visit object slots (that is set to the page itself as default). + +Forms, submit buttons, and action links, may fire @code{ACTION-OBJECT} (whose default is the current page) methods on submission, just before the page content rendering. + +@subsection You first form + +All right, now it's time to build your first ``hello world'' form. To do so, you have to change your index.lisp file with the following code: + +@sp 2 +@smalllisp +;;; -*- Mode: LISP; Syntax: COMMON-LISP; Package: CL-USER; Base: 10 -*- +;;; $Header: src/index.lisp $ + +(in-package :clhtml-sample2) + +(defgeneric index-page-say-hello (page)) + +(defclass index-page (page) + ((username :initform nil + :accessor index-page-username) + (welcome-message :initform nil + :accessor index-page-welcome-message))) + +(defmethod index-page-say-hello ((page index-page)) + (setf (index-page-welcome-message page) + (format nil "Hello ~a!" (index-page-username page)))) + +(defmethod page-content ((o index-page)) + (site-template> :id "theBody" + :title "Home test page sample 2" + :class "sampleBody" + (div> :class "topHeader" "top header") + (div> :class "mainContent" + (cform> :action 'index-page-say-hello + "Write your name " + (cinput> :id "username" + :accessor 'index-page-username) + (csubmit> :value "Say hello")) + (h1> (index-page-welcome-message o))) + (div> :style "color: black;" + "Today: " + (show-time> :class "showTime")))) + +(lisplet-register-function-location *fs-lisplet* + (make-page-renderer 'index-page + #'claw-post-parameters + #'claw-get-parameters) + "index.html" + :welcome-page-p t) +@end smalllisp +@sp 2 + +As you can see there is no need to handle http request parameters, neither action dispatching! + +Now suppose that you want your form to be able to say both ``Hello'' and ``Goodbye''. This time you only +have to define the ``goodbye'' method for your page and connect the ``goodbye'' button to it changing the @code{PAGE-CONTENT} method definition, like the following: + +@sp 2 +@smalllisp +(defgeneric index-page-say-goodbye (page)) + +(defmethod index-page-say-goodbye ((page index-page)) + (setf (index-page-welcome-message page) + (format nil "Goodbye ~a!" (index-page-username page)))) + +(defmethod page-content ((o index-page)) + (site-template> :id "theBody" + :title "Home test page sample 2" + :class "sampleBody" + (div> :class "topHeader" "top header") + (div> :class "mainContent" + (cform> :action 'index-page-say-hello +; :method "post" + "Write your name " + (cinput> :id "username" + :accessor 'index-page-username) + (csubmit> :value "Say hello") + (csubmit> :action 'index-page-say-goodbye + :value "Say goodbye")) + (h1> (index-page-welcome-message o))) + (div> :style "color: black;" + "Today: " + (show-time> :class "showTime")))) +@end smalllisp +@sp 2 + +Since you have provided the @code{:ACTION} attribute to the second submit button, your form is now able do use two different methods for action +dispatching. Yes you don't have to implement any custom code for dispatching actions! + +Now you may have noticed that if you submit the form leaving the input box blank, the message ``Hello NIL'' will be displayed. + +There is an easy way to avoid this behaviour, ...validation! +