Changeset 17186 in project


Ignore:
Timestamp:
02/06/10 17:19:25 (10 years ago)
Author:
Mario Domenech Goulart
Message:

Documentation for awful 0.10.

File:
1 edited

Legend:

Unmodified
Added
Removed
  • wiki/eggref/4/awful

    r17173 r17186  
    1212Here's a short summary of awful features:
    1313
    14 * Straightforward interface to postgresql
     14* Straightforward interface to databases (currently supported are postgresql and sqlite3)
    1515* Easy access to query string and body request variables from HTTP requests
    1616* Ajax support via JQuery
     
    3131The following eggs are required:
    3232
    33 * [[http://chicken.wiki.br/eggref/4/postgresql|postgresql]]
    3433* [[http://chicken.wiki.br/eggref/4/spiffy|spiffy]]
    3534* [[http://chicken.wiki.br/eggref/4/spiffy-request-vars|spiffy-request-vars]]
     
    7170You can also use some global page-related parameters if all pages use the same CSS, doctype and charset ({{page-css}}, {{page-doctype}} and {{page-charset}}, respectively).
    7271
     72
     73
    7374=== Accessing request variables
    7475
     
    103104
    104105You can disable this feature by setting the {{enable-reload}} parameter to {{#f}}.  You can also change the URL path by setting the {{reload-path}} parameter.
     106
     107
    105108
    106109=== Using ajax
     
    173176</enscript>
    174177
     178
     179
    175180=== Adding arbitrary javascript code to pages
    176181
     
    192197</enscript>
    193198
     199
     200
    194201=== Database access
    195202
    196 As with ajax, database access is not enabled by default.  To anable it, you need to set the {{enable-db}} parameter to {{#t}}.
    197 
    198 Additionally, to use the db, you need to provide the credentials.  You can provide the credentials by setting the {{db-credentials}} parameter (see the [[http://chicken.wiki.br/eggref/4/postgresql|postgresql]] egg).
    199 
    200 To actually query the database, there's the {{$db}} procedure, which uses as arguments a string representing the query and, optionally, a default value to be used in case the query doesn't return any result. {{$db}} returns a list of lists. Below is an usage example:
    201 
    202 <enscript highlight=scheme>
    203   (use awful)
    204  
    205   (enable-db #t)
     203To access databases, you need some of the awful eggs which provide database access.  Currently, these are the possible options:
     204
     205* [[http://chicken.wiki.br/eggref/4/awful-postgresql|awful-postgresql]] (for Postgresql databases, using the [[http://chicken.wiki.br/eggref/4/postgresql|postgresql]] egg)
     206
     207* [[http://chicken.wiki.br/eggref/4/awful-sqlite3|awful-sqlite3]] (for Sqlite3 databases, using the [[http://chicken.wiki.br/eggref/4/sqlite3|sqlite3]] egg)
     208* [[http://chicken.wiki.br/eggref/4/awful-sql-de-lite|awful-sql-de-lite]] (for Sqlite3 databases, using the [[http://chicken.wiki.br/eggref/4/sqlite3|sqlite3]] egg)
     209
     210As with ajax, database access is not enabled by default.  To enable it, you need to pick one the awful database support eggs and call the {{enable-db}} procedure.  Since version 0.10, and differently from the {{enable-*}} parameters, {{enable-db}} is a zero-argument procedure provided by each of awful database-support eggs.  So, if you use {{awful-postgresql}} the {{enable-db}} procedure will automatically set up awful to use a postgresql database.
     211
     212Additionally, to use the db, you need to provide the credentials.  You can provide the credentials by setting the {{db-credentials}} parameter.  See the documentation for the eggs corresponding to the database type you are using ([[http://chicken.wiki.br/eggref/4/postgresql|postgresql]] for Postgresql and ([[http://chicken.wiki.br/eggref/4/sqlite3|sqlite3]] or ([[http://chicken.wiki.br/eggref/4/sql-de-lite|sql-de-lite]] for Sqlite3.)
     213
     214To actually query the database, there's the {{$db}} procedure, which uses as arguments a string representing the query and, optionally, a default value (a keyword parameter) to be used in case the query doesn't return any result. {{$db}} returns a list of lists. Below is an usage example:
     215
     216<enscript highlight=scheme>
     217  (use awful awful-postgresql)
     218 
     219  (enable-db)
    206220  (db-credentials '((dbname . "my-db")
    207221                    (user . "mario")
     
    216230</enscript>
    217231
     232''Hint'': for Sqlite3 databases, {{db-credentials}} should be the path to the database file.
     233
    218234There's also the {{$db-row-obj}} procedure for when you want to access the results of a query by row name.  {{$db-row-obj}} returns a procedure of two arguments: the name of the field and, optionally, a default value to be used in case the field value is {{#f}}.
    219235
     
    226242</enscript>
    227243
    228 If you need more flexibility to query the database, you can always use the {{(db-connection}}) parameter to get the database connection object and use it with the procedures available from the postgresql egg API.
     244''Warning'': currently {{$db-row-obj}} is only implemented for Postgresql.
     245
     246If you need more flexibility to query the database, you can always use the {{(db-connection}}) parameter to get the database connection object and use it with the procedures available from the your favorite database egg API.
    229247
    230248
     
    367385
    368386
     387
    369388=== Compiled pages
    370389
     
    375394
    376395
     396
    377397=== Multiple applications support
    378398
    379399To be able to deploy multiple awful applications with different configurations under the same server, use Spiffy access files.  See Spiffy's [[http://chicken.wiki.br/eggref/4/spiffy#access-files|access files documentation]] for further details.
     400
    380401
    381402
     
    599620<parameter>(db-connection)</parameter>
    600621
    601 A per-request [[http://chicken.wiki.br/eggref/4/postgresql|postgresql]] egg connection object.  The connection is automatically opened and closed by awful in a per-request basis (unless {{enable-db}} is {{#f}} or the {{no-db}} keyword parameter for {{define-page}} is {{#t}}.)
     622A per-request [[http://chicken.wiki.br/eggref/4/postgresql|postgresql]] egg connection object.  The connection is automatically opened and closed by awful in a per-request basis (unless databases are not being used the {{no-db}} keyword parameter for {{define-page}} is {{#t}}.)
    602623
    603624
     
    687708</enscript>
    688709
     710''Warning'': currently {{$db-row-obj}} is only implemented for Postgresql databases.
     711
    689712
    690713<procedure>(sql-quote . data)</procedure>
     
    692715Escape and quote the concatenation of {{data}} to be used in SQL queries.
    693716
     717''Warning'': for Sqlite databases, {{sql-quote}} just replaces {{'}} by {{''}} and quotes the {{data}}.  For Postgresql, {{sql-quote}} quotes the result of {{escape-string}}.
     718
    694719
    695720<procedure>(define-page path contents #!key css title doctype headers charset no-ajax no-template no-session no-db no-javascript-compression)</procedure>
     
    703728If {{no-session}} is {{#t}}, it means that the page should not use session.
    704729
    705 If {{no-db}} is {{#t}}, it means that the page should not use the database, even when {{enable-db}} is {{#t}} and {{db-credentials}} is not {{#f}}.
     730If {{no-db}} is {{#t}}, it means that the page should not use the database, even when database usage is activated by {{enable-db}} and {{db-credentials}} is not {{#f}}.
    706731
    707732If {{no-javascript-compression}} is {{#t}} the javascript code for the page is not compressed, even when {{enable-javascript-compression}} is not {{#f}}.
     
    735760If the {{no-session}} keyword parameter is {{#t}}, it means that no session should be considered ({{ajax}} implicit sends the session identifier when {{no-session}} is {{#f}}).
    736761
    737 If the {{no-db}} keyword parameter is {{#t}}, it means that the should be no attempt to connect the database, even when {{enable-db}} is {{#t}} and {{db-credentials}} is not {{#f}}.
     762If the {{no-db}} keyword parameter is {{#t}}, it means that the should be no attempt to connect the database, even when database usage is activated by {{enable-db}} and {{db-credentials}} is not {{#f}}.
    738763
    739764The {{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 {{define-page}}) but for different vhosts.
     
    886911=== Version history
    887912
     913; 0.10
     914* Multiple database support. Currently Postgresql (via [[http://chicken.wiki.br/eggref/4/postgresql|postgresql]] egg) and Sqlite3 (via [[http://chicken.wiki.br/eggref/4/sqlite3|sqlite3]] and [[http://chicken.wiki.br/eggref/4/sql-de-lite|sql-de-lite]] eggs) are supported.  See [[http://chicken.wiki.br/eggref/4/awful-postgresql|wful-postgresql]], [[http://chicken.wiki.br/eggref/4/sqlite3|sqlite3]] and [[http://chicken.wiki.br/eggref/4/sql-de-lite|sql-de-lite]] eggs.
     915
     916* Removed requirement for postgresql
     917
     918* `enable-db' is now a procedure (not a parameter as before) and accepts no arguments
     919
    888920; 0.9 : {{login-form}} gets the {{user}} refilled when the session or passowrd is not valid.  This feature may be disabled by setting the {{refill-user}} keyword parameter for {{login-form}} to {{#f}} (default is {{#t}}).  Thanks to Arthur Maciel for suggesting this feature.
    889921; 0.8 :
Note: See TracChangeset for help on using the changeset viewer.