Changeset 18559 in project


Ignore:
Timestamp:
06/19/10 16:10:38 (11 years ago)
Author:
Mario Domenech Goulart
Message:

Updated docs for awful 0.23.

File:
1 edited

Legend:

Unmodified
Added
Removed
  • wiki/eggref/4/awful

    r18449 r18559  
    3434* [[http://chicken.wiki.br/eggref/4/html-tags|html-tags]]
    3535* [[http://chicken.wiki.br/eggref/4/html-utils|html-utils]]
     36* [[http://chicken.wiki.br/eggref/4/json|json]]
    3637* [[http://chicken.wiki.br/eggref/4/http-session|http-session]] (>= 2.0)
    3738
     39
    3840=== Components
    3941
     
    6264{{define-page}} is the primitive procedure to define pages.  In the simplest case, it takes as arguments a path to the page and a procedure to generate the page contents. The path to the page you use as the first argument is the same to be used as the path part of the URL you use to access the page.
    6365
    64 In the example we use the {{main-page-path}} parameter, which is one of the awful configuration parameters.  The default is {{"/main"}}.  So, when you access {{http://localhost:8080}} awful will take you to {{http://localhost:8080/main}}.
     66In the example we use the {{main-page-path}} parameter, which is one of the awful configuration parameters.  The default is {{"/"}}.
    6567
    6668If you look at the page source code, you'll see that awful created an HTML page for you.  Awful uses the [[http://chicken.wiki.br/eggref/4/html-utils|html-tags]]'s {{html-page}} procedure behind the scenes.  You can customize the page either by passing {{html-page}}'s keyword parameters to {{define-page}} or by setting the {{page-template}} parameter with your favourite procedure to generate pages (a one argument procedure which receives the page contents and returns a string representing the formatted contents). {{define-page}} would still pass the {{html-page}} keyword parameters, so you can make use of them.
     
    102104The {{++}} procedure is an alias to {{string-append}} (name inspired by Haskell's operator to concatenate strings).
    103105
    104 So, restart the web server to reload the code, then access the main page using an argument, represented by the {{person}} query string variable: {{http://localhost:8080/main?person=Mario}}. You'll see a page showing {{Hello, Mario!}}.
     106So, restart the web server to reload the code, then access the main page using an argument, represented by the {{person}} query string variable: {{http://localhost:8080/?person=Mario}}. You'll see a page showing {{Hello, Mario!}}.
    105107
    106108
     
    428430=== List of user configurable parameters
    429431
     432==== Debugging
     433
    430434<parameter>(debug-file [file path])</parameter>
    431435
     
    449453
    450454
     455<parameter>(debug-resources [boolean])</parameter>
     456
     457When {{#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 {{debug-file}}.  The default value is {{#f}}.
     458
     459
     460==== Database
     461
    451462<parameter>(db-credentials [boolean or list])</parameter>
    452463
     
    456467
    457468
     469==== Ajax
     470
    458471<parameter>(ajax-library [string])</parameter>
    459472
     
    477490
    478491
     492<parameter>(ajax-invalid-session-message [string])</parameter>
     493
     494The message to be used when attempting the make an ajax call using an invalid session identifier.
     495
     496The default value is {{"Invalid session}}.
     497
     498
     499
     500==== Sessions
     501
    479502<parameter>(enable-session [boolean])</parameter>
    480503
     
    484507
    485508
     509==== Access control
     510
    486511<parameter>(page-access-control [procedure])</parameter>
    487512
     
    498523
    499524
     525<parameter>(valid-password? [procedure])</parameter>
     526
     527A two-argument (user and password) procedure which indicates whether the given password is valid for the given user.
     528
     529The default value is {{(lambda (user password) #f)}}.
     530
     531
     532==== Pages
     533
    500534<parameter>(page-doctype [string])</parameter>
    501535
     
    504538The default value is {{""}}.
    505539
     540
    506541<parameter>(page-css [boolean or string])</parameter>
    507542
     
    509544
    510545The default value is {{#f}} (no CSS).
     546
    511547
    512548<parameter>(page-charset [boolean or string])</parameter>
     
    515551The default value is {{#f}} (no explicit charset).
    516552
    517 
    518 <parameter>(login-page-path [string])</parameter>
    519 
    520 The URL path for the login page.  When creating a login page, be sure to set the {{no-session}} keyword parameter for {{define-page}} to {{#t}}, otherwise you'll get an endless loop.
    521 
    522 The default value is {{"/login"}}.
    523 
    524 
    525 <parameter>(main-page-path [string])</parameter>
    526 
    527 The URL path to the app main page.
    528 
    529 The default value is {{"/main"}}.
    530 
    531 <parameter>(app-root-path [string])</parameter>
    532 
    533 The base path to be used by the application.  All the pages defined by {{define-page}} will use {{app-root-path}} as the base directory.  For example, if {{app-root-path}} is set to {{"/my-app"}} and {{"my-page"}} is used as first argument to {{define-page}}, the page would be available at {{http://<server>:<port>/my-app/my-page}}.
    534 
    535 The default value is {{"/"}}.
    536 
    537 <parameter>(valid-password? [procedure])</parameter>
    538 
    539 A two-argument (user and password) procedure which indicates whether the given password is valid for the given user.
    540 
    541 The default value is {{(lambda (user password) #f)}}.
    542553
    543554<parameter>(page-template [procedure])</parameter>
     
    557568The default value is {{html-page}} (see the [[http://chicken.wiki.br/eggref/4/html-utils|html-utils]] egg documentation.)
    558569
    559 <parameter>(ajax-invalid-session-message [string])</parameter>
    560 
    561 The message to be used when attempting the make an ajax call using an invalid session identifier.
    562 
    563 The default value is {{"Invalid session}}.
    564 
     570
     571<parameter>(page-exception-message [procedure])</parameter>
     572
     573An one-argument procedure to be used when an exception occurs while {{define-page}} tries to evaluate its contents.
     574
     575The default value is {{(lambda (exn) (<h3> "An error has accurred while processing your request."))}}
     576
     577
     578
     579==== Page paths
     580
     581<parameter>(main-page-path [string])</parameter>
     582
     583The URL path to the app main page.
     584
     585The default value is {{"/"}}.
     586
     587
     588<parameter>(app-root-path [string])</parameter>
     589
     590The base path to be used by the application.  All the pages defined by {{define-page}} will use {{app-root-path}} as the base directory.  For example, if {{app-root-path}} is set to {{"/my-app"}} and {{"my-page"}} is used as first argument to {{define-page}}, the page would be available at {{http://<server>:<port>/my-app/my-page}}.
     591
     592The default value is {{"/"}}.
     593
     594
     595<parameter>(login-page-path [string])</parameter>
     596
     597The URL path for the login page.  When creating a login page, be sure to set the {{no-session}} keyword parameter for {{define-page}} to {{#t}}, otherwise you'll get an endless loop.
     598
     599The default value is {{"/login"}}.
     600
     601
     602==== Web REPL
    565603
    566604<parameter>(web-repl-access-control [procedure])</parameter>
     
    578616
    579617
     618
     619==== Session inspector
     620
    580621<parameter>(session-inspector-access-control [procedure])</parameter>
    581622
     
    592633
    593634
    594 <parameter>(page-exception-message [procedure])</parameter>
    595 
    596 An one-argument procedure to be used when an exception occurs while {{define-page}} tries to evaluate its contents.
    597 
    598 The default value is {{(lambda (exn) (<h3> "An error has accurred while processing your request."))}}
    599 
     635==== Javascript
    600636
    601637<parameter>(enable-javascript-compression [boolean])</parameter>
     
    615651
    616652
     653
    617654=== List of read-only parameters available to users
    618655
     
    645682
    646683
     684
    647685=== List of procedures
    648686
     687
     688==== Miscelaneous
     689
    649690<procedure>(++ string1 string2 ... stringn)</procedure>
    650691
     
    657698
    658699
     700==== Javascript
     701
    659702<procedure>(include-javascript file)</procedure>
    660703
     
    664707<procedure>(add-javascript . code)</procedure>
    665708
    666 Add arbitrary javascript code to the pages defined by {{define-page}}.
    667 
     709Add arbitrary javascript code to the pages defined by {{define-page}} and {{define-session-page}}.
     710
     711
     712==== Debugging
    668713
    669714<procedure>(debug . args)</procedure>
     
    676721Pretty-print {{arg}} to the file {{debug-file}}.
    677722
     723
     724
     725==== Sessions and authentication
    678726
    679727<procedure>($session var #!optional default)</procedure>
     
    721769
    722770
     771<procedure>(define-login-trampoline path #!key vhost-root-path hook)</procedure>
     772
     773Define a trampoline -- an intermediate page accessed when redirecting from the login page to the main page.
     774
     775
     776<procedure>(login-form #!key (user-label "User: ") (password-label "Password: ") (submit-label "Submit") (refill-user #t))</procedure>
     777
     778Return a user/password login form (e.g., for using in authentication pages).
     779
     780When the {{refill-user}} is {{#t}}, the User field is reffiled with the value from the {{user}} query string value when either the session or the password is invalid.
     781
     782The {{user-label}}, {{password-label}} and {{submit-label}} keyword parameters are labels to be used for the user, password and submit form widgets, respectively.
     783
     784
     785
     786==== Request variables and values
     787
    723788<procedure>($ var #!optional default converter)</procedure>
    724789
    725790Return the HTTP request value for the given variable {{var}}.  The variable is looked for in both the query string (GET method) and request body (e.g., POST method).
    726791
     792
     793==== Database access
    727794
    728795<procedure>($db q #!key default values)</procedure>
     
    759826''Warning'': for Sqlite databases, {{sql-quote}} just replaces {{'}} by {{''}} and quotes the {{data}}.  For Postgresql, {{sql-quote}} quotes the result of {{escape-string}}.
    760827
     828
     829
     830==== Pages
    761831
    762832<procedure>(define-page path contents #!key css title doctype headers charset no-ajax no-template no-session no-db no-javascript-compression)</procedure>
     
    797867
    798868</enscript>
     869
    799870
    800871<procedure>(define-session-page path contents . rest)</procedure>
     
    825896
    826897
    827 <procedure>(ajax path id event proc #!key target (action 'html) (method 'POST) (arguments '()) js no-session no-db vhost-root-path live prelude)</procedure>
     898
     899==== Ajax
     900
     901<procedure>(ajax path id event proc #!key target (action 'html) (method 'POST) (arguments '()) success no-session no-db vhost-root-path live prelude update-targets)</procedure>
    828902
    829903Generate 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).
     
    860934The {{prelude}} keyword parameter (string) is an arbitrary piece of javascript code to be placed right before the ajax request.
    861935
     936The {{update-targets}} keyword parameter is a list of symbols which represent the identifiers of DOM elements to be updated on the success of the ajax request.  When {{update-targets}} is used, the procedure {{proc}} used as argument to {{ajax}} should yield an alist as result.  The alist maps DOM elements identifiers to their corresponding values.
     937
     938Here's an example:
     939
     940<enscript highlight=scheme>
     941#!/usr/bin/awful
     942
     943(use awful html-tags)
     944
     945(enable-ajax #t)
     946
     947(define-page (main-page-path)
     948  (lambda ()
     949
     950    (ajax "foo" 'foo 'click
     951          (lambda ()
     952            '((a . 1) (b . 2) (c . 3)))
     953          update-targets: '(a b c))
     954
     955    (<div>
     956     (link "#" "foo" id: "foo")
     957     (<div> id: "a")
     958     (<div> id: "b")
     959     (<div> id: "c"))))
     960</enscript>
     961
     962The {{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 {{response}} is bound and contains the request resulting data.  Here's an example:
     963
     964<enscript highlight=scheme>
     965#!/usr/bin/awful
     966
     967(use awful html-tags)
     968
     969(enable-ajax #t)
     970
     971(define-page (main-page-path)
     972  (lambda ()
     973
     974    (ajax "foo" 'foo "click"
     975          (lambda ()
     976            "hey")
     977          success: "$('#bar').html(response + ' you!')")
     978
     979    (++ (link "#" "foo" id: "foo")
     980        (<div> id: "bar"))))
     981</enscript>
     982
    862983The {{ajax}} procedure is session, HTTP request and database -aware.
    863984
    864985
    865 <procedure>(periodical-ajax path interval proc #!key target (action 'html) (method 'POST) (arguments '()) js no-session no-db vhost-root-path live prelude)</procedure>
     986<procedure>(periodical-ajax path interval proc #!key target (action 'html) (method 'POST) (arguments '()) success no-session no-db vhost-root-path live prelude update-targets)</procedure>
    866987
    867988Periodically execute {{proc}} on the server side, using {{(app-root-path)/(ajax-namespace)/path}} as the URL path for the server side handler.
     
    872993
    873994
    874 <procedure>(ajax-link path id text proc #!key target (action 'html) (method 'POST) (arguments '()) js no-session no-db (event 'click) vhost-root-path live class hreflang type rel rev charset coords shape accesskey tabindex a-target prelude)</procedure>
     995<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 class hreflang type rel rev charset coords shape accesskey tabindex a-target prelude update-targets)</procedure>
    875996
    876997A shortcut to
     
    8821003</enscript>
    8831004
    884 The meaning of the {{target}}, {{action}}, {{method}}, {{arguments}}, {{js}}, {{no-session}}, {{no-db}}, {{event}}, {{vhost-root-path}} and {{live}} keyword parameters is the same as for {{ajax}}'s.
     1005The meaning of the {{target}}, {{action}}, {{method}}, {{arguments}}, {{success}}, {{no-session}}, {{no-db}}, {{event}}, {{vhost-root-path}}, {{update-targets}} and {{live}} keyword parameters is the same as for {{ajax}}'s.
    8851006
    8861007The meaning of the {{class}}, {{hreflang}}, {{type}}, {{rel}}, {{rev}}, {{charset}}, {{coords}}, {{shape}}, {{accesskey}}, {{tabindex}} and {{a-target}} are the same as for [[http://chicken.wiki.br/eggref/4/html-tags]]' {{<nowiki>&lt;a&gt;</nowiki>}} procedure (except that {{a-target}} is {{<nowiki>&lt;a&gt;</nowiki>}}'s {{target}}, since {{ajax}} uses the {{target}} keyword parameter).
     
    8891010
    8901011
    891 <procedure>(login-form #!key (user-label "User: ") (password-label "Password: ") (submit-label "Submit") (refill-user #t))</procedure>
    892 
    893 Return a user/password login form (e.g., for using in authentication pages).
    894 
    895 When the {{refill-user}} is {{#t}}, the User field is reffiled with the value from the {{user}} query string value when either the session or the password is invalid.
    896 
    897 The {{user-label}}, {{password-label}} and {{submit-label}} keyword parameters are labels to be used for the user, password and submit form widgets, respectively.
    898 
     1012
     1013==== Web REPL
    8991014
    9001015<procedure>(enable-web-repl path #!key css title)</procedure>
     
    9081023{{enable-web-repl}} automatically enables ajax (see {{enable-ajax}}.)
    9091024
     1025
     1026==== Session inspector
     1027
    9101028<procedure>(enable-session-inspector path #!key css title)</procedure>
    9111029
     
    9171035
    9181036{{enable-session-inspector}} automatically enables session (see {{enable-session}}.)
    919 
    920 <procedure>(define-login-trampoline path #!key vhost-root-path hook)</procedure>
    921 
    922 Define a trampoline -- an intermediate page accessed when redirecting from the login page to the main page.
    9231037
    9241038
     
    11101224* sjamaan
    11111225
     1226=== FAQ (aka Fakely Asked Questions)
     1227
     1228==== How does awful bind URIs to files/directories on the filesystem and procedures?
     1229
     1230Explanation by example:
     1231
     1232When a procedure is bound to a path {{a}} (like {{(define-page "a" (lambda ...))}}) and the request is made to {{a/}}, the awful behavior is the following:
     1233
     1234* if the path {{a}} does not exist, the server replies with the result of the evaluation of the procedure bound to {{a}}.
     1235
     1236* if {{a}} is an existent file, the server replies with the file contents (or the result of processing the file, in case it is a special one like [[http://chicken.wiki.br/eggref/4/spiffy#web-scheme-handler|web-scheme]] or {{.ssp}} files)
     1237
     1238* if {{a}} is an existing directory and the directory contains one of the files in {{index-file}} (see documentation for [[http://chicken.wiki.br/eggref/4/spiffy|Spiffy]]), with the index file contents (or the result of processing the file, in case it is a special one like [[http://chicken.wiki.br/eggref/4/spiffy#web-scheme-handler|web-scheme]]'s or {{.ssp}})
     1239
     1240* if {{a}} is an existing directory and does not contain index files, the server replies with the result of the evaluation of the  procedure bound to {{a}}.
     1241
     1242
     1243=== Known bugs
     1244
     1245* The {{ajax}} procedure is not session-aware when called from {{define-session-page}} (it is when called from {{define-page}}).  To workaround this bug, you can explicitly pass the sid (see the read-only {{sid}} parameter) along with requests (see the {{arguments}} keyword parameter for {{ajax}} and ajax-related procedures).
     1246
    11121247
    11131248=== License
     
    11171252
    11181253=== Version history
     1254
     1255; 0.23:
     1256* added the {{update-targets}} keyword parameter for {{ajax}}, {{periodical-ajax}} and {{ajax-link}} procedures (multiple targets update support)
     1257* added the {{debug-resources}} parameter for debugging the resources table
     1258* the {{js}} keyword parameter for {{ajax}}, {{periodical-ajax}} and {{ajax-link}} has been renamed to {{success}} (to match JQuery's API naming for Ajax). '''Warning''': if your code uses the {{js}} keyword parameter for {{ajax}}, {{periodical-ajax}} or {{ajax-link}}, this change will break your code.
     1259* the javascript variable bound to the response data on successful ajax request has been renamed to {{response}} (it was {{h}} before). The same warning for the {{js}}->{{success}} renaming is valid for this change, since it is directly related to {{js}} (now {{success}}).
     1260* the default value for {{main-page-path}} is now {{"/"}} (it was {{"/main"}} before).  There's no more main page redirection.  '''Warning''': if your code relies on hardcoded {{"/main"}} paths (instead of using {{(main-page-path)}}) or if you rely on the main page automatic redirection, this change will break your code.
     1261* {{ajax}} bugfix regarding to session identifiers (could cause "Invalid session ID" errors in some cases, specially with {{define-session-page}}).
     1262* better handling of URI paths regarding to paths as directories (see FAQ's ''How does awful bind URIs to files/directories on the filesystem and procedures?'')
    11191263
    11201264; 0.22:
Note: See TracChangeset for help on using the changeset viewer.