Author: achiumenti Date: Wed Apr 9 09:16:31 2008 New Revision: 29

Added: trunk/doc/chapters/access.texinfo trunk/doc/chapters/advanced-components.texinfo trunk/doc/chapters/advanced-techniques.texinfo trunk/doc/chapters/forms.texinfo trunk/doc/chapters/getting-started.texinfo trunk/doc/chapters/i18n.texinfo trunk/doc/chapters/lisplets.texinfo trunk/doc/chapters/pages.texinfo trunk/doc/chapters/validation.texinfo trunk/doc/chapters/writing-components.texinfo Log: updating user manual

Added: trunk/doc/chapters/access.texinfo ============================================================================== --- (empty file) +++ trunk/doc/chapters/access.texinfo Wed Apr 9 09:16:31 2008 @@ -0,0 +1,3 @@ +@node login access +@comment node-name, next, previous, up +@chapter Access validation and authorization

Added: trunk/doc/chapters/advanced-components.texinfo ============================================================================== --- (empty file) +++ trunk/doc/chapters/advanced-components.texinfo Wed Apr 9 09:16:31 2008 @@ -0,0 +1,3 @@ +@node advanced components +@comment node-name, next, previous, up +@chapter Writing advanced components

Added: trunk/doc/chapters/advanced-techniques.texinfo ============================================================================== --- (empty file) +++ trunk/doc/chapters/advanced-techniques.texinfo Wed Apr 9 09:16:31 2008 @@ -0,0 +1,3 @@ +@node Advanced techniques +@comment node-name, next, previous, up +@chapter Advanced techniques

Added: trunk/doc/chapters/forms.texinfo ============================================================================== --- (empty file) +++ trunk/doc/chapters/forms.texinfo Wed Apr 9 09:16:31 2008 @@ -0,0 +1,3 @@ +@node forms +@comment node-name, next, previous, up +@chapter @value{claw} forms and form components

Added: trunk/doc/chapters/getting-started.texinfo ============================================================================== --- (empty file) +++ trunk/doc/chapters/getting-started.texinfo Wed Apr 9 09:16:31 2008 @@ -0,0 +1,3 @@ +@node Getting Started +@comment node-name, next, previous, up +@chapter Getting started with @value{claw}

Added: trunk/doc/chapters/i18n.texinfo ============================================================================== --- (empty file) +++ trunk/doc/chapters/i18n.texinfo Wed Apr 9 09:16:31 2008 @@ -0,0 +1,3 @@ +@node i18n +@comment node-name, next, previous, up +@chapter Internationalization of our application

Added: trunk/doc/chapters/lisplets.texinfo ============================================================================== --- (empty file) +++ trunk/doc/chapters/lisplets.texinfo Wed Apr 9 09:16:31 2008 @@ -0,0 +1,148 @@ +@node Lisplets +@comment node-name, next, previous, up +@chapter Lisplets + +Lisplets are @code{CLOS} objects that extend the functionalities of @code{CLAWSERVER}, dispatching requests that +come from this last one. + +Lisplets are so, the place where you put your web applications developed with @value{claw}. + +Lisplets return to the requesting user, pages, functions and resources mapped into them. + +Each Lisplet contains its own dispatch table and realm so that applications are not mixed together. + +@section Registering a lisplet into the server, crating a web application + +To create a web application you have to instantiate a @code{LISPLET} and then register it into the server. +@cartouche +@lisp +(defvar *clawserver* (make-instance 'clawserver :port 4242)) + +(defvar *test-lisplet* (make-instance 'lisplet :base-path "/test")) +(clawserver-register-lisplet *clawserver* *test-lisplet*) + +;;; you can now start the server +;;; with: +;;; (clawserver-start *clawserver*) +;;; and +;;; (clawserver-stop *clawserver*) +@end lisp +@end cartouche + +At this point you have defined a web application registered to the URL ``http://localhost:4242/test'' that +@value{claw} will be able to serve. + +All sessions and the authentication and authourization logic will be under the default realm ``claw'', +so if you register another lisplet into the server with the instruction: +@cartouche +@lisp +(defvar *test-lisplet2* (make-instance 'lisplet :base-path "/test2")) +(clawserver-register-lisplet *clawserver* *test-lisplet2*) +@end lisp +@end cartouche +any user session will be shared among @code{*test-lisplet*} and @code{*test-lisplet2*} and if a user is logged into +``/test'' application, he will be logged into ``/test2'' application too. + +To avoid this behaviour, you need to define a different realm for each of the two lisplet as the following example does: +@cartouche +@lisp +(defvar *clawserver* (make-instance 'clawserver :port 4242)) + +(defvar *test-lisplet* (make-instance 'lisplet :realm "test" + :base-path "/test")) +(clawserver-register-lisplet *clawserver* *test-lisplet*) + +(defvar *test-lisplet2* (make-instance 'lisplet :realm "test2" + :base-path "/test2")) +(clawserver-register-lisplet *clawserver* *test-lisplet2*) +@end lisp +@end cartouche + +The two lisplets will now have different realms, so a user session in @code{*test-lisplet*} will be +different from the one in @code{*test-lisplet2*}. So for the authentication and authorization module. +The same is for a user logged into the first application, he will not be automatically logged into the +other now. + +@section Adding resources into a @code{LISPLET} + +Lisplets alone don't do anything more then providing some error pages when something goes wrong. +To make a @code{LISPLET} a web application, you have to fill it with some application resource, and this +may be done in several ways. + +@subsection Adding files and folders to a @code{LISPLET} + +Suppose now you want to provide, thought your web application, a file present on jour hard disk, for example: +``/opt/webresources/images/matrix.jpg''. + +This is made very simple with the following instructions +@cartouche +@lisp +(lisplet-register-resource-location *test-lisplet* + #P"/opt/webresources/images/matrix.jpg" + "images/matrix.jpg" "image/jpeg") +@end lisp +@end cartouche + +The jpeg file will now be available when accessing ``http://localhost:4242/test/images/matrix.jpg''. +The last rgument specifies the mime-type, but it's optional. + +If you want to regiter an entire folder, the process is very similar +@cartouche +@lisp +(lisplet-register-resource-location *test-lisplet* + #P"/opt/webresources/images/" + "images2/") +@end lisp +@end cartouche + +Now you'll be able to access the same resource following the URL +``http://localhost:4242/test/images2/matrix.jpg'', easy, isn't it? + +@subsection Adding functions to a @code{LISPLET} + +Registering a function gives you more flexybility then registering a static resource as a file or a directory but the complexity +relies into the function that you want to register. + +For example, if you want to provide the same ``matrix.jpg'' file throught a function, you'll have to do something of the kind: +@cartouche +@lisp +(lisplet-register-function-location *test-lisplet* + #'(lambda () + (let ((path #P"/opt/webresources/images/matrix.jpg")) + (setf (content-type) (mime-type path)) + (with-open-file (in path :element-type 'flex:octet) + (let ((image-data (make-array (file-length in) + :element-type 'flex:octet))) + (read-sequence image-data in) + image-data)))) + "images/matrix2.jpg" ) +@end lisp +@end cartouche +Now the image will be availbe at the URL ``http://localhost:4242/test/images/matrix2.jpg''. + +The method @code{lisplet-register-function-location} accepts two optional keys: +@itemize @minus +@item +@code{:WELCOME-PAGE-P} that +will redirect you to the registered location when you'll access your application with the URL +``http://localhost:4242/test'' +@item +@code{:LOGIN-PAGE-P} that will redirect an unregistered user to the resource when he tries to access +a protected resource to perform the login with a form based authentication. +@end itemize + +@subsection Adding pages to a @code{LISPLET} + +Pages are one of the key objects of @value{claw}, since they are sophisticated collectors of web components. +Pages are described in the next chapter, meanwhile to register a page that is a @code{CLOS} object, the procedure +is very similar to when you register a function. +@cartouche +@lisp +(defclass empty-page (page) ()) +(lisplet-register-page-location *test-lisplet* 'empty-page "index.html" :welcome-page-p t) +@end lisp +@end cartouche + +This will provide an empty page at the URL ``http://localhost:4242/test/index.html'' and, since it +is defined as a welcome page when you'll access the URL ``http://localhost:4242/test'' you will redirected +to it.

Added: trunk/doc/chapters/pages.texinfo ============================================================================== --- (empty file) +++ trunk/doc/chapters/pages.texinfo Wed Apr 9 09:16:31 2008 @@ -0,0 +1,3 @@ +@node Pages +@comment node-name, next, previous, up +@chapter Web application pages

Added: trunk/doc/chapters/validation.texinfo ============================================================================== --- (empty file) +++ trunk/doc/chapters/validation.texinfo Wed Apr 9 09:16:31 2008 @@ -0,0 +1,3 @@ +@node validation +@comment node-name, next, previous, up +@chapter Input validation and field translations

Added: trunk/doc/chapters/writing-components.texinfo ============================================================================== --- (empty file) +++ trunk/doc/chapters/writing-components.texinfo Wed Apr 9 09:16:31 2008 @@ -0,0 +1,3 @@ +@node writing components +@comment node-name, next, previous, up +@chapter Creating a web application by writing reusable components