Artifact a67434fc337eefb53d79bdcefe3abcb2051e854e
File README part of check-in [5633e834f9] - add serve: to docs by crc on 2011-01-05 21:33:20. [annotate]
Casket
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
This is Casket, a minimalistic framework for building web applications using
Retro.
It provides basic parsing of the CGI PATH_INFO, execution of views, and some
templating functionality.
A Sample ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
count-vistors.rx:
include casket.rx
with casket'
variable visits
: /index
Content-type: text/html
visits ++ save
@visits "index.erx" withTemplate ;
&/index is /
[ ( -$ ) "/home/crc/apps/countVistors" ] is casket:root
[ ( -$ ) "http://rx-core.org/dev/countVisits" ] is casket:url
&dispatch is boot
templates/index.erx:
<html>
<head>
<title>Visitor Counter</title>
</head>
<body>
<p>This page has been viewed %d times.</p>
</body>
</html>
Explaination:
This is a pretty simple Casket application. It only handles one
view, /index, which increments a variable by one and displays a
barebones page with the total visit count to date.
The page is stored in a templates/ directory. It can contain the
standard escape sequences for formatting and display of values,
as well as a %u escape which is replaced by the URL of the Casket
application.
Note here that the visit counter is stored *in* the Retro image,
making this self contained.
If we wanted to expand this with a new view that did not update
the counter, we could simply add it like so:
( add to count-vistors.rx )
: /howmany
Content-type: text/html
@visits "howmany.erx" withTemplate ;
( new file: templates/howmany.erx )
<html>
<head>
<title>Visitor Counter</title>
</head>
<body>
<p>There have been %d visits to this application.</p>
</body>
</html>
At the end of the code we have a couple of lines of configuration. With
comments:
( set /index as the default view )
&/index is /
( set the physical path to the application root so Casket )
( can find templates and such )
[ ( -$ ) "/home/crc/apps/countVistors" ] is casket:root
( set the base URL of the application )
[ ( -$ ) "http://rx-core.org/dev/countVisits" ] is casket:url
( and have casket run on startup )
&dispatch is boot
API Reference ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
casket:root ( -$ ) Function returning path to application root
casket:url ( -$ ) Function returning application url
casket:path ( -$ ) Returns requested view (e.g., /index)
casket:options ( -$ ) Returns optional data following view)
casket:buffer ( -$ ) Internal: buffer
getRequest ( -$ ) Internal: Read the PATH_INFO environment variable
for use casket:path and casket:options
Content-type: ( "- ) Parse for a mime type to send to the browser
tputs ( $- ) Display a string with the template formatting
system
withTemplate ( $- ) Include and display a template file
/404 ( - ) Default 404 page
/ ( - ) Default index page
doBeforeDispatch ( - ) Hook for code that needs calling before running
any of the view functions
dispatch ( - ) Look at casket:path and invoke the desired view
or /404 if no handler is found
serve: ( "- ) Serve a file with a specific mime type
Deploying ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
This is what I do:
- Make a copy of the retro.py, renamed to the match the url desired.
e.g., I have a blog at http://rx-core.org/dev/corpse
There is a 'corpse' executable, which gets put in the cgi
directory corresponding to /dev/ on my server.
- Modify the imageFile variable in the copy to point to the physical
location of the image for your application
- Use a standard Retro VM to build and save an image with your code
and the Casket library loaded.
- Setup permissions on the files as necessary