Changeset 36427 in project


Ignore:
Timestamp:
08/25/18 20:51:07 (3 months ago)
Author:
mario
Message:

eggref/4/awful: release notes for version 1.0.0

File:
1 edited

Legend:

Unmodified
Added
Removed
  • wiki/eggref/4/awful

    r35517 r36427  
    6767* [[/egg/spiffy-cookies|spiffy-cookies]]
    6868* [[/egg/spiffy-request-vars|spiffy-request-vars]]
    69 * [[/egg/html-tags|html-tags]]
    70 * [[/egg/html-utils|html-utils]]
    7169* [[/egg/json|json]]
    7270* [[/egg/http-session|http-session]]
    7371* [[/egg/sxml-transforms|sxml-transforms]]
     72* [[/eggref/5/srfi-1|srfi-1]] (CHICKEN 5 only -- in CHICKEN 4 it is a core unit)
     73* [[/eggref/5/srfi-13|srfi-13]] (CHICKEN 5 only -- in CHICKEN 4 it is a core unit)
     74* [[/eggref/5/srfi-69|srfi-69]] (CHICKEN 5 only -- in CHICKEN 4 it is a core unit)
     75
    7476
    7577=== Components
     
    8486
    8587<enscript highlight=scheme>
    86 (use awful)
    87 
    88 (enable-sxml #t)
     88(cond-expand
     89  (chicken-4
     90    (use awful))
     91  (chicken-5
     92    (import awful)))
    8993
    9094(define-page (main-page-path)
     
    132136#! /usr/bin/awful
    133137
    134 (use awful)
    135 
    136 (enable-sxml #t)
     138(cond-expand
     139  (chicken-4
     140    (use awful))
     141  (chicken-5
     142    (import awful)))
    137143
    138144(define-page (main-page-path)
     
    157163
    158164<enscript highlight=scheme>
    159 (use awful)
    160 
    161 (enable-sxml #t)
     165(cond-expand
     166  (chicken-4
     167    (use awful))
     168  (chicken-5
     169    (import awful)))
    162170
    163171(define-page (main-page-path)
     
    182190
    183191<enscript highlight=scheme>
    184 (use awful)
    185 
    186 (enable-sxml #t)
     192(cond-expand
     193  (chicken-4
     194    (use awful))
     195  (chicken-5
     196    (import awful)))
    187197
    188198(define-page "/reload"
     
    200210
    201211<enscript highlight=scheme>
    202 (use awful spiffy)
     212(cond-expand
     213  (chicken-4
     214    (use awful spiffy))
     215  (chicken-5
     216    (import awful spiffy)))
    203217
    204218(page-access-control
     
    239253
    240254<enscript highlight=scheme>
    241 (use awful)
    242 
    243 (enable-sxml #t)
     255(cond-expand
     256  (chicken-4
     257    (use awful))
     258  (chicken-5
     259    (import awful)))
    244260
    245261(define-page (main-page-path)
     
    256272
    257273<enscript highlight=scheme>
    258 (use awful)
    259 
    260 (enable-sxml #t)
     274(cond-expand
     275  (chicken-4
     276    (use awful))
     277  (chicken-5
     278    (import awful)))
    261279
    262280(define-page (main-page-path)
     
    274292The {{ajax}} procedure uses at least four arguments:
    275293
    276 1. The URL path to the server-side handler (a string).  This path is relative to {{ajax-namespace}} parameter (default is {{ajax}}.  So, in the example, we'll have {{/ajax/greetings}} as the ajax path to be generated if we pass {{"greetings"}} as the first argument.
     2941. The URL path to the server-side handler (a string).  This path is relative to {{ajax-namespace}} parameter (default is {{ajax}}.  So, in the example, we'll have {{/ajax/greetings}} as the ajax path to be generated if we pass {{ajax}} as the first argument.
    277295
    2782962. The ID of the DOM element to observe.
     
    283301
    284302So, in the example, {{ajax}} will bind the fourth argument (the
    285 procedure) to the path generated based on the first argument on the server side. Then
     303procedure) to the first argument (the path) on the server side. Then
    286304it will add JavaScript code to the page in order to wait for click
    287305events for the element of ID {{greetings}}.  When we click "Hello,
     
    295313
    296314<enscript highlight=scheme>
    297 (use awful)
    298 
    299 (enable-sxml #t)
     315(cond-expand
     316  (chicken-4
     317    (use awful))
     318  (chicken-5
     319    (import awful)))
    300320
    301321(define-page (main-page-path)
     
    318338
    319339<enscript highlight=scheme>
    320 (use awful)
    321 
    322 (enable-sxml #t)
     340(cond-expand
     341  (chicken-4
     342    (use awful))
     343  (chicken-5
     344    (import awful)))
    323345
    324346(define-page (main-page-path)
     
    367389
    368390<enscript highlight=scheme>
    369 (use awful awful-postgresql)
     391(cond-expand
     392  (chicken-4
     393    (use awful awful-postgresql))
     394  (chicken-5
     395    (import awful awful-postgresql)))
    370396
    371397(enable-db)
    372 (enable-sxml #t)
    373398
    374399(db-credentials '((dbname . "my-db")
     
    441466
    442467<enscript highlight=scheme>
    443 (use awful)
    444 
    445 (enable-sxml #t)
     468(cond-expand
     469  (chicken-4
     470    (use awful))
     471  (chicken-5
     472    (import awful)))
     473
    446474(enable-session #t)
    447475
     
    586614
    587615<enscript highlight=scheme>
    588 (use awful)
    589 
    590 (enable-sxml #t)
     616(cond-expand
     617  (chicken-4
     618    (use awful))
     619  (chicken-5
     620    (import awful)))
     621
    591622(enable-session #t)
    592623
     
    812843<enscript highlight=scheme>
    813844;; -*- scheme -*-
    814 
    815 (use spiffy awful)
     845(cond-expand
     846  (chicken-4
     847    (use awful spiffy))
     848  (chicken-5
     849    (import awful spiffy)))
     850
    816851(spiffy-user "awful")
    817852(server-port 80)
     
    860895<parameter>(enable-sxml [boolean])</parameter>
    861896
    862 If {{#t}} specifies that awful should assume that page handlers always
    863 produce SXML.  If {{#f}} specifies that awful should assume that page
    864 handlers always produce strings.
    865 
    866 The default value is {{#f}} (likely to be changed in future versions,
    867 since supporting SXML by default is a goal).
    868 
    869 This parameter has been introduced in awful 0.36.
     897Deprecated.  Since version 1.0.0, this parameter has no effect.  It is
     898going to be removed in future versions.
    870899
    871900
     
    10341063
    10351064A one-argument (URL path of the current page) procedure which returns
    1036 the access denied message.
    1037 
    1038 The default value is {{(lambda (path) (<h3> "Access denied."))}}.
     1065the access denied message in SXML.
     1066
     1067The default value is {{(lambda (path) '(h3 "Access denied."))}}.
    10391068
    10401069
     
    11071136{{define-page}} tries to evaluate its contents.
    11081137
    1109 The default value is {{(lambda (exn) (<h3> "An error has occurred while processing your request."))}}
     1138The default value is {{(lambda (exn) '(h3 "An error has occurred while processing your request."))}}
    11101139
    11111140
     
    11891218
    11901219===== {{web-repl-access-denied-message}}
    1191 <parameter>(web-repl-access-denied-message [string])</parameter>
     1220<parameter>(web-repl-access-denied-message [SXML])</parameter>
    11921221
    11931222Message to be printed when the access to the web REPL is denied.
    11941223
    1195 The default value is {{(<h3> "Access denied.")}}.
     1224The default value is {{'(h3 "Access denied.")}}.
    11961225
    11971226
     
    12261255
    12271256===== {{session-inspector-access-denied-message}}
    1228 <parameter>(session-inspector-access-denied-message [string])</parameter>
     1257<parameter>(session-inspector-access-denied-message [SXML])</parameter>
    12291258
    12301259Message to be printed when the access to the session inspector is denied.
    12311260
    1232 The default value is {{(<h3> "Access denied.")}}.
     1261The default value is {{'(h3 "Access denied.")}}.
    12331262
    12341263
     
    13291358
    13301359==== Miscellaneous
    1331 
    1332 ===== {{++}}
    1333 <procedure>(++ string1 string2 ... stringn)</procedure>
    1334 
    1335 A shortcut to {{string-append}}.
    1336 
    1337 This procedure has been deprecated in awful 0.36 and will be removed
    1338 in future versions.
    1339 
    1340 
    1341 ===== {{concat}}
    1342 <procedure>(concat args #!optional (sep ""))</procedure>
    1343 
    1344 Convert {{args}} to string and intersperse the resulting strings with {{sep}}.
    1345 
    1346 
    1347 This procedure has been deprecated in awful 0.36 and will be removed
    1348 in future versions.
    1349 
    13501360
    13511361===== {{awful-version}}
     
    16791689
    16801690<enscript highlight=scheme>
    1681 (use awful
    1682      srfi-1  ;; for filter-map
    1683      regex   ;; for regexp
    1684      spiffy) ;; for send-static-file
    1685 
    1686 (enable-sxml #t)
     1691(cond-expand
     1692  (chicken-4
     1693    (use awful
     1694         srfi-1   ;; for filter-map
     1695         srfi-13  ;; for string-prefix?
     1696         irregex  ;; for irregex
     1697         spiffy)) ;; for send-static-file
     1698  (chicken-5
     1699    (import (chicken irregex) ;; for irregex
     1700            (chicken format)  ;; for sprintf
     1701            (chicken string)) ;; for string-split
     1702    (import awful
     1703            srfi-1   ;; for filter-map
     1704            srfi-13  ;; for string-prefix?
     1705            spiffy)) ;; for send-static-file
     1706  )
    16871707
    16881708;;
     
    17011721
    17021722;; http://host:port/add/1/2/3 => 6
    1703 (define-page (regexp "/add/.*")
     1723(define-page (irregex "/add/.*")
    17041724  (lambda (path)
    17051725    (let ((numbers (filter-map string->number (string-split path "/"))))
     
    17661786
    17671787<enscript highlight=scheme>
    1768 (use awful)
    1769 
    1770 (enable-sxml #t)
     1788(cond-expand
     1789  (chicken-4
     1790    (use awful))
     1791  (chicken-5
     1792    (import awful)))
    17711793
    17721794(define-session-page "said"
     
    17981820
    17991821
    1800 
    18011822===== {{set-page-title!}}
    18021823<procedure>(set-page-title! title)</procedure>
     
    18111832
    18121833<enscript highlight=scheme>
    1813 (use awful)
     1834(cond-expand
     1835  (chicken-4
     1836    (use awful))
     1837  (chicken-5
     1838    (import awful)))
    18141839
    18151840(define-page (main-page-path)
     
    18181843    "Hi!"))
    18191844</enscript>
     1845
     1846
     1847===== {{html-page}}
     1848
     1849<procedure>(html-page contents #!key css title doctype headers charset content-type literal-style? (html-attribs '()) (body-attribs '()))</procedure>
     1850
     1851Generates an SXML page containing {{contents}} (SXML).  The following
     1852keywords arguments may be used to customize the page:
     1853
     1854* {{headers}}: an SXML form containing additional headers to be inserted in the section delimited by the {{<head>}} tag. Default = {{#f}}.
     1855
     1856* {{title}}: the title for the page (to be used in the {{<title>}} tag). Default = {{#f}}.
     1857
     1858* {{css}}: may be either a path to a Cascading Style Sheet file, to be linked from the generated page (the default value is {{#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: {{css: '("css1.css" ("css2.css"))}}. In the example, {{css1.css}} would be linked from the generated page (using the link tag) and {{css2.css}} would be inlined into the generated page (e.g., {{html-page}} would read the {{css2.css}} file and inline its contents in the HTML code).
     1859
     1860* {{doctype}}: specifies the document type of the generated page. The default value is {{#f}}. The possible values are the ones available from the [[doctype]] egg.
     1861
     1862* {{charset}}: specifies the default charset to be used in the corresponding meta tag of the document. The default value is {{"UTF-8"}} (only when {{content-type}} is provided).
     1863
     1864* {{literal-style?}}: if {{#f}}, convert special characters in style code (CSS) to theyr equivalent HTML entities.  If non-{{#f}}, insert them verbatim.
     1865
     1866* {{content-type}} and {{charset}} are used together for the {{<meta http-equiv ...>}} specification.: {{charset}}'s default value is {{"UTF-8"}} and {{content-type}}'s default value is {{"application/xhtml+xml"}}.
     1867
     1868* {{html-attribs}}: attributes to the {{html}} tag. The format is a list of lists {{(<attribute> <value>)}} ({{<attribute>}} is a symbol).  Example: {{(html-page "foo" html-attribs: '((lang "us")))}}.
     1869
     1870* {{body-attribs}}: attributes to the {{body}} tag. The format is a list of lists {{(<attribute> <value>)}} ({{<attribute>}} is a symbol).  Example: {{(html-page "foo" body-attribs: '((bgcolor "red")))}}.
    18201871
    18211872
     
    19151966
    19161967<enscript highlight=scheme>
    1917 (use awful)
    1918 
    1919 (enable-sxml #t)
     1968(cond-expand
     1969  (chicken-4
     1970    (use awful))
     1971  (chicken-5
     1972    (import awful)))
    19201973
    19211974(define-page (main-page-path)
     
    19401993
    19411994<enscript highlight=scheme>
    1942 (use awful)
    1943 
    1944 (enable-sxml #t)
     1995(cond-expand
     1996  (chicken-4
     1997    (use awful))
     1998  (chicken-5
     1999    (import awful)))
    19452000
    19462001(define-page (main-page-path)
     
    20292084
    20302085<enscript highlight=scheme>
    2031 (use awful)
     2086(cond-expand
     2087  (chicken-4
     2088    (use awful))
     2089  (chicken-5
     2090    (import awful)))
    20322091
    20332092;; / -> /foo
     
    20462105
    20472106<enscript highlight=scheme>
    2048 (use awful)
     2107(cond-expand
     2108  (chicken-4
     2109    (use awful))
     2110  (chicken-5
     2111    (import awful)))
    20492112
    20502113;; /bar.* -> /foo
     
    22472310
    22482311<enscript highlight=scheme>
    2249 (use awful srfi-13 html-tags awful-sql-de-lite)
     2312(cond-expand
     2313  (chicken-4
     2314    (use awful awful-sql-de-lite srfi-13))
     2315  (chicken-5
     2316    (import awful awful-sql-de-lite srfi-13)))
     2317
    22502318
    22512319;;;
     
    22572325
    22582326  parameters: ((enable-ajax #t)
    2259                (enable-sxml #t)
    22602327               (ajax-library "/js/foo.js"))
    22612328
     
    22682335      '(p "quux from foo")))
    22692336
    2270   )
     2337)
    22712338
    22722339;;;
     
    22862353  (define-page "/bar/baz"
    22872354    (lambda ()
    2288       (<p> "baz from bar")))
     2355      '(p "baz from bar")))
    22892356
    22902357  (define-page "/bar/quux"
    22912358    (lambda ()
    2292       (<p> "quux from bar")))
    2293 
    2294   )
     2359      '(p "quux from bar")))
     2360
     2361)
    22952362
    22962363;;;
     
    23032370  (define-page "/baz/foo"
    23042371    (lambda ()
    2305       "foo from baz"))
     2372      '("foo from baz")))
    23062373
    23072374  (define-page "/baz/bar"
    23082375    (lambda ()
    2309       "bar from baz"))
    2310 
    2311   )
     2376      '("bar from baz")))
     2377
     2378)
    23122379</enscript>
    23132380
     
    23212388
    23222389<enscript highlight=scheme>
    2323 (use awful)
     2390(cond-expand
     2391  (chicken-4
     2392    (use awful))
     2393  (chicken-5
     2394    (import awful)))
    23242395
    23252396(add-request-handler-hook!
     
    23312402(define-page (main-page-path)
    23322403  (lambda ()
    2333     "1"))
     2404    '("1")))
    23342405</enscript>
    23352406
     
    23542425
    23552426<enscript highlight=scheme>
    2356 (use awful)
    2357 
    2358 (enable-sxml #t)
     2427(cond-expand
     2428  (chicken-4
     2429    (use awful))
     2430  (chicken-5
     2431    (import awful)))
    23592432
    23602433(define-session-page "save-and-show-user"
     
    23672440
    23682441<enscript highlight=scheme>
    2369 (use awful)
    2370 
    2371 (enable-sxml #t)
     2442(cond-expand
     2443  (chicken-4
     2444    (use awful))
     2445  (chicken-5
     2446    (import awful)))
    23722447
    23732448(define-session-page "save-and-show-user"
     
    24222497
    24232498<enscript highlight=scheme>
    2424 (use awful)
    2425 
    2426 (enable-sxml #t)
     2499(cond-expand
     2500  (chicken-4
     2501    (use awful))
     2502  (chicken-5
     2503    (import awful)))
    24272504
    24282505(define (define-custom-page path content)
     
    24342511(define-custom-page (main-page-path)
    24352512  (lambda ()
    2436     "Hey!"))
     2513    '("Hey!")))
    24372514</enscript>
    24382515
     
    24502527
    24512528<enscript highlight=scheme>
    2452 (use awful)
    2453 
    2454 (enable-sxml #t)
     2529(cond-expand
     2530  (chicken-4
     2531    (use awful))
     2532  (chicken-5
     2533    (import (chicken base)
     2534            (chicken condition)
     2535            (chicken port))
     2536    (import awful)))
    24552537
    24562538(page-exception-message
     
    24802562
    24812563
    2482 ==== Awful & SXML
    2483 
    2484 Since version 0.36, awful provides SXML support.  To enable it, you
    2485 can either do it globally, by setting the {{enable-sxml}} parameter to
    2486 {{#t}}, or in a per-page basis, by binding {{define-page}}'s
    2487 {{use-sxml}} keyword parameter to {{#t}}.
    2488 
    2489 Notice that supporting SXML by default is a goal.  Strings support
    2490 will be deprecated and removed in future versions.  So, if you are
    2491 about to start a project using awful, consider setting {{enable-sxml}}
    2492 to {{#t}}.
    2493 
    2494 Here are some examples:
    2495 
    2496 ===== Globally using SXML
    2497 
    2498 <enscript highlight=scheme>
    2499 (use awful)
    2500 
    2501 (enable-sxml #t)
    2502 
    2503 (define-page (main-page-path)
    2504   (lambda ()
    2505     `(div (@ (id "content"))
    2506           "Hi, this is awful " ,(awful-version))))
    2507 </enscript>
    2508 
    2509 
    2510 You can also use [[/egg/html-tags|html-tags]] and
    2511 [[/egg/html-utils|html-utils]] to generate SXML content:
    2512 
    2513 <enscript highlight=scheme>
    2514 (use awful html-tags)
    2515 
    2516 (enable-sxml #t)
    2517 (generate-sxml? #t) ;; from html-tags
    2518 
    2519 (define-page (main-page-path)
    2520   (lambda ()
    2521     (<div> id: "content"
    2522            "Hi, this is awful " (awful-version))))
    2523 </enscript>
    2524 
    2525 
    2526 ===== Using SXML in a per-page basis
    2527 
    2528 <enscript highlight=scheme>
    2529 (use awful html-tags)
    2530 
    2531 (define-page "/strings"
    2532   (lambda ()
    2533     (<div> id: "content"
    2534            "Hi, this is awful " (awful-version))))
    2535 
    2536 
    2537 (define-page "/sxml"
    2538   (lambda ()
    2539     `(div (@ (id "content"))
    2540           "Hi, this is awful " ,(awful-version)))
    2541   use-sxml: #t)
    2542 
    2543 
    2544 (define-page "/sxml-with-html-tags"
    2545   (lambda ()
    2546     (parameterize ((generate-sxml? #t))
    2547       (<div> id: "content"
    2548              "Hi, this is awful " (awful-version))))
    2549   use-sxml: #t)
    2550 </enscript>
    2551 
    25522564
    25532565==== Reloading awful from Emacs
     
    25992611
    26002612<enscript highlight=scheme>
    2601 (use awful regex srfi-13)
     2613(cond-expand
     2614  (chicken-4
     2615    (use awful irregex srfi-13))
     2616  (chicken-5
     2617    (import (chicken string))
     2618    (import awful irregex srfi-13)))
    26022619
    26032620(define (define-page* page-path content)
    2604   (define-page (regexp (string-append page-path "/*.*"))
     2621  (define-page (irregex (string-append page-path "/*.*"))
    26052622    (lambda (path)
    26062623      (let ((url-args
     
    26232640(define-page* "/page1"
    26242641  (lambda _
    2625     "no args"))
     2642    '("no args")))
    26262643
    26272644
     
    26342651(define-page* "/page2"
    26352652  (lambda (foo)
    2636     (conc "foo=" foo)))
     2653    '("foo=" foo)))
    26372654
    26382655
     
    26472664(define-page* "/page3"
    26482665  (lambda (foo #!optional bar)
    2649     (conc "foo=" foo ", bar=" bar)))
     2666    '("foo=" foo ", bar=" bar)))
    26502667
    26512668
     
    26592676(define-page* "/page4"
    26602677  (lambda (#!optional foo bar)
    2661     (conc "foo=" foo ", bar=" bar)))
     2678    '("foo=" foo ", bar=" bar)))
    26622679</enscript>
    26632680
     
    26792696
    26802697<enscript highlight=scheme>
    2681 (use html-utils ;; you'll need html-utils >= 0.10
    2682      awful)
    2683 
    2684 (enable-sxml #t)
     2698(cond-expand
     2699  (chicken-4
     2700    (use awful))
     2701  (chicken-5
     2702    (import awful)))
    26852703
    26862704(define-page (main-page-path)
     
    27002718
    27012719<enscript highlight=scheme>
    2702 (use html-utils ;; you'll need html-utils >= 0.10
    2703      awful)
     2720(cond-expand
     2721  (chicken-4
     2722    (use awful))
     2723  (chicken-5
     2724    (import awful)))
    27042725
    27052726;; Configure page-template to set ng-app as attribute for the html tag
     
    27092730          (append (list content html-attribs: '((ng-app)))
    27102731                  args))))
    2711 
    2712 (enable-sxml #t)
    27132732
    27142733(define-page (main-page-path)
     
    27402759
    27412760<enscript highlight=scheme>
    2742 (use awful)
    2743 
    2744 (enable-sxml #t)
     2761(cond-expand
     2762  (chicken-4
     2763    (use awful))
     2764  (chicken-5
     2765    (import awful)))
    27452766
    27462767(define (prompt-guess)
     
    27882809
    27892810<enscript highlight=scheme>
    2790 (use awful sandbox)
     2811(cond-expand
     2812  (chicken-4
     2813    (use awful sandbox))
     2814  (chicken-5
     2815    (import (chicken base)
     2816            (chicken condition)
     2817            (chicken port))
     2818    (import awful sandbox)))
    27912819
    27922820(enable-sxml #t)
     
    28862914
    28872915<enscript highlight=scheme>
    2888 (use awful)
    2889 
    2890 (enable-sxml #t)
     2916(cond-expand
     2917  (chicken-4
     2918    (use awful))
     2919  (chicken-5
     2920    (import awful)))
    28912921
    28922922(define color-table
     
    29382968
    29392969==== Fortune server
     2970
     2971Note: this example assumes CHICKEN 4.
    29402972
    29412973This example is a fortune server in awful.  It demonstrates some handy
     
    31873219{{add-javascript}} and ajax-related features for {{define-page}}
    31883220won't be effective for the page in question.
     3221
     3222* If you encounter bugs, please report them to the author.
     3223
    31893224=== License
    31903225
    3191   Copyright (c) 2010-2016, Mario Domenech Goulart
     3226  Copyright (c) 2010-2018, Mario Domenech Goulart
    31923227  All rights reserved.
    31933228 
     
    32173252=== Version history
    32183253
     3254===== version 1.0.0
     3255
     3256* CHICKEN 5 support
     3257* Drop support for page handlers that produce strings ("string mode").  Now only SXML is supported.
     3258* {{enable-sxml}} has been deprecated.  It is still available, but doesn't do anything.
     3259* Drop dependency on the following eggs: regex, html-tags, html-utils
     3260* The following deprecated procedures have been removed: {{++}}, {{concat}}
     3261* New procedure: {{html-page}}
     3262
     3263
    32193264===== version 0.42.0
    32203265
Note: See TracChangeset for help on using the changeset viewer.