We have three basic layers of structures: -*- Outline -*-
* Overview
(a) Basic User surflets, simple-surflet-api
(b) Advanced User surflets/my-sxml, surflets/my-sessions,
surflets/my-input-fields, surflets/primitives
(c) Administrative User surflet-handler/admin, profiling
The fourth layer:
(d) Various surflets/outdaters, surflets/utilities
Finally, there is a HOWTO added, that describes how you can use your
own rules.
* (a) Basic User
** structures: (1) surflets
provides: . sending of html represented by surflet-sxml
. using special tags in its surflet-sxml:
url, plain-html, surflet-form
. input-fields: input-field-value,
input-field-binding, ...
. get-bindings, extract-bindings, ...
. make-address, make-annotated-address, ...
. returned-via?, case-returned-via, ...
. get-session-data, set-session-data!
surflets contains of several parts, that can
be loaded independently from each other.
** structures: (2) simple-surflet-api
provides: . PLT like generation of simple web pages:
. single-query, form-query, inform-page,
final-page
. make-password, make-number...
* (b) Advanced User
** structures: (1) surflets/my-sxml
provides: . generating and sending of own sxml,
see HOWTO below
. send-html-string/suspend...
. sxml-rules...
. sxml->string
. surflet-sxml-rules...
. surflet-sxml->low-level-sxml
** structures: (2) surflets/my-sessions
provides: . Everything needed to administrate your own
sessions and continuations.
(This represents the access to the sessions of
one surflet. However, you currently have
access to all sessions. This will be
restricted in the future.)
. my-session-id, my-continuation-id,
instance-session-id
. get-session, delete-session!
. get-continuation, delete-continuation!
. session-adjust-timeout!, adjust-timeout!
. session-alive?, session-surflet-name
. access to options: options-session-lifetime,
options-cache-surflets?
** structures: (3) surflets/my-input-fields
provides: . Access to the primitives of input-fields:
. Constructor, selector, mutators, predicate
** structures: (4) surflet-handler/primitives
provides: . Access to the primitives of the
surflet handler:
. send/suspend, ... that send surflet responses
. send-error (sending Webserver error message)
. make-surflet-response, ... status-code:
surflet responses with own status-code, own
content-type, own headers and own content
(string or list of strings)
. surflet-requests...
* (c) Administrative User
** structures: (1) surflet-handler/admin
provides: . Access to all internal structures of the
handler
. surflets: get-loaded-surflets, unload-surflet
. sessions: get-session, get-sessions,
session-data, instance-session-id,
adjust-timeout..., session-record selectors
. continuations: get-continuations,
delete-continuations!
. resume-urls: resume-url?, resume-url-ids...
. options: options-session-lifetime...
set-options...!
surflet-handler/admin is splitted in several
parts, that can be loaded independently from
each other.
** structures: (2) profiling
provides: . Access to memory usage of the whole scsh session
. profile-space, profile-results,
with-gnuplot-data-file, space-info-pair,
space-info-symbol...
* (d) Various
** structures: (1) surflets/outdaters
provides: . Data structure to prevent call for outdated
links. This is useful if in some places of your
session the user should not go back and recall
another continuation.
. make-outdater, if-outdated, show-outdated
** structures: (2) surflets/utilities
provides: . Various utilities that didn't fit in another
package but were too small for an own one.
. form-query-list: url-query->alist
. rev-append
. make-callback enables you to place a callback
below a link. If the user clicks the link, an
arbitrary function is called.
. generate-unique-name generates name from a
prefix that are highest probable unique with
this prefix. For example this is used to
generate the names of the input fields.
* HOWTO use your own conversion rules:
** (i) Create your own conversion rules:
(trigger [*preorder*] . function)
- TRIGGER is the symbol that trigger the rule
- FUNCTION will get the trigger and the rest of the list, that
triggered the rule as arguments. Thus, if you know, you will
only get (at least x) arguments, FUNCTION must accept (at
least) x+1 arguments. FUNCTION must return a list
containing only characters or strings or, recursively, lists
of this type. (Well, there may be others also, but this is
too advanced.)
- If *PREORDER* misses, the rules will be first applied to all
arguments, before the are passed to function.
*** Examples:
MY-HEAD will take no args and creates my heading:
(define my-head-rule
`(my-head . (lambda (trigger)
(list "My Page"
title
"STRING/INTERNAL
MY-ATTRIBUTED-HEAD takes attributes as well. As we don't want
to reformat this on our own, we use SXML->STRING/INTERNAL,
assuming that MY-RULES contains *all* the rules we use for
this sublist. As we do everything for the rest of the tree
ourselves, we use *preorder*:
(define my-attributed-head
`(my-attributed-head *preorder* .
,(lambda (trigger attributes title)
(sxml->string/internal `(head ,attributes (title ,title))
my-rules))))
** (ii) Create your own rule set.
A rule set is a list of conversion rules.
*** Example:
(define my-rules
(list default-rule
attribute-rule
text-rule
my-head-rule
my-title-head
my-attributed-head))
*** Note:
If you want to use SXML->STRING/INTERNAL with the same
rule set that entered the rule, you have to define them
either on top level with define or with letrec like
(letrec ((my-rules
(cons my-attributed-head-rule default-rules))
(my-attributed-head-rule
`(my-attributed-head *preorder* .
,(lambda (trigger attributes title)
(sxml->string/internal `(head ,attributes (title ,title))
my-rules)))))
my-rules)