sunet/scheme/httpd/surflets/surflets-structures.txt

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 "<head><title>My Page</title></head"))))

  MY-TITLE-HEAD takes one argument, the title:
  (define my-title-head-rul
  `(my-title-head . (lambda (trigger title)
                     (list "<head><title>" 
                           title
                           "</title></head"))))

*** SXML->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)