chickadee » awful » define-page

Define an awful page.

path-matcher matches requested paths. It can be represented by three types:

string

a literal path. When the path matcher is a string, the handler procedure must be a thunk.

regex

a regular expression to match the requested path (regexes created by both regex egg and irregex unit are valid values). When the path matcher is a regular expression, the page handler procedure must be a one-argument procedure which will be given the requested path.

procedure

a one-argument procedure to match the requested path (feature introduced in awful 0.35). If the procedure matches the requested path, it should return a list to be applied to the page handler. When the path matcher is a procedure, the arity of the page handler procedure must match the length of the list returned by the path matcher. #f indicates that there was no match. Values which are not #f or a list will cause an invalid argument type error.

handler should return either a string, a no-argument procedure or a list (in case SXML mode is enabled -- SXML support has been introduced in awful 0.36). If it returns a string, it will be given as argument to (page-template), unless no-template is not false. If handler returns a procedure (feature introduced in awful 0.35), awful won't do anything besides evaluating the returned procedure. It can be useful, for example, to serve static files out of the web server document directory (see the examples in this section). If handler produces a list, awful or the particular page in question must be operating in SXML mode, which can be set via the enable-sxml parameter or via de use-sxml keywork parameter for define-page. The list produced by the handler will be given as argument to the procedure yield by the sxml->html parameter.

use-sxml (boolean): specifies whether awful should assume that the handler produces SXML code or strings. In case the handler produces SXML code, the parameter sxml->html yields the procedure used to generate HTML out of SXML.

method (a symbol or a list) indicates the HTTP method to be used (e.g., GET, POST, PUT). method can also be a list of methods. In this case, awful will define a page for each method of the list. Methods are case-insensitive. Pages that use different methods can use the same path. The default value is (GET HEAD) (prior to version 0.39, the default value was just GET).

The css, title, doctype, headers and charset keyword parameters have the same meaning as html-page (from the html-utils egg).

If no-ajax is #t, it means that the page won't use ajax, even if the enable-ajax parameter is #t.

If use-ajax is #t, it means that the page will be linked to the ajax library, even if the enable-ajax parameter is #f.

If no-template is #t, it means that no page template (see the page-template parameter) should be used.

If no-session is #t, it means that the page should not use session.

If no-db is #t, it means that the page should not use the database, even when database usage is activated by enable-db and db-credentials is not #f.

If no-javascript-compression is #t the JavaScript code for the page is not compressed, even when enable-javascript-compression is not #f.

vhost-root-path (a string or #f) is the root path of the virtual host the page definition is to be applied to. If vhost-root-path is set to a path, the page definition will only be valid for the virtual host whose root path is the given path.

If strict is truthy, awful will only match the requested path if it strictly matches the defined matchers. For convenience, awful sloppily considered requests for files and directories to be equivalent. For example, if a page was defined with a "/foo" matcher, a request for "/foo/" would be handled by "/foo"'s handler. That's not always desired. For example, consider this case:

 (define-page (irregex "/[^/]*") identity)

We want to specify that, e.g., requests for /foo should be handled, but requests for /foo/ should not be handled. However, since awful tries to find a handler by stripping the trailing slash, a request for /foo/ would actually be handled by the handler for (irregex "/[^/]*"), even if the regex specified that paths with a trailing slash should not match.

Examples:

(cond-expand
  (chicken-4
    (use awful
         srfi-1   ;; for filter-map
         srfi-13  ;; for string-prefix?
         irregex  ;; for irregex
         spiffy)) ;; for send-static-file
  (chicken-5
    (import (chicken irregex) ;; for irregex
            (chicken format)  ;; for sprintf
            (chicken string)) ;; for string-split
    (import awful
            srfi-1   ;; for filter-map
            srfi-13  ;; for string-prefix?
            spiffy)) ;; for send-static-file
  )

;;
;; Path matcher as a string
;;

;; http://host:port/foo => "bar"
(define-page "/foo"
  (lambda ()
    "bar"))


;;
;; Path matcher as a regular expression
;;

;; http://host:port/add/1/2/3 => 6
(define-page (irregex "/add/.*")
  (lambda (path)
    (let ((numbers (filter-map string->number (string-split path "/"))))
      `(,(apply + numbers)))))


;;
;; Path matchers as procedures
;;

(define (ticket-id path)
  (and (string-prefix? "/ticket/" path)
       (and-let* ((tokens (string-split path "/"))
                  (_ (not (null? (cdr tokens))))
                  (id (string->number (cadr tokens))))
         (and id (list id)))))


(define (ticket-reporter+severity path)
  (and (string-prefix? "/ticket/" path)
       (and-let* ((tokens (string-split path "/"))
                  (_ (> (length tokens) 2)))
         (list (cadr tokens)
               (caddr tokens)))))

;; http://host:port/ticket/4
(define-page ticket-reporter+severity
  (lambda (reporter severity)
    `(,(sprintf "Reporter=~a, severity=~a"
                reporter
                severity))))

;; http://host:port/ticket/4/5
(define-page ticket-id
  (lambda (id)
    `("This is ticket " ,id)))


;;
;; Page handler returning a procedure
;;

;; Serving a static file out of the web server documents directory
(define-page "/my-dot-emacs"
  (lambda ()
    (lambda ()
      (parameterize ((root-path (get-environment-variable "HOME")))
        (send-static-file ".emacs"))))
  no-template: #t)