= Mason Domain - a mason-like domain =


According to the Mason website: [http://www.masonhq.com/ Mason] is a '''powerful Perl-based web site development and delivery engine.'''

The Wub Mason domain emulates some of Mason's architecture.  Henceforth in this document, '''Mason''' will refer to MasonDomain, and not the original PERL system.

This documentation is being delivered by a Mason instance.  Detailed documentation can be found here [http://wiki.tcl.tk/_doc/ns?ns=Mason]

----

=== Example 1. Construct a Mason domain ===

 Mason mason -url /_wub -root /var/www/wubdocs

This will create a command ''mason'' which interprets the file system directory specified by '''-root''', using '''.before''' and '''.after''' as templates.

=== Example 2. Use of a Mason domain ===

 mason do $req

Assuming that '''$req''' represents a Wub request dict, a Wub response dict will be returned containing the file within mason's '''-root''' named by the request, after mason's '''-url''' has been stripped from the front of the URL.

----
== Mason Architecture ==

There are two kinds of static elements (normal files and directories), and three kinds of procedural elements (templates, .notfound and .wrapper files) in Mason.  The procedural elements are tcl scripts, which are loaded and evaluated.

;directories: are treated as if they referred to a file index.html contained within them.  If no index.html or index.tml file is found, the .directory template is evaluated
;normal files: are returned unevaluated, and unmodified.
;templates: are evaluated with tcl's [[subst]] command.  Their resultant value is returned to the client (subject to some additional processing, [http:#extra noted below].)  Templates are distinguished by their file extension ('''.tml''' by default.)

=== Functional Files ===

Mason evaluates files when certain conditions arise.  Functional files are searched for in the directory to which the requested URL maps, or in successively enclosing directories until it is found.

;.notfound: is evaluated when a URL doesn't resolve to a file.  The search proceeds from the nearest enclosing URL, in a hierarchy-climbing search.
;.before: is evaluated before content is sought and generated.
;.after: is evaluated after content has been found or generated.  It is intended to perform some of the functions of [http:Convert.stx Convert Domain].
;.directory: is evaluated when a URL maps to a directory which contains no index.html or index.html file.
;*.tml: is evaluated when a URL maps to a non-existent file whose rootname matches the template's rootname.

----
== Template Handling ==

[#:extra]
