[claw-cvs] r29 - trunk/doc/chapters
achiumenti at common-lisp.net
achiumenti at common-lisp.net
Wed Apr 9 13:16:34 UTC 2008
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 @@
+ at node login access
+ at comment node-name, next, previous, up
+ at 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 @@
+ at node advanced components
+ at comment node-name, next, previous, up
+ at 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 @@
+ at node Advanced techniques
+ at comment node-name, next, previous, up
+ at 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 @@
+ at node forms
+ at comment node-name, next, previous, up
+ at 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 @@
+ at node Getting Started
+ at comment node-name, next, previous, up
+ at 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 @@
+ at node i18n
+ at comment node-name, next, previous, up
+ at 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 @@
+ at node Lisplets
+ at comment node-name, next, previous, up
+ at 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.
+
+ at 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.
+ at cartouche
+ at 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*)
+ at end lisp
+ at end cartouche
+
+At this point you have defined a web application registered to the URL ``http://localhost:4242/test'' that
+ at 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:
+ at cartouche
+ at lisp
+(defvar *test-lisplet2* (make-instance 'lisplet :base-path "/test2"))
+(clawserver-register-lisplet *clawserver* *test-lisplet2*)
+ at end lisp
+ at 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:
+ at cartouche
+ at 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*)
+ at end lisp
+ at 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.
+
+ at 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.
+
+ at 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
+ at cartouche
+ at lisp
+(lisplet-register-resource-location *test-lisplet*
+ #P"/opt/webresources/images/matrix.jpg"
+ "images/matrix.jpg" "image/jpeg")
+ at end lisp
+ at 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
+ at cartouche
+ at lisp
+(lisplet-register-resource-location *test-lisplet*
+ #P"/opt/webresources/images/"
+ "images2/")
+ at end lisp
+ at 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?
+
+ at 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:
+ at cartouche
+ at 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" )
+ at end lisp
+ at 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:
+ at itemize @minus
+ at item
+ at 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''
+ at item
+ at 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.
+ at end itemize
+
+ at 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.
+ at cartouche
+ at lisp
+(defclass empty-page (page) ())
+(lisplet-register-page-location *test-lisplet* 'empty-page "index.html" :welcome-page-p t)
+ at end lisp
+ at 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 @@
+ at node Pages
+ at comment node-name, next, previous, up
+ at 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 @@
+ at node validation
+ at comment node-name, next, previous, up
+ at 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 @@
+ at node writing components
+ at comment node-name, next, previous, up
+ at chapter Creating a web application by writing reusable components
More information about the Claw-cvs
mailing list