Changeset 33741 in project

Timestamp:

11/13/16 10:07:23 (3 years ago)

Author:

Mario Domenech Goulart

Message:

awful (wiki): update doc with changes from git

File:

• wiki/eggref/4/awful (modified) (8 diffs)

wiki/eggref/4/awful

@@ -1553 +1553 @@
 been introduced in awful version 0.40.0.
 
+Note that {{$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
+{{define-page}}).
+
+If you want to use {{$db}} out of the context of request handlers,
+you'll have to manage database connections yourself.  Basically, you
+have to parameterize {{db-connection}} with the actual connection
+object.  Example:
+
+<enscript highlight=scheme>
+(parameterize ((db-connection (open-database (db-credentials))))
+  ($db the-query)
+  (close-database (db-connection)))
+</enscript>
+
 
 ===== {{$db-row-obj}}
@@ -1581 +1596 @@
 
 ===== {{define-page}}
-<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 strict)</procedure>
+<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)</procedure>
 
 Define an awful page.
@@ -1591 +1606 @@
 
 
-{{handler}} should return either a string or a no-argument procedure.
-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).
+{{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
@@ -1634 +1655 @@
 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
@@ -1649 +1675 @@
 {{(irregex "/[^/]*")}}, even if the regex specified that paths with a
 trailing slash should not match.
-
 
 Examples:
@@ -1802 +1827 @@
 
 Generate JavaScript code to be added to the page defined by
-{{define-page}}.  Return the generated JavaScript code (which usually
-is not useful, so should be discarded).
+{{define-page}}.  Return the generated JavaScript code. Unless
+{{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.
 
 {{path}} is the URL path (a string) of the server side handler. This
@@ -1941 +1968 @@
 jQuery.ajax
 ([[http://api.jquery.com/jQuery.ajax/|http://api.jquery.com/jQuery.ajax/]]).
+
+The {{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 {{#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.
 
 The {{ajax}} procedure is session, HTTP request and database -aware.
@@ -3155 +3189 @@
 === License
 
-  Copyright (c) 2010-2014, Mario Domenech Goulart
+  Copyright (c) 2010-2016, Mario Domenech Goulart
   All rights reserved.