(index ("enable-sxml" 0) ("sxml->html" 184) ("debug-file" 633) ("debug-db-query?" 952) ("debug-db-query-prefix" 1197) ("debug-resources" 1426) ("db-credentials" 1819) ("ajax-library" 2136) ("enable-ajax" 2416) ("ajax-namespace" 2874) ("ajax-invalid-session-message" 3051) ("enable-session" 3314) ("enable-session-cookie" 3483) ("session-cookie-name" 3783) ("session-cookie-setter" 3981) ("page-access-control" 4281) ("page-access-denied-message" 4548) ("valid-password?" 4838) ("page-doctype" 5105) ("page-css" 5440) ("page-charset" 5869) ("page-template" 6182) ("page-exception-message" 6803) ("main-page-path" 7135) ("app-root-path" 7293) ("login-page-path" 7914) ("awful-response-headers" 8248) ("web-repl-access-control" 8912) ("web-repl-access-denied-message" 9124) ("enable-web-repl-fancy-editor" 9361) ("web-repl-fancy-editor-base-uri" 9758) ("session-inspector-access-control" 10026) ("session-inspector-access-denied-message" 10265) ("enable-javascript-compression" 10529) ("javascript-compressor" 10797) ("javascript-position" 11254) ("literal-script/style?" 11571) ("http-request-variables" 11927) ("db-connection" 12137) ("page-javascript" 12454) ("sid" 12601) ("awful-apps" 12672) ("development-mode?" 12830) ("awful-version" 13054) ("include-javascript" 13158) ("add-javascript" 13350) ("add-css" 13652) ("debug" 13979) ("debug-pp" 14109) ("$session" 14233) ("$session-set!" 14441) ("link" 15000) ("form" 16010) ("define-login-trampoline" 16736) ("login-form" 17258) ("$" 18101) ("with-request-variables" 18519) ("$db" 18884) ("$db-row-obj" 20410) ("define-page" 21214) ("define-session-page" 28610) ("undefine-page" 29806) ("set-page-title!" 30158) ("html-page" 30715) ("ajax" 33269) ("periodical-ajax" 41158) ("ajax-link" 41766) ("redirect-to" 43162) ("add-request-handler-hook!" 44096) ("remove-request-handler-hook!" 44776) ("enable-web-repl" 44943) ("enable-session-inspector" 45921) ("load-apps" 46806) ("reload-apps" 46980) ("awful-start" 47189))
(def (sig (parameter "(enable-sxml [boolean])" (id enable-sxml))) (p "Deprecated.  Since version 1.0.0, this parameter has no effect.  It is going to be removed in future versions."))
(def (sig (parameter "(sxml->html [procedure])" (id sxml->html))) (p "The procedure used to transform SXML into HTML. The default value is:") (highlight scheme "(let ((rules `((literal *preorder* . ,(lambda (t b) b))\n               . ,universal-conversion-rules*)))\n  (lambda (sxml)\n    (with-output-to-string\n      (lambda ()\n        (SRV:send-reply (pre-post-order* sxml rules))))))") (p "This parameter has been introduced in awful 0.36."))
(def (sig (parameter "(debug-file [file path])" (id debug-file))) (p "If " (tt "#f") ", indicates that debugging should be disabled.  When set to a string, it should be the path to the file where the debug messages go (when " (tt "debug") " or " (tt "debug-pp") " is used.)") (p "The default value is " (tt "#f") "."))
(def (sig (parameter "(debug-db-query? [boolean])" (id debug-db-query?))) (p "When not " (tt "#f") ", all queries passed to " (tt "$db") " and to " (tt "$db-row-obj") " are printed to the debug file.") (p "The default value is " (tt "#f") "."))
(def (sig (parameter "(debug-db-query-prefix [string])" (id debug-db-query-prefix))) (p "Prefix to be used for queries debugging when " (tt "debug-db-query") " is not " (tt "#f") ".") (p "The default value is " (tt "\"\"") "."))
(def (sig (parameter "(debug-resources [boolean])" (id debug-resources))) (p "When " (tt "#t") ", enables debugging of awful's resources table (an alist mapping paths (or regexes) and vhost paths to their corresponding procedures to be executed on the server side upon request).  The debugging data is sent to the file pointed by " (tt "debug-file") ".  The default value is " (tt "#f") "."))
(def (sig (parameter "(db-credentials [boolean or list])" (id db-credentials))) (p "Credentials to be used to access the database (see the documentation for the egg corresponding to the database backend you selected.)  When " (tt "#f") ", no database access is performed.") (p "The default value is " (tt "#f") "."))
(def (sig (parameter "(ajax-library [string])" (id ajax-library))) (p "URL or path to the ajax library (currently only " (link "http://jquery.com" "jQuery") " is supported.)") (p "The default value is " (tt "\"http://ajax.googleapis.com/ajax/libs/jquery/1.8.2/jquery.min.js\"")))
(def (sig (parameter "(enable-ajax [boolean])" (id enable-ajax))) (p "When " (tt "#t") ", makes " (tt "define-page") " link the " (tt "ajax-library") " to the generated page.  Its effect is global, that is, once " (tt "enable-ajax") " is set to " (tt "#t") ", all pages defined via " (tt "define-page") " will be linked to the ajax library, unless when the " (tt "no-ajax") " keyword parameter is explicitly set.") (p "The default value is " (tt "#f") "."))
(def (sig (parameter "(ajax-namespace [string])" (id ajax-namespace))) (p "Name to be used as a namespace for ajax URL paths.") (p "The default value is " (tt "\"ajax\"") "."))
(def (sig (parameter "(ajax-invalid-session-message [string])" (id ajax-invalid-session-message))) (p "The message to be used when attempting the make an ajax call using an invalid session identifier.") (p "The default value is " (tt "\"Invalid session\"") "."))
(def (sig (parameter "(enable-session [boolean])" (id enable-session))) (p "When " (tt "#t") ", session support is enabled.") (p "The default value is " (tt "#f") "."))
(def (sig (parameter "(enable-session-cookie [boolean])" (id enable-session-cookie))) (p "When " (tt "#t") ", awful uses cookies to store the session identifier. Otherwise, the session identifier is passed as a value in the query string or in the request body. The default value is " (tt "#t") "."))
(def (sig (parameter "(session-cookie-name [string])" (id session-cookie-name))) (p "The name of the cookie for storing the session identifier.  The default value is " (tt "\"awful-cookie\"") "."))
(def (sig (parameter "session-cookie-setter" (id session-cookie-setter))) (p "A one-argument procedure (the sid) that is called when creating/refreshing the session.") (p "The default value is the following procedure:") (highlight scheme "(lambda (sid)\n  (set-cookie! (session-cookie-name) sid))"))
(def (sig (parameter "(page-access-control [procedure])" (id page-access-control))) (p "A one-argument (URL path of the current page) procedure which tells whether the access to the page is allowed or not.") (p "The default value is " (tt "(lambda (path) #t)") "."))
(def (sig (parameter "(page-access-denied-message [procedure])" (id page-access-denied-message))) (p "A one-argument (URL path of the current page) procedure which returns the access denied message in SXML.") (p "The default value is " (tt "(lambda (path) '(h3 \"Access denied.\"))") "."))
(def (sig (parameter "(valid-password? [procedure])" (id valid-password?))) (p "A two-argument (user and password) procedure which indicates whether the given password is valid for the given user.") (p "The default value is " (tt "(lambda (user password) #f)") "."))
(def (sig (parameter "(page-doctype [string])" (id page-doctype))) (p "The doctype (see the " (int-link "/egg/doctype" "doctype") " egg) to be applied to all pages defined by " (tt "define-page") ".  It can be overwritten by " (tt "define-page") "'s " (tt "doctype") " keyword parameter.") (p "The default value is " (tt "\"\"") "."))
(def (sig (parameter "(page-css [boolean or string])" (id page-css))) (p "The CSS file to be linked by all pages defined by " (tt "define-page") ".  It can be overwritten by " (tt "define-page") "'s " (tt "css") " keyword parameter. See " (int-link "/egg/html-utils" "html-utils") "'s " (tt "html-page") " procedure to know about the " (tt "css") " keyword parameter syntax.") (p "The default value is " (tt "#f") " (no CSS)."))
(def (sig (parameter "(page-charset [boolean or string])" (id page-charset))) (p "The page charset to be used by all pages defined by " (tt "define-page") ". It can be overwritten by " (tt "define-page") "'s " (tt "charset") " keyword parameter.") (p "The default value is " (tt "#f") " (no explicit charset)."))
(def (sig (parameter "(page-template [procedure])" (id page-template))) (p "A one-mandatory-argument procedure to be used by " (tt "define-page") " (unless " (tt "define-page") "'s " (tt "no-template") " keyword parameter is set to " (tt "#f") ") to generate HTML pages. Although the procedure yielded by this parameter takes only one mandatory argument, the following keyword arguments are passed:") (ul (li "css") (li "title") (li "doctype") (li "headers") (li "charset") (li "literal-style?")) (p "The default value is " (tt "html-page") " (see the " (int-link "/egg/html-utils" "html-utils") " egg documentation.)"))
(def (sig (parameter "(page-exception-message [procedure])" (id page-exception-message))) (p "A one-argument procedure to be used when an exception occurs while " (tt "define-page") " tries to evaluate its contents.") (p "The default value is " (tt "(lambda (exn) '(h3 \"An error has occurred while processing your request.\"))")))
(def (sig (parameter "(main-page-path [string])" (id main-page-path))) (p "The URL path to the app main page.") (p "The default value is " (tt "\"/\"") "."))
(def (sig (parameter "(app-root-path [string])" (id app-root-path))) (p "The base path to be used by the application.  All the pages defined by " (tt "define-page") " will use " (tt "app-root-path") " as the base directory.  For example, if " (tt "app-root-path") " is set to " (tt "\"/my-app\"") " and " (tt "\"my-page\"") " is used as first argument to " (tt "define-page") ", the page would be available at " (tt "http://<server>:<port>/my-app/my-page") ".") (p "The default value is " (tt "\"/\"") ".") (p (b "Important") ": this parameter is evaluated both at page definition time and page request handling time."))
(def (sig (parameter "(login-page-path [string])" (id login-page-path))) (p "The URL path for the login page.  When creating a login page, be sure to set the " (tt "no-session") " keyword parameter for " (tt "define-page") " to " (tt "#t") ", otherwise you'll get an endless loop.") (p "The default value is " (tt "\"/login\"") "."))
(def (sig (parameter "(awful-response-headers [alist])" (id awful-response-headers))) (p "An alist to specify the headers to be used in the response.  If the " (tt "content-length") " header is not provided, awful will calculate it automatically.") (p "Here's an example:") (highlight scheme "(cond-expand\n  (chicken-4\n    (use awful))\n  (chicken-5\n    (import awful)))\n\n(enable-sxml #t)\n\n(define (define-json path body)\n  (define-page path\n    (lambda ()\n      (awful-response-headers '((content-type \"application/json\")))\n      (body))\n    no-template: #t))\n\n\n(define-json (main-page-path)\n  (lambda ()\n    '(literal \"{\\\"a\\\": 1}\")))"))
(def (sig (parameter "(web-repl-access-control [procedure])" (id web-repl-access-control))) (p "A no-argument procedure to control access to the web REPL.") (p "The default value is " (tt "(lambda () #f)") "."))
(def (sig (parameter "(web-repl-access-denied-message [SXML])" (id web-repl-access-denied-message))) (p "Message to be printed when the access to the web REPL is denied.") (p "The default value is " (tt "'(h3 \"Access denied.\")") "."))
(def (sig (parameter "(enable-web-repl-fancy-editor [boolean])" (id enable-web-repl-fancy-editor))) (p "Indicates whether the web REPL should use a fancier editor for the input area.  The editor is based on " (link "http://codemirror.net" "codemirror") ".  Without the fancy editor, the input area is a simple HTML textarea.  The default value for " (tt "use-fancy-editor") " is " (tt "#t") "."))
(def (sig (parameter "(web-repl-fancy-editor-base-uri [string])" (id web-repl-fancy-editor-base-uri))) (p "The URI which indicates the fancy editor source files (JavaScript and CSS) location.  The default value is " (tt "http://parenteses.org/awful/codemirror") "."))
(def (sig (parameter "(session-inspector-access-control [procedure])" (id session-inspector-access-control))) (p "A no-argument procedure to control access to the session inspector.") (p "The default value is " (tt "(lambda () #f)") "."))
(def (sig (parameter "(session-inspector-access-denied-message [SXML])" (id session-inspector-access-denied-message))) (p "Message to be printed when the access to the session inspector is denied.") (p "The default value is " (tt "'(h3 \"Access denied.\")") "."))
(def (sig (parameter "(enable-javascript-compression [boolean])" (id enable-javascript-compression))) (p "Enable JavaScript compression support.  When enabled the compressor set by " (tt "javascript-compressor") " is used.") (p "The default value is " (tt "#f") "."))
(def (sig (parameter "(javascript-compressor [procedure])" (id javascript-compressor))) (p "A one-argument procedure which receives JavaScript code and returns it compressed.  Only used when " (tt "enable-javascript-compression") " is not " (tt "#f") ".") (p "The default value is the " (tt "identity") " procedure.") (p "A possible value for " (tt "javascript-compressor") " is " (tt "jsmin-string") " (see the " (int-link "/egg/jsmin" "jsmin") " egg.)"))
(def (sig (parameter "(javascript-position [symbol])" (id javascript-position))) (p "A symbol indicating the position of JavaScript code in the generated pages.  Possible values are " (tt "top") " (in the page headers) and " (tt "bottom") " (right before " (tt "</body>") ").  The default value is " (tt "top") "."))
(def (sig (parameter "(literal-script/style? [boolean])" (id literal-script/style?))) (p "When " (tt "#f") " (the default value), convert special HTML characters in JavaScript and in CSS code to their corresponding HTML entities.  When non-" (tt "#f") ", leave the special HTML characters untouched.") (p "This parameter was introduced in version 0.39."))
(def (sig (parameter "(http-request-variables)" (id http-request-variables))) (p "The per-request value returned by " (int-link "/egg/spiffy-request-vars" "spiffy-request-vars") "'s " (tt "request-vars") "."))
(def (sig (parameter "(db-connection)" (id db-connection))) (p "A per-request database connection object.  The connection is automatically opened and closed by awful in a per-request basis (unless databases are not being used or the " (tt "no-db") " keyword parameter for " (tt "define-page") " is " (tt "#t") ".)"))
(def (sig (parameter "(page-javascript)" (id page-javascript))) (p "JavaScript code to be added to the pages defined by " (tt "define-page") "."))
(def (sig (parameter "(sid)" (id sid))) (p "The session identifier."))
(def (sig (parameter "(awful-apps)" (id awful-apps))) (p "The list of awful applications, as given to the awful server when invoked from the command line."))
(def (sig (parameter "(development-mode?)" (id development-mode?))) (p "Indicates whether awful is running in development mode (see the " (tt "--development-mode") " command line option for the awful application server)."))
(def (sig (procedure "(awful-version)" (id awful-version))) (p "Return the awful version (a string)."))
(def (sig (procedure "(include-javascript . files)" (id include-javascript))) (p "A shortcut to " (tt "(<script> type: \"text/javascript\" src: file)") " for each file in " (tt "files") "."))
(def (sig (procedure "(add-javascript . code)" (id add-javascript))) (p "Add arbitrary JavaScript code to the pages defined by " (tt "define-page") " and " (tt "define-session-page") ".") (p "Note that the " (tt "literal-script/style?") " parameter may affect special characters in JavaScript code."))
(def (sig (procedure "(add-css . code)" (id add-css))) (p "Add arbitrary CSS code to the pages defined by " (tt "define-page") " and " (tt "define-session-page") ".") (p "Note that the " (tt "literal-script/style?") " parameter may affect special characters in CSS code.") (p "This procedure was introduced in version 0.39."))
(def (sig (procedure "(debug . args)" (id debug))) (p "Print " (tt "args") ", concatenated, to the file " (tt "debug-file") "."))
(def (sig (procedure "(debug-pp arg)" (id debug-pp))) (p "Pretty-print " (tt "arg") " to the file " (tt "debug-file") "."))
(def (sig (procedure "($session var #!optional default)" (id $session))) (p "Return the value of " (tt "var") " in the session (or " (tt "default") " if " (tt "var") " does not exist or is " (tt "#f") ")."))
(def (sig (procedure "($session-set! var #!optional val)" (id $session-set!))) (p "If " (tt "var") " is a quoted symbol, set the value of " (tt "var") " to " (tt "val") ". If " (tt "val") " is not provided, " (tt "var") " will have its value set to " (tt "#f") ".") (p (tt "var") " can be an alist mapping session variable names to their corresponding values.") (p "Examples:") (highlight scheme "($session-set! 'foo \"foo value\")\n\n($session-set! '((foo . \"foo value\")\n                 (bar . \"bar value\")\n                 (baz . \"baz value\")))"))
(def (sig (procedure "(link url text . rest)" (id link))) (p "Return a session-aware HTML code for a link, using the " (tt "<a>") " procedure from " (int-link "/egg/html-tags" "html-tags") ".") (p "The " (tt "rest") " arguments are the same as the ones for the " (tt "<a>") " procedure from " (int-link "/egg/html-tags" "html-tags") ", plus the following:") (dl (dt (tt "no-session")) (dd "a boolean.  If " (tt "#t") ", forces " (tt "link") " to ignore the session even when " (tt "enable-session") " is " (tt "#t") ".") (dt (tt "arguments")) (dd "an alist mapping variable names to their corresponding values, to be passed to uri-common's " (tt "form-urlencode") " procedure.") (dt (tt "separator")) (dd "the value to the " (tt "separator") " keyword argument to be passed to to uri-common's " (tt "form-urlencode") " procedure.")) (p "When " (tt "enable-session") " is " (tt "#t") ", " (tt "link") " automatically encodes the session identifier in the URI (unless " (tt "no-session") " is " (tt "#t") ")."))
(def (sig (procedure "(form contents . rest)" (id form))) (p "Return a session-aware HTML code for a form, using the " (tt "<form>") " procedure from " (int-link "/egg/html-tags" "html-tags") ".") (p "The " (tt "rest") " arguments are the same as the ones for the " (tt "<form>") " procedure from " (int-link "/egg/html-tags" "html-tags") ", plus " (tt "no-session") ", a boolean.  If " (tt "no-session") " is " (tt "#t") ", it forces " (tt "form") " to ignore the session even when " (tt "enable-session") " is " (tt "#t") ".") (p "When " (tt "enable-session") " is " (tt "#t") ", " (tt "form") " automatically generates a hidden input field to pass the session identifier (unless " (tt "no-session") " is " (tt "#t") ")."))
(def (sig (procedure "(define-login-trampoline path #!key vhost-root-path hook)" (id define-login-trampoline))) (p "Define a trampoline -- an intermediate page accessed when redirecting from the login page to the main page.") (p (tt "vhost-root-path") " is the path to the virtual host the trampoline will be defined for.") (p (tt "hook") " is a one-argument procedure which receives the given user. It is called right before the redirection to the attempted path (if any was attempted) or " (tt "(main-page-path)") "."))
(def (sig (procedure "(login-form #!key (user-label \"User: \") (password-label \"Password: \") (submit-label \"Submit\") (refill-user #t) (trampoline-path \"/login-trampoline\"))" (id login-form))) (p "Return a user/password login form (e.g., for using in authentication pages).") (p "When the " (tt "refill-user") " is " (tt "#t") ", the User field is refilled with the value from the " (tt "user") " query string value when either the session or the password is invalid.") (p "The " (tt "user-label") ", " (tt "password-label") " and " (tt "submit-label") " keyword parameters are labels to be used for the user, password and submit form widgets, respectively.") (p (tt "trampoline-path") " is a string that specify the path the form will be submitted to.  It must match the path given as argument to " (tt "define-login-trampoline") "."))
(def (sig (procedure "($ var #!optional default/converter)" (id $))) (p "Return the HTTP request value for the given variable " (tt "var") ".  The variable is looked for in both the query string (GET method) and request body (e.g., POST method).  See the documentation for the procedure returned by " (int-link "/eggref/4/spiffy-request-vars" "spiffy-request-vars") "'s " (tt "request-vars") " for further details."))
(def (sig (syntax "(with-request-variables (var1 var2 ... varn) expression1 ...)" (id with-request-variables))) (p "A wrapper around " (int-link "/egg/spiffy-request-vars" "spiffy-request-vars") "'s " (tt "with-request-vars*") ".") (p "All the " (int-link "/egg/spiffy-request-vars" "spiffy-request-vars") "'s converter procedures are exported, for convenience."))
(def (sig (procedure "($db q #!key (default '()) values)" (id $db))) (p "Execute the given query (" (tt "q") ") on the database and return the result as a list of lists or " (tt "default") " if the result set is empty.") (p "The " (tt "values") " keyword parameter (a list) is a list of values to replace the placeholders in the query.") (p "Example:") (highlight scheme "($db \"insert into foo (bar, baz) values (?, ?)\" values: '(\"bar-val\" \"baz-val\"))") (p (i "Note") ": up to version 0.40.0, " (tt "$db") " returned " (tt "#f") " when queries returned empty set of results.  Starting from version 0.41.0, " (tt "$db") " returns " (tt "'()") " queries return empty set of results.") (p "If you use the " (int-link "/egg/awful-ssql" "awful-ssql") " egg, you can give " (tt "$db") " the query as a SSQL expression.  See the documentation for " (int-link "/egg/awful-ssql" "awful-ssql") " for more details.  Support for SSQL has been introduced in awful version 0.40.0.") (p "Note that " (tt "$db") " is supposed to be used in the context of request handlers (i.e., in the body of a lambda bound to a uri path by " (tt "define-page") ").") (p "If you want to use " (tt "$db") " out of the context of request handlers, you'll have to manage database connections yourself.  Basically, you have to parameterize " (tt "db-connection") " with the actual connection object.  Example:") (highlight scheme "(parameterize ((db-connection (open-database (db-credentials))))\n  ($db the-query)\n  (close-database (db-connection)))"))
(def (sig (procedure "($db-row-obj q)" (id $db-row-obj))) (p "Execute the given query " (tt "q") " on the database and return an one-argument procedure which takes as argument the name of the database field to get the value.") (p "Example:") (highlight scheme "(let ((& ($db-row-obj \"select full_name, phone from users where user_id=1\")))\n  (<p> \"Full name: \" (& 'full_name))\n  (<p> \"Phone: \" (& 'phone)))") (p (i "Warning") ": currently " (tt "$db-row-obj") " is only implemented for PostgreSQL databases.") (p "If you use the " (int-link "/egg/awful-ssql" "awful-ssql") " egg, you can give " (tt "$db") " the query as a SSQL expression.  See the documentation for " (int-link "/egg/awful-ssql" "awful-ssql") " for more details.  Support for SSQL has been introduced in awful version 0.40.0."))
(def (sig (procedure "(define-page path-matcher handler #!key css title doctype headers charset no-ajax use-ajax no-template no-session no-db no-javascript-compression method use-sxml vhost-root-path strict)" (id define-page))) (p "Define an awful page.") (p (tt "path-matcher") " matches requested paths.  It can be represented by three types:") (dl (dt "string") (dd "a literal path. When the path matcher is a string, the handler procedure must be a thunk.") (dt "regex") (dd "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.") (dt "procedure") (dd "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. " (tt "#f") " indicates that there was no match.  Values which are not " (tt "#f") " or a list will cause an invalid argument type error.")) (p (tt "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 " (tt "(page-template)") ", unless " (tt "no-template") " is not false. If " (tt "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 " (tt "handler") " produces a list, awful or the particular page in question must be operating in SXML mode, which can be set via the " (tt "enable-sxml") " parameter or via de " (tt "use-sxml") " keywork parameter for " (tt "define-page") ".  The list produced by the handler will be given as argument to the procedure yield by the " (tt "sxml->html") " parameter.") (p (tt "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 " (tt "sxml->html") " yields the procedure used to generate HTML out of SXML.") (p (tt "method") " (a symbol or a list) indicates the HTTP method to be used (e.g., " (tt "GET") ", " (tt "POST") ", " (tt "PUT") ").  " (tt "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 " (tt "(GET HEAD)") " (prior to version 0.39, the default value was just " (tt "GET") ").") (p "The " (tt "css") ", " (tt "title") ", " (tt "doctype") ", " (tt "headers") " and " (tt "charset") " keyword parameters have the same meaning as " (tt "html-page") " (from the " (int-link "/egg/html-utils" "html-utils") " egg).") (p "If " (tt "no-ajax") " is " (tt "#t") ", it means that the page won't use ajax, even if the " (tt "enable-ajax") " parameter is " (tt "#t") ".") (p "If " (tt "use-ajax") " is " (tt "#t") ", it means that the page will be linked to the ajax library, even if the " (tt "enable-ajax") " parameter is " (tt "#f") ".") (p "If " (tt "no-template") " is " (tt "#t") ", it means that no page template (see the " (tt "page-template") " parameter) should be used.") (p "If " (tt "no-session") " is " (tt "#t") ", it means that the page should not use session.") (p "If " (tt "no-db") " is " (tt "#t") ", it means that the page should not use the database, even when database usage is activated by " (tt "enable-db") " and " (tt "db-credentials") " is not " (tt "#f") ".") (p "If " (tt "no-javascript-compression") " is " (tt "#t") " the JavaScript code for the page is not compressed, even when " (tt "enable-javascript-compression") " is not " (tt "#f") ".") (p (tt "vhost-root-path") " (a string or " (tt "#f") ") is the root path of the virtual host the page definition is to be applied to.  If " (tt "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.") (p "If " (tt "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 " (tt "\"/foo\"") " matcher, a request for " (tt "\"/foo/\"") " would be handled by " (tt "\"/foo\"") "'s handler.  That's not always desired.  For example, consider this case:") (pre " (define-page (irregex \"/[^/]*\") identity)") (p "We want to specify that, e.g., requests for " (tt "/foo") " should be handled, but requests for " (tt "/foo/") " should " (i "not") " be handled.  However, since awful tries to find a handler by stripping the trailing slash, a request for " (tt "/foo/") " would actually be handled by the handler for " (tt "(irregex \"/[^/]*\")") ", even if the regex specified that paths with a trailing slash should not match.") (p "Examples:") (highlight scheme "(cond-expand\n  (chicken-4\n    (use awful\n         srfi-1   ;; for filter-map\n         srfi-13  ;; for string-prefix?\n         irregex  ;; for irregex\n         spiffy)) ;; for send-static-file\n  (chicken-5\n    (import (chicken irregex) ;; for irregex\n            (chicken format)  ;; for sprintf\n            (chicken string)) ;; for string-split\n    (import awful\n            srfi-1   ;; for filter-map\n            srfi-13  ;; for string-prefix?\n            spiffy)) ;; for send-static-file\n  )\n\n;;\n;; Path matcher as a string\n;;\n\n;; http://host:port/foo => \"bar\"\n(define-page \"/foo\"\n  (lambda ()\n    \"bar\"))\n\n\n;;\n;; Path matcher as a regular expression\n;;\n\n;; http://host:port/add/1/2/3 => 6\n(define-page (irregex \"/add/.*\")\n  (lambda (path)\n    (let ((numbers (filter-map string->number (string-split path \"/\"))))\n      `(,(apply + numbers)))))\n\n\n;;\n;; Path matchers as procedures\n;;\n\n(define (ticket-id path)\n  (and (string-prefix? \"/ticket/\" path)\n       (and-let* ((tokens (string-split path \"/\"))\n                  (_ (not (null? (cdr tokens))))\n                  (id (string->number (cadr tokens))))\n         (and id (list id)))))\n\n\n(define (ticket-reporter+severity path)\n  (and (string-prefix? \"/ticket/\" path)\n       (and-let* ((tokens (string-split path \"/\"))\n                  (_ (> (length tokens) 2)))\n         (list (cadr tokens)\n               (caddr tokens)))))\n\n;; http://host:port/ticket/4\n(define-page ticket-reporter+severity\n  (lambda (reporter severity)\n    `(,(sprintf \"Reporter=~a, severity=~a\"\n                reporter\n                severity))))\n\n;; http://host:port/ticket/4/5\n(define-page ticket-id\n  (lambda (id)\n    `(\"This is ticket \" ,id)))\n\n\n;;\n;; Page handler returning a procedure\n;;\n\n;; Serving a static file out of the web server documents directory\n(define-page \"/my-dot-emacs\"\n  (lambda ()\n    (lambda ()\n      (parameterize ((root-path (get-environment-variable \"HOME\")))\n        (send-static-file \".emacs\"))))\n  no-template: #t)"))
(def (sig (procedure "(define-session-page path-matcher handlerr . rest)" (id define-session-page))) (p "Define a session-aware page.  When the page is accessed and a corresponding session does not exist, it is created.  If the session already exists and is not valid, it is recreated.  If the session already exists and is valid, then it is refreshed.") (p "The " (tt "rest") " parameters are the same as for " (tt "define-page") ".") (p "Here's an example (the " (link "http://www.paulgraham.com/arcchallenge.html" "arc challenge") "):") (highlight scheme "(cond-expand\n  (chicken-4\n    (use awful))\n  (chicken-5\n    (import awful)))\n\n(define-session-page \"said\"\n  (lambda ()\n    (with-request-variables (said)\n      (cond (said\n             ($session-set! 'said said)\n             `(,(link \"said\" \"click here\")))\n            (($session 'said)\n             => (lambda (said)\n                  `(\"You said: \" ,said)))\n            (else `(,(form '((input (@ (type \"text\") (name \"said\")))\n                             (input (@ (type \"submit\"))))\n                           action: \"said\"\n                           method: 'post))))))\n  method: '(GET POST))"))
(def (sig (procedure "(undefine-page path #!optional vhost-root-path)" (id undefine-page))) (p "Undefine a page whose path is " (tt "path") " (a string or a regular expression object).") (p "The optional parameter " (tt "vhost-root-path") " is the path of virtual host where the page is to be undefined.  If omitted, " (tt "(root-path)") " is used."))
(def (sig (procedure "(set-page-title! title)" (id set-page-title!))) (p "Set the title for the requested page.  This procedure is useful to set the page title dynamically from the page handler (instead of statically, via " (tt "define-page") "'s " (tt "title") " keyword parameter).") (p "This procedure has been introduced in awful 0.35.") (p "Example:") (highlight scheme "(cond-expand\n  (chicken-4\n    (use awful))\n  (chicken-5\n    (import awful)))\n\n(define-page (main-page-path)\n  (lambda ()\n    (set-page-title! \"a title\")\n    \"Hi!\"))"))
(def (sig (procedure "(html-page contents #!key css title doctype headers charset content-type literal-style? (html-attribs '()) (body-attribs '()))" (id html-page))) (p "Generates an SXML page containing " (tt "contents") " (SXML).  The following keywords arguments may be used to customize the page:") (ul (li (tt "headers") ": an SXML form containing additional headers to be inserted in the section delimited by the " (tt "<head>") " tag. Default = " (tt "#f") ".") (li (tt "title") ": the title for the page (to be used in the " (tt "<title>") " tag). Default = " (tt "#f") ".") (li (tt "css") ": may be either a path to a Cascading Style Sheet file, to be linked from the generated page (the default value is " (tt "#f") ", so no CSS is used) or a list of paths to CSS files. If a list of paths is used, the elements which are also lists are read and inlined into the generated page. Example: " (tt "css: '(\"css1.css\" (\"css2.css\"))") ". In the example, " (tt "css1.css") " would be linked from the generated page (using the link tag) and " (tt "css2.css") " would be inlined into the generated page (e.g., " (tt "html-page") " would read the " (tt "css2.css") " file and inline its contents in the HTML code).") (li (tt "doctype") ": specifies the document type of the generated page. The default value is " (tt "#f") ". The possible values are the ones available from the " (int-link "doctype") " egg.") (li (tt "charset") ": specifies the default charset to be used in the corresponding meta tag of the document. The default value is " (tt "\"UTF-8\"") " (only when " (tt "content-type") " is provided).") (li (tt "literal-style?") ": if " (tt "#f") ", convert special characters in style code (CSS) to theyr equivalent HTML entities.  If non-" (tt "#f") ", insert them verbatim.") (li (tt "content-type") " and " (tt "charset") " are used together for the " (tt "<meta http-equiv ...>") " specification.: " (tt "charset") "'s default value is " (tt "\"UTF-8\"") " and " (tt "content-type") "'s default value is " (tt "\"application/xhtml+xml\"") ".") (li (tt "html-attribs") ": attributes to the " (tt "html") " tag. The format is a list of lists " (tt "(<attribute> <value>)") " (" (tt "<attribute>") " is a symbol).  Example: " (tt "(html-page \"foo\" html-attribs: '((lang \"us\")))") ".") (li (tt "body-attribs") ": attributes to the " (tt "body") " tag. The format is a list of lists " (tt "(<attribute> <value>)") " (" (tt "<attribute>") " is a symbol).  Example: " (tt "(html-page \"foo\" body-attribs: '((bgcolor \"red\")))") ".")))
(def (sig (procedure "(ajax path selector event proc #!key target (action 'html) (method 'POST) (arguments '()) success no-session no-db vhost-root-path live on prelude update-targets cache error-handler use-sxml strict)" (id ajax))) (p "Generate JavaScript code to be added to the page defined by " (tt "define-page") ".  Return the generated JavaScript code. Unless " (tt "no-page-javascript") " is a truthy value, the JavaScript code will be added to the page in which case the returned JavaScript code is usually not useful and can be discarded.") (p (tt "path") " is the URL path (a string) of the server side handler. This path is placed under the " (tt "(app-root-path)/(ajax-namespace)") " path. So, if your " (tt "app-root-path") " is " (tt "\"my-app\"") ", your " (tt "ajax-namespace") " is " (tt "\"ajax\"") " and you use " (tt "\"do-something\"") " as the first argument to " (tt "ajax") ", the URL for the server side handler would be " (tt "\"/my-app/ajax/do-something\"") ".") (p (tt "selector") " is the selector for the DOM element to be observed.  If it is a quoted symbol, awful generates a jQuery selector by DOM id (e.g., " (tt "'my-selector") " generates " (tt "\"#my-selector\"") ").  If it is a string, awful uses it as-is to generate the jQuery selector (e.g., " (tt "\"input[name^=omg]\"") " generates " (tt "\"input[name^=omg]\"") ").") (p (tt "event") " (a quoted symbol or a list) is the event(s) to be observed. If it is a quoted symbol (e.g., " (tt "'click") "), only this event will be bound.  If " (tt "event") " is a list of events, all the events from the list will be bound.") (p (tt "proc") " is a no-argument procedure to be executed on the server side.") (p "The " (tt "target") " keyword parameter is the id of the DOM element to be affected by the result of " (tt "proc") ".") (p "The " (tt "method") " (a quoted symbol, usually " (tt "'GET") " or " (tt "'POST") ") keyword parameter is the HTTP method to be used by the ajax request.") (p "The " (tt "arguments") " keyword parameter is an alist mapping request variables (symbols) to their values (strings).  " (tt "ajax") " uses these arguments to assembly the query string or the request body to send to the server when performing the ajax request.") (p "If " (tt "use-sxml") " is " (tt "#t") ", it specifies that the ajax handler produces SXML code instead of strings.") (p "Example:") (highlight scheme "arguments: '((var1 . \"$('#var1').val()\")\n             (var2 . \"$('#var2').val()\"))") (p "If the " (tt "no-session") " keyword parameter is " (tt "#t") ", it means that no session should be considered (" (tt "ajax") " implicit sends the session identifier when " (tt "no-session") " is " (tt "#f") ").") (p "If the " (tt "no-db") " keyword parameter is " (tt "#t") ", it means that the should be no attempt to connect the database, even when database usage is activated by " (tt "enable-db") " and " (tt "db-credentials") " is not " (tt "#f") ".") (p "The " (tt "vhost-root-path") " keyword parameter (a string) is the vhost root path.  It is useful for explicitly separate pages defined using the same path (see " (tt "define-page") ") but for different vhosts.") (p "The " (tt "on") " keyword parameter (boolean) indicates whether ajax should use jQuery's " (tt "on") " method (see " (link "http://api.jquery.com/on/") ").  If " (tt "on") " gets bound to " (tt "#t") ", awful will generate code to start delegating events from the " (tt "document") " DOM element.  If " (tt "on") " gets bound to a symbol, awful will generate code to start delegating events from DOM element whose id is the given symbol.  If " (tt "on") " gets bound to a string, awful will generate code to start delegating events from DOM element which matches the given string representing a selector. The " (tt "on") " keyword parameter was introduced in awful 0.39.2.") (p "The " (tt "live") " keyword parameter (boolean) indicates whether ajax should use jQuery's " (tt "live") " method (see " (link "http://api.jquery.com/live/") "). Note that the " (tt "live") " method was deprecated in jQuery 1.7 and removed in version 1.9.  If you are using a more recent version of jQuery, see the " (tt "on") " keyword parameter for " (tt "ajax") " (introduced in awful 0.39.2).") (p "The " (tt "prelude") " keyword parameter (string) is an arbitrary piece of JavaScript code to be placed right before the ajax request.") (p "The " (tt "update-targets") " keyword parameter a boolean indicating whether multiple targets should be updated upon ajax response.  When " (tt "update-targets") " is used, the procedure " (tt "proc") " used as argument to " (tt "ajax") " should yield an alist as result.  The alist maps DOM elements identifiers to their corresponding values.") (p "Here's an example:") (highlight scheme "(cond-expand\n  (chicken-4\n    (use awful))\n  (chicken-5\n    (import awful)))\n\n(define-page (main-page-path)\n  (lambda ()\n\n    (ajax \"foo\" 'foo 'click\n          (lambda ()\n            '((a . 1) (b . 2) (c . 3)))\n          update-targets: #t)\n\n    `(,(link \"#\" \"Click me\" id: \"foo\")\n      (div (@ (id \"a\")))\n      (div (@ (id \"b\")))\n      (div (@ (id \"c\")))))\n  use-ajax: #t)") (p "The " (tt "success") " keyword parameter (string) can be any arbitrary JavaScript code to be executed on the successful ajax request.  The JavaScript code can assume that a variable " (tt "response") " is bound and contains the request resulting data.  Here's an example:") (highlight scheme "(cond-expand\n  (chicken-4\n    (use awful))\n  (chicken-5\n    (import awful)))\n\n(define-page (main-page-path)\n  (lambda ()\n\n    (ajax \"foo\" 'foo \"click\"\n          (lambda ()\n            \"hey\")\n          success: \"$('#bar').html(response + ' you!')\")\n\n    `(,(link \"#\" \"Click me\" id: \"foo\")\n      (div (@ (id \"bar\")))))\n  use-ajax: #t)") (p "When " (tt "success") " is used together with " (tt "target") " or " (tt "update-targets") ", the success code runs before the update code.  This allows to update parts of the dom that cannot be identified by id (e.g., attributes), post-process the response before targets are updated, or skip the update altogether by performing a return from the callback function.  Here's an example:") (highlight scheme "(cond-expand\n  (chicken-4\n    (use awful))\n  (chicken-5\n    (import awful)))\n\n(define-page (main-page-path)\n  (lambda ()\n\n    (ajax \"foo\" 'foo 'click\n          (lambda ()\n            '((lang . \"en\") (a . 1) (b . 2) (c . 3)))\n          update-targets: #t\n          success: \"document.documentElement.lang = response['lang'];\")\n\n    `(,(link \"#\" \"Click me\" id: \"foo\")\n      (span (@ (id \"lang\") (display \"none\")))\n      (div (@ (id \"a\")))\n      (div (@ (id \"b\")))\n      (div (@ (id \"c\")))))\n  use-ajax: #t)") (p "The " (tt "cache") " keyword parameter (boolean), if set to " (tt "#f") ", it will force requested pages not to be cached by the browser.  The default value is not set, leaving it to be set by jQuery. See " (link "http://api.jquery.com/jQuery.ajax/" "jQuery's documentation") " for further details.") (p "The " (tt "error-handler") " keyword parameter expects a JavaScript callback to be used as the error handler for the Ajax request.  See the " (tt "error") " attribute for the " (tt "settings") " object given as argument to jQuery.ajax (" (link "http://api.jquery.com/jQuery.ajax/" "http://api.jquery.com/jQuery.ajax/") ").") (p "The " (tt "no-page-javascript") " keyword parameter is a boolean that determines whether the generated JavaScript code is automatically added to the page or not.  Defaults to " (tt "#f") ". This parameter may be useful if you want more control of where or when the generated JavaScript code gets added to the page or even if it gets added at all.") (p "The " (tt "ajax") " procedure is session, HTTP request and database -aware."))
(def (sig (procedure "(periodical-ajax path interval proc #!key target (action 'html) (method 'POST) (arguments '()) success no-session no-db vhost-root-path live on prelude update-targets error-handler use-sxml strict)" (id periodical-ajax))) (p "Periodically execute " (tt "proc") " on the server side, using " (tt "(app-root-path)/(ajax-namespace)/path") " as the URL path for the server side handler.") (p (tt "interval") " (a number) is the interval between consecutive executions of " (tt "proc") ", in milliseconds.") (p "The meaning of the keyword parameters is the same as for " (tt "ajax") "'s."))
(def (sig (procedure "(ajax-link path id text proc #!key target (action 'html) (method 'POST) (arguments '()) success no-session no-db (event 'click) vhost-root-path live on class hreflang type rel rev charset coords shape accesskey tabindex a-target prelude update-targets error-handler use-sxml strict)" (id ajax-link))) (p "A shortcut to") (highlight scheme "(begin\n  (ajax path id 'click proc ...)\n  (<a> href: \"#\" [...other <a> keyword parameters...] id: id text))") (p "The meaning of the " (tt "target") ", " (tt "action") ", " (tt "method") ", " (tt "arguments") ", " (tt "success") ", " (tt "no-session") ", " (tt "no-db") ", " (tt "event") ", " (tt "vhost-root-path") ", " (tt "update-targets") " " (tt "live") " and " (tt "on") " keyword parameters is the same as for " (tt "ajax") "'s.") (p "The meaning of the " (tt "class") ", " (tt "hreflang") ", " (tt "type") ", " (tt "rel") ", " (tt "rev") ", " (tt "charset") ", " (tt "coords") ", " (tt "shape") ", " (tt "accesskey") ", " (tt "tabindex") " and " (tt "a-target") " are the same as for " (int-link "/egg/html-tags" "html-tags") "' " (tt "<a>") " procedure (except that " (tt "a-target") " is " (tt "<a>") "'s " (tt "target") ", since " (tt "ajax") " uses the " (tt "target") " keyword parameter).") (p "The " (tt "event") " keyword parameter syntax is the same for " (tt "ajax") "'s " (tt "event") " mandatory parameter."))
(def (sig (procedure "(redirect-to uri)" (id redirect-to))) (p "Perform an HTTP redirection (code 302) to the given " (tt "uri") " (either a string or a " (int-link "/eggref/4/uri-common" "uri-common") " URI object).  To be used from " (tt "define-page") " handler.  Example:") (highlight scheme "(cond-expand\n  (chicken-4\n    (use awful))\n  (chicken-5\n    (import awful)))\n\n;; / -> /foo\n(define-page \"/\"\n  (lambda ()\n    (redirect-to \"/foo\")))\n\n(define-page \"/foo\"\n  (lambda ()\n    \"foo\"))") (p "The example above shows a redirection from " (tt "/") " to " (tt "/foo") ". Redirections can also be performed when the origin path is a regular expression:") (highlight scheme "(cond-expand\n  (chicken-4\n    (use awful))\n  (chicken-5\n    (import awful)))\n\n;; /bar.* -> /foo\n(define-page (regexp \"/bar.*\")\n  (lambda (_)\n    (redirect-to \"/foo\")))\n\n(define-page \"/foo\"\n  (lambda ()\n    \"foo\"))"))
(def (sig (procedure "(add-request-handler-hook! hook-id proc)" (id add-request-handler-hook!))) (p "Adds a hook identified by " (tt "id") " (can be used to remove the hook if necessary). " (tt "proc") " is a two-argument procedure which receives the requested path and its handler.") (p "Here's a simple usage example:") (highlight scheme "(add-request-handler-hook!\n 'foo\n (lambda (path handler)\n   (when (string-prefix? \"/foo\" path)\n     (parameterize\n         ((debug-file \"/tmp/foo-debug\")\n          (enable-ajax #t))\n       (handler))))") (p "By using request handlers, you can parameterize parameter values in a way that they don't affect other applications."))
(def (sig (procedure "(remove-request-handler-hook! hook-id)" (id remove-request-handler-hook!))) (p "Removes the request handler hook identified by " (tt "id") "."))
(def (sig (procedure "(enable-web-repl path #!key css title)" (id enable-web-repl))) (p "Enable the web REPL.  " (tt "path") " is the URL path to the web REPL.") (p "The keyword parameter " (tt "css") " is the CSS to be used the the web REPL page (see the documentation for " (tt "html-page") ", from the " (int-link "/egg/html-utils" "html-utils") " egg, for the " (tt "css") " keyword parameter.)") (p "The keyword parameter " (tt "title") " (a string) is the title for the web REPL page (see the documentation for " (tt "html-page") ", from the " (int-link "/egg/html-utils" "html-utils") " egg, for the " (tt "title") " keyword parameter.)") (p "The web REPL is automatically enabled by the awful application server when the " (tt "--development-mode") " is provided (available from " (tt "/web-repl") ").  By default, the fancy editor is used, but can be disabled with the " (tt "--disable-web-repl-fancy-editor") " command line option for the awful application server."))
(def (sig (procedure "(enable-session-inspector path #!key css title)" (id enable-session-inspector))) (p "Enable the session inspector.  " (tt "path") " is the URL path to the session inspector.") (p "The keyword parameter " (tt "css") " is the CSS to be used the the session inspector page (see the documentation for " (tt "html-page") ", from the " (int-link "/egg/html-utils" "html-utils") " egg, for the " (tt "css") " keyword parameter.)") (p "The keyword parameter " (tt "title") " (a string) is the title for the session inspector page (see the documentation for " (tt "html-page") ", from the " (int-link "/egg/html-utils" "html-utils") " egg, for the " (tt "title") " keyword parameter.)") (p "The session inspector is automatically enabled by the awful application server when the " (tt "--development-mode") " is provided (available from " (tt "/session-inspector") ")."))
(def (sig (procedure "(load-apps apps)" (id load-apps))) (p "Load the given applications (" (tt "apps") " - a list) (using " (int-link "/man/4/Unit eval#load" "load") ")."))
(def (sig (procedure "(reload-apps apps)" (id reload-apps))) (p "The same as " (tt "load-apps") " but also reseting the resources table (the thing that maps URIs to procedures) before loading applications."))
(def (sig (procedure "(awful-start thunk #!key dev-mode? port ip-address (use-fancy-web-repl? #t) privileged-code))" (id awful-start))) (p "Starts awful.  This procedure is only useful for standalone applications which intent to embed awful.  For example, the awful application server (the awful command line tool) uses it.") (p "This procedure does all the listening, switching user/group and entering the accept loop dance.") (p (tt "thunk") " is a procedure to be executed upon starting awful.  It can be Scheme code just like any other that can be loaded as an awful application.") (p (tt "dev-mode?") " (boolean) indicates whether awful should run in development mode.") (p (tt "port") " (integer) indicates to port to bind to.") (p (tt "ip-address") " (string) indicates the IP address to bind to.") (p (tt "use-fancy-web-repl?") " (boolean): indicates whether the web REPL should use the fancy editor.  The default value is " (tt "#t") " (since awful 0.40.0 -- before that it was " (tt "#f") ")") (p (tt "privileged-code") " (procedure): a thunk that is executed while awful is still running with privileged permissions (when run by the superuser)."))
