SourceForge: woof/woof: changeset 114:2ccc5af27dfc
More docs
authorAshok P. Nadkarni <apnadkarni@users.sourceforge.net>
Tue Nov 10 22:35:28 2009 +0530 (2 weeks ago)
changeset 1142ccc5af27dfc
parent 1133a735ff3e798
child 115f16b0aeb6e0c
More docs
app/controllers/_woof/docs/ug_controller.tcl
app/controllers/_woof/docs/views/ug-controller_object-content.wtf
app/controllers/_woof/docs/views/ug-default_page_layout-content.wtf
app/controllers/_woof/docs/views/ug-implementing_controllers-content.wtf
app/controllers/_woof/docs/views/ug-page_generation-content.wtf
app/controllers/_woof/docs/views/ug-page_layout-content.wtf
app/controllers/_woof/docs/views/ug-page_section_direct-content.wtf
app/controllers/_woof/docs/views/ug-page_section_templates-content.wtf
app/controllers/_woof/docs/views/ug-page_sections-content.wtf
app/controllers/_woof/docs/views/ug-redirects-content.wtf
app/controllers/_woof/docs/views/ug-wtf-content.wtf
public/stylesheets/_woof.css
     1.1 --- a/app/controllers/_woof/docs/ug_controller.tcl	Tue Nov 10 21:06:30 2009 +0530
     1.2 +++ b/app/controllers/_woof/docs/ug_controller.tcl	Tue Nov 10 22:35:28 2009 +0530
     1.3 @@ -69,11 +69,20 @@
     1.4              {response_headers "Adding HTTP Response Headers" 2}
     1.5              {sending_files "Sending Files and Non-HTML Data" 2}
     1.6              {ocookies_object "The <span class='wf_code'>ocookies</span> Object" 2}
     1.7 +            {page_generation "Page Generation"}
     1.8 +            {page_layout "Page Layout" 2}
     1.9 +            {default_page_layout "Default Page Layout" 3}
    1.10 +            {custom_page_layout "Custom Page Layout" 3}
    1.11 +            {page_sections "Page Sections" 2}
    1.12 +            {page_section_templates "Template Based Page Sections" 3}
    1.13 +            {page_section_direct "Directly Generated Page Sections" 3}
    1.14 +            {using_stylesheets "Using Stylesheets" 2}
    1.15 +            {using_images "Using Images" 2}
    1.16 +            {wtf "Woof! Template Files" 2}
    1.17              {tools "Tools and Utilities"}
    1.18              {installer "installer - Installation Utility" 2}
    1.19              {bowwow "bowwow - a Lightweight Web Server" 2}
    1.20              {scgi_winservice "scgi_winservice - Woof! Windows Service" 2}
    1.21 -            {page_generation "Page Generation"}
    1.22              {wtf "Woof! Template Files"}
    1.23              {recommended_reading "Recommended Reading"}
    1.24          }
     2.1 --- a/app/controllers/_woof/docs/views/ug-controller_object-content.wtf	Tue Nov 10 21:06:30 2009 +0530
     2.2 +++ b/app/controllers/_woof/docs/views/ug-controller_object-content.wtf	Tue Nov 10 22:35:28 2009 +0530
     2.3 @@ -6,7 +6,7 @@
     2.4  application writer to implement the specific action methods for a
     2.5  controller.</p>
     2.6  
     2.7 -<h2>The <span class='wf_code'>Controller</span> class tree</h2>
     2.8 +<h3>The <span class='wf_code'>Controller</span> class tree</h3>
     2.9  
    2.10  <p>When an incoming request is [my _chapter_link url_dispatcher "mapped"]
    2.11  to a controller class and action method, Woof! instantiates a controller
    2.12 @@ -21,7 +21,7 @@
    2.13  to all controllers in the application, the changes should be made to
    2.14  class <span class='wf_code'>ApplicationController</span>.</p>
    2.15  
    2.16 -<h2>The controller object execution context</h2>
    2.17 +<h3>The controller object execution context</h3>
    2.18  
    2.19  <p>When a controller object is instantiated for a request, the
    2.20  base <span class='wf_code'>Controller</span> class constructor sets up an execution
    2.21 @@ -108,7 +108,7 @@
    2.22  methods. Refer to its
    2.23  [my _manpage_link ::woof::Controller "reference pages"] for more details.</p>
    2.24  
    2.25 -<h2>The <span class='wf_code'>ApplicationController</span> class</h2>
    2.26 +<h3>The <span class='wf_code'>ApplicationController</span> class</h3>
    2.27  
    2.28  <p>The <span class='wf_code'>ApplicationController</span> class is defined to allow
    2.29  the application programmer to add controller behaviours that are
     3.1 --- /dev/null	Thu Jan 01 00:00:00 1970 +0000
     3.2 +++ b/app/controllers/_woof/docs/views/ug-default_page_layout-content.wtf	Tue Nov 10 22:35:28 2009 +0530
     3.3 @@ -0,0 +1,26 @@
     3.4 +<p>The default Woof! page layout is defined by the
     3.5 +file <span class="wf_filename">app/controllers/views/layout.wtf</span>. This
     3.6 +layout divides a Web page into five page sections:</p>
     3.7 +<ul>
     3.8 +  <li>The <span class='wf_code'>header</span> section which contains
     3.9 +  content, such as a banner, that pat the top of a page.</li>
    3.10 +  <li>Similarly, the <span class='wf_code'>footer</span> section
    3.11 +  contains content that is to appear at the bottom of a page.</li>
    3.12 +  <li>The <span class='wf_code'>sidebar</span> contains elements such
    3.13 +  as navigation links that appear alongside the main content.</li>
    3.14 +  <li>The <span class='wf_code'>main</span> section
    3.15 +  contains the primary content of the main page.</li>
    3.16 +  <li>The <span class='wf_code'>supplement</span> section contains
    3.17 +  content related to the main content, such as additional related
    3.18 +  links, advertising.</li>
    3.19 +</ul>
    3.20 +
    3.21 +<p>When using the default layout, all sections are optional. Sections
    3.22 +that are empty are omitted from the generated Web page with the
    3.23 +exception of the main section which is always generated. Section
    3.24 +content may be generated either through template files or directly
    3.25 +created by application code.</p>
    3.26 +
    3.27 +<p>Note that even with the default layout, the size and location of
    3.28 +sections are controllable. For example, the sidebar may appear either
    3.29 +on the left or the right and may be of different width.</p>
     4.1 --- a/app/controllers/_woof/docs/views/ug-implementing_controllers-content.wtf	Tue Nov 10 21:06:30 2009 +0530
     4.2 +++ b/app/controllers/_woof/docs/views/ug-implementing_controllers-content.wtf	Tue Nov 10 22:35:28 2009 +0530
     4.3 @@ -58,7 +58,7 @@
     4.4  method definitions. Naturally, all these stubs could be created
     4.5  manually as well. Using the script only saves a bit of typing.</p>
     4.6  
     4.7 -<h2>Writing an action method</h2>
     4.8 +<h3>Writing an action method</h3>
     4.9  
    4.10  <p>The index method is the default method callled when a request is
    4.11  made that does not contain an explicit action method name for the
     5.1 --- /dev/null	Thu Jan 01 00:00:00 1970 +0000
     5.2 +++ b/app/controllers/_woof/docs/views/ug-page_generation-content.wtf	Tue Nov 10 22:35:28 2009 +0530
     5.3 @@ -0,0 +1,25 @@
     5.4 +<p>Web pages within a site generally follow a specific pattern. For
     5.5 +example, all pages might have a navigation bar on the top, the main
     5.6 +content in the middle and legal or contact information at the
     5.7 +bottom. For the most part, the top and bottom areas might be almost
     5.8 +the same or with little variation across all pages with only the main
     5.9 +content being specific to a page.</p>
    5.10 +
    5.11 +<p>Moreover, the main content itself often follows some boilerplate
    5.12 +format, for example shopping cart where only the line items differ
    5.13 +between page views. In such cases, the page needs to be constructed
    5.14 +from a combination of static content and data dynamically retrieved
    5.15 +from some source such as a database.</p>
    5.16 +
    5.17 +<p>Woof! provides mechanisms to simplify implementation of web pages
    5.18 +that follow the above pattern. Conceptually, Woof! constructs a Web
    5.19 +page from [my _chapter_link page_sections "<em>page sections</em>"],
    5.20 +each identified by a name, that
    5.21 +correspond to the various areas within the page. These page sections
    5.22 +are rendered using templates that combine static content and
    5.23 +HTML markup with Tcl code that generates the dynamic
    5.24 +content. They are then positioned within a page as specified by
    5.25 +a [my _chapter_link page_layout "<em>page layout</em>"]
    5.26 +template, which again can be a combination of
    5.27 +Tcl code and HTML positioning markup.</p>
    5.28 +<p>This chapter describes this whole process.</p>
     6.1 --- /dev/null	Thu Jan 01 00:00:00 1970 +0000
     6.2 +++ b/app/controllers/_woof/docs/views/ug-page_layout-content.wtf	Tue Nov 10 22:35:28 2009 +0530
     6.3 @@ -0,0 +1,100 @@
     6.4 +<p>A layout defines the HTML&nbsp;page head and body sections and then
     6.5 +positions the various page sections within the body.</p>
     6.6 +
     6.7 +<p>The following is a simple example of a layout:</p>
     6.8 +
     6.9 +[my _code_sample {
    6.10 +  <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN">
    6.11 +  <html>
    6.12 +    <head>
    6.13 +      <title>Example Layout</title>
    6.14 +    </head>
    6.15 +    <body>
    6.16 +  % if {[page fetch header content]} {
    6.17 +       $content
    6.18 +       <hr/>
    6.19 +  % }
    6.20 +  % if {[page fetch main content]} {
    6.21 +       $content
    6.22 +  % }
    6.23 +  % if {[page exists footer content]} {
    6.24 +       <hr/>
    6.25 +       $content
    6.26 +  % }
    6.27 +    </body>
    6.28 +  </html>
    6.29 +}]
    6.30 +
    6.31 +<p>The above layout is defined in
    6.32 +[my _chapter_link wtf] (WTF) containing a mixture of Tcl code and HTML 
    6.33 +markup. It starts with defining the standard HTML page headers. Within the body
    6.34 +element, the layout defines three sections - the header, the main
    6.35 +content and the footer. The contents of each section, if defined, are
    6.36 +expected to be in the <span class='wf_code'>page</span> object. Note
    6.37 +that the layout makes use of conditional Tcl statements to insert each
    6.38 +section only if they exist. The <span class='wf_code'>fetch</span>
    6.39 +method returns true if the page section exists and stores it in the
    6.40 +variable <span class='wf_code'>content</span>.
    6.41 +The [my _chapter_link page_object "<span class='wf_code'>page</span>"]
    6.42 +object, from which the HTML content is retrieved, is constructed when
    6.43 +building page sections.
    6.44 +
    6.45 +<h3>Defining page sections in layouts</h3>
    6.46 +
    6.47 +<p>In the above layout, only three sections are referenced. However,
    6.48 +Woof! itself does not impose any restrictions on the number and names
    6.49 +of the sections, or how they are positioned. The page object will
    6.50 +attempt to retrieve the content of each section based on the
    6.51 +controller and action specified in the client request and the name of
    6.52 +the section. The corresponding section content is either supplied by
    6.53 +the action method or generated from a page section template. It is up
    6.54 +to the application writer to ensure the appropriate named sections can
    6.55 +be generated.</p>
    6.56 +
    6.57 +<h3>Processing layout templates</h3>
    6.58 +
    6.59 +<p>A layout template is processed like as any
    6.60 +other [my _chapter_link wtf "Woof Template Format"] file. What
    6.61 +makes it different is really only the intended usage. By convention,
    6.62 +the layout template is primarily be concerned with positioning of
    6.63 +major HTML areas and providing standard headers. It then makes use of
    6.64 +the <span class='wf_code'>page</span> object
    6.65 +to retrieve the various page sections that contain the actual data,
    6.66 +both static and dynamically retrieved from a controller.</p>
    6.67 +
    6.68 +<p>However, there is nothing that prevents a layout from containing
    6.69 +pure static HTML content, or directly accessing a controller's dynamic
    6.70 +content. This practice is not recommended but might be occasionally
    6.71 +used when a particular page does not follow a site's standard layout
    6.72 +and is simple enough that adding separate layout and page section
    6.73 +templates is not worthwhile.</p>
    6.74 +
    6.75 +<h3>Locating layout templates</h3>
    6.76 +
    6.77 +<p>When Woof! receives a client request with a URL that is mapped to a
    6.78 +controller <span class='wf_code'><em>CONTROLLER</em> </span>and
    6.79 +action <span class='wf_code'><em>ACTION</em></span>, it checks for the
    6.80 +existence of the
    6.81 +files <span class="woof_filename"><em>CONTROLLER-ACTION</em>-layout.wtf</span>
    6.82 +and <span class="woof_filename"><em>CONTROLLER</em>-layout.wtf</span>
    6.83 +in the <span class="woof_filename">views</span> subdirectory of the
    6.84 +directory where the controller module is located. If neither is found,
    6.85 +Woof! searches for a
    6.86 +file <span class="woof_filename">layout.wtf</span> in
    6.87 +all <span class="woof_filename">views </span>subdirectories starting
    6.88 +with the controller module directory and working upwards through all
    6.89 +parent module directories of the controller. The first file found is
    6.90 +used as the template for the layout.</p>
    6.91 +
    6.92 +<h3>Sharing layout templates</h3>
    6.93 +
    6.94 +<p>Pages within a web site, or within a specific area of a web site,
    6.95 +share common structure such as navigation bars, footers and so on. A
    6.96 +layout therefore may be, and generally is, shared between actions
    6.97 +within a controller and even across multiple controllers.</p>
    6.98 +
    6.99 +<p>The method described above for locating layouts allows flexible
   6.100 +sharing of common layouts within, and between, controllers and
   6.101 +controller trees while simultaneously allowing special layouts for
   6.102 +specific controllers or even actions within a controller.</p>
   6.103 +
     7.1 --- /dev/null	Thu Jan 01 00:00:00 1970 +0000
     7.2 +++ b/app/controllers/_woof/docs/views/ug-page_section_direct-content.wtf	Tue Nov 10 22:35:28 2009 +0530
     7.3 @@ -0,0 +1,21 @@
     7.4 +<p>In lieu of template files, the content for a page section may be
     7.5 +directly stored into the page object by the action method of a
     7.6 +controller. In this case, when the layout template retrieves the page
     7.7 +section from the object, it will not search for a template file for
     7.8 +the page section but instead directly include the stored
     7.9 +HTML instead. The stored content for the page section must be
    7.10 +properly encoded, valid HTML content as no further processing,
    7.11 +substitution or encoding is done on it.</p>
    7.12 +
    7.13 +<p>The store method of the page object will store any specified
    7.14 +content as the content of the named page section. For example,</p>
    7.15 +
    7.16 +[my _code_sample {
    7.17 +  page store main "<p>This is the content for the main page section.</p>"
    7.18 +}]
    7.19 +
    7.20 +<p>sets the content for the main page section of the web page.</p>
    7.21 +
    7.22 +<p>As a general rule, it is not recommended setting page section
    7.23 +content in this manner except in some simple cases as it violates the
    7.24 +principle of separation of program logic from presentation.</p>
     8.1 --- /dev/null	Thu Jan 01 00:00:00 1970 +0000
     8.2 +++ b/app/controllers/_woof/docs/views/ug-page_section_templates-content.wtf	Tue Nov 10 22:35:28 2009 +0530
     8.3 @@ -0,0 +1,88 @@
     8.4 +<p>Like most other frameworks, Woof! separates program logic from the
     8.5 +presentation by using <em>templates</em> to implement the latter. A
     8.6 +template in Woof! is a combination of HTML text markup with Tcl code
     8.7 +as the simple example below shows.</p>
     8.8 +
     8.9 +[my _code_sample {
    8.10 +<p>The current time is [clock format [clock seconds] -format %T].</p>
    8.11 +}]
    8.12 +
    8.13 +<p>In the above example, the template processor will replace the Tcl
    8.14 +code in brackets with its result, thereby generating a HTML fragment
    8.15 +displaying the current time in a paragraph.</p>
    8.16 +
    8.17 +<h3>Locating page templates</h3>
    8.18 +
    8.19 +<p>When the fetch method of the page object is called to retrieve a
    8.20 +page section that has not already been stored in the object, it
    8.21 +searches the file system for a suitable template from which the
    8.22 +requested page section can be generated.</p>
    8.23 +
    8.24 +<p>If the client request URL is mapped to a controller
    8.25 +<span class='wf_code'><em>CONTROLLER</em></span> and
    8.26 +action <span class='wf_code'><em>ACTION</em></span>, and the name of the page section
    8.27 +to be generated is <span class='wf_code'><em>SECTION</em></span>, the method checks in
    8.28 +turn for the existence of the
    8.29 +files <span class="wf_filename"><em>CONTROLLER-ACTION</em>-<em>SECTION</em>.wtf</span>, 
    8.30 +<span class="wf_filename"><em>CONTROLLER-</em><em>SECTION</em>.wtf</span> 
    8.31 +and <em><span class="wf_filename">SECTION</span></em><span class="wf_filename">.wtf</span>
    8.32 +in the <span class="wf_filename">views</span> subdirectory of the
    8.33 +directory where the controller module is located. If none of them is
    8.34 +found, Woof! searches for a file
    8.35 +<em><span class="wf_filename">SECTION</span></em><span class="wf_filename">.wtf</span>
    8.36 +in all <span class="wf_filename">views</span> subdirectories starting
    8.37 +with the controller module directory and working upwards through all
    8.38 +parent module directories of the controller. The first file found is
    8.39 +used as the template for the page section.</p>
    8.40 +
    8.41 +<h3>Sharing section templates</h3>
    8.42 +
    8.43 +<p>The above search mechanism for templates allows page sections to be
    8.44 +easily shared. For example, a common header page section for the
    8.45 +entire site can be defined by the contents of the
    8.46 +file <span class="wf_filename">app/controllers/views/header.wtf</span>. All
    8.47 +URL's for the site will automatically show its contents wherever the
    8.48 +layout file inserts the page section named <span class='wf_code'>header</span>. A
    8.49 +different header section can be defined for a particular controller,
    8.50 +say <span class="wf_filename">blogs</span>, by creating the
    8.51 +file <span class="wf_filename">app/controllers/views/blogs-header.wtf</span>
    8.52 +with the appropriate content.</p>
    8.53 +
    8.54 +<p>As another example, imagine the website has a separate
    8.55 +module, <span class='wf_code'>site::admin</span>, that is used for managing the
    8.56 +website itself. So the URL
    8.57 +<span class="wf_filename">http://www.mywebsite.com/site/admin/user/show</span>
    8.58 +(for example) would be mapped to the <span class='wf_code'>show</span> action method
    8.59 +in the controller <span class='wf_code'>user</span> (implemented in
    8.60 +class <span class='wf_code'>UserController</span>) in the <span class='wf_code'>site::admin</span>
    8.61 +module. To render the <span class='wf_code'>main</span> page section, Woof! will look
    8.62 +in order for one of the files
    8.63 +<span class="wf_filename">user-show-main.wtf</span>,
    8.64 +<span class="wf_filename">user-main.wtf</span>
    8.65 +and <span class="wf_filename">main.wtf</span> in the
    8.66 +directory <span class="wf_filename">app/controllers/site/admin/views</span>.
    8.67 +If none of these are found, it will then look
    8.68 +for <span class="wf_filename">main.wtf</span> in
    8.69 +the <span class="wf_filename">app/controllers/site/views</span>
    8.70 +directory followed
    8.71 +by <span class="wf_filename">app/controllers/views</span>.</p>
    8.72 +
    8.73 +<p>Note that when searching up the directory hierarchy, Woof! only
    8.74 +uses the section name and does not look for the controller and action
    8.75 +specific templates (such
    8.76 +as <span class="wf_filename">user-show-main.wtf</span>
    8.77 +or <span class="wf_filename">user-main.wtf</span>). This is by design
    8.78 +as it does not make sense for a file specific for a controller and/or
    8.79 +action to show up outside the controller content directory.</p>
    8.80 +
    8.81 +<h3>Page template processing</h3>
    8.82 +<p>The syntax used in the template depends on the template
    8.83 +processor. Currently, Woof! only supports the syntax defined
    8.84 +in [my _chapter_link wtf].</p>
    8.85 +
    8.86 +<p>The processing of the template is done in the context of the
    8.87 +[my _chapter_link controller_object "<span class='wf_code'>controller</span>"]
    8.88 +object. The Tcl code in the template can therefore invoke any method of the
    8.89 +controller or access any object instance variable using the standard
    8.90 +Tcl syntax.</p>
    8.91 +
     9.1 --- /dev/null	Thu Jan 01 00:00:00 1970 +0000
     9.2 +++ b/app/controllers/_woof/docs/views/ug-page_sections-content.wtf	Tue Nov 10 22:35:28 2009 +0530
     9.3 @@ -0,0 +1,44 @@
     9.4 +<p>A page section is the HTML content of a specific area within a
     9.5 +Web page, for example, the header area. Page sections may be generated
     9.6 +by a controller method, or from a template containing a mixture of
     9.7 +HTML content and Tcl code.</p>
     9.8 +
     9.9 +<h3>The <span class='wf_code'>page</span> object</h3>
    9.10 +
    9.11 +<p>By convention, layouts expect to retrieve their page sections from
    9.12 +the <span class='wf_code'>page</span> object, of
    9.13 +class [my _manpage_link ::woof::Page], that
    9.14 +is created by the controller for every request. This object will
    9.15 +return the raw HTML content of a specified page section through
    9.16 +its <span class='wf_code'>fetch</span> method. For example, the
    9.17 +following is a fragment from a layout template.</p>
    9.18 +[my _code_sample {
    9.19 +  % if {[page fetch header header_content]} {
    9.20 +   <hr/>$header_content<hr/>
    9.21 +  % }
    9.22 +}]
    9.23 +
    9.24 +<p>If the <span class='wf_code'>page</span> object has a header
    9.25 +section defined, or can generate one, it returns the content of that
    9.26 +section in <span class='wf_code'>header_content</span> and
    9.27 +returns <span class='wf_code'>true</span>. Otherwise it
    9.28 +returns <span class='wf_code'>false</span>. The layout template
    9.29 +fragment conditionally includes that content, braced by horizontal
    9.30 +rules.</p>
    9.31 +
    9.32 +<p>The <span class='wf_code'>page</span> object may be populated with
    9.33 +page sections in one of two ways.</p>
    9.34 +<ul>
    9.35 +  <li>When a layout invokes the <span class='wf_code'>fetch</span>
    9.36 +  method to retrieve a page section that has not yet been defined,
    9.37 +  the <span class='wf_code'>page</span> object will search the file
    9.38 +  system for a suitable template from which the page section might be
    9.39 +  generated. This is the recommended way of producing a page section
    9.40 +  wherein the template provides the presentation for the page
    9.41 +  separately from the action method.</li>
    9.42 +  <li>Alternatively, an action method may directly store the HTML
    9.43 +  fragment for a page section in which case
    9.44 +  the <span class='wf_code'>fetch</span> method simply returns the
    9.45 +  stored content for the section</li>
    9.46 +</ul>
    9.47 +<p>The following sections describe both these methods.</p>
    10.1 --- a/app/controllers/_woof/docs/views/ug-redirects-content.wtf	Tue Nov 10 21:06:30 2009 +0530
    10.2 +++ b/app/controllers/_woof/docs/views/ug-redirects-content.wtf	Tue Nov 10 22:35:28 2009 +0530
    10.3 @@ -65,7 +65,7 @@
    10.4  the HTTP response code and text (which is not generally displayed
    10.5  in the browser).</p>
    10.6  
    10.7 -<h2>Redirects and rendering</h2>
    10.8 +<h3>Redirects and rendering</h3>
    10.9  <p>Note that because only one response can be sent back to the client,
   10.10  an application cannot redirect a request and simultaneously generate a
   10.11  Web page as a response. Therefore, using <span class='wf_code'>redirect</span>
    11.1 --- /dev/null	Thu Jan 01 00:00:00 1970 +0000
    11.2 +++ b/app/controllers/_woof/docs/views/ug-wtf-content.wtf	Tue Nov 10 22:35:28 2009 +0530
    11.3 @@ -0,0 +1,68 @@
    11.4 +<p>A <strong>Woof! Template Format</strong> (WTF) file is a file
    11.5 +containing a combination of plain text and Tcl code that is processed
    11.6 +to product the final text output. In the context of web servers, the
    11.7 +text is generally HTML format text but does not have to be. Both
    11.8 +layouts and page sections are normally generated from WTF files.</p>
    11.9 +
   11.10 +<p>In its simplest form, a WTF fragment contains text with no
   11.11 +characters that are special to Tcl. The output of the template
   11.12 +processor is exactly the same as the fragment. For example,</p>
   11.13 +
   11.14 +[my _code_sample {
   11.15 +<p>This is a paragraph.</p>
   11.16 +}]
   11.17 +
   11.18 +<p>will be passed through by the WTF processor without any changes.</p>
   11.19 +
   11.20 +<p>Dynamic content can be generated by including Tcl commands and
   11.21 +variable references.</p>
   11.22 +
   11.23 +[my _code_sample {
   11.24 +<p>Today's date is [clock format [clock seconds] -format %D]</p>
   11.25 +}]
   11.26 +
   11.27 +<p>In this WTF fragment, the text between
   11.28 +the <span class='wf_code'>[]</span> characters is evaluated as Tcl
   11.29 +code and replaced by the result of the evaluation in effect printing
   11.30 +the current date. The exact syntax and semantics of processing is
   11.31 +defined by Tcl's subst command which is in fact used as the basic
   11.32 +engine in template processing.</p>
   11.33 +
   11.34 +<p>In addition, lines beginning with the % character are treated
   11.35 +entirely as Tcl code but the resulting values are not inserted into
   11.36 +the template output. This is most useful for control structures or
   11.37 +short intermediate calculations. For example, the following
   11.38 +fragment</p>
   11.39 +
   11.40 +[my _code_sample {
   11.41 +  <table>
   11.42 +  % for {set i 1} {$i < 6} {incr i} {
   11.43 +    <tr><td>$i</td></tr>
   11.44 +  % }
   11.45 +</table>
   11.46 +}]
   11.47 +
   11.48 +<p>will generate a HTML table of integers from 1 to 5.</p>
   11.49 +
   11.50 +<h3>Template context</h3>
   11.51 +
   11.52 +<p>The processing of WTF fragments is implemented by the
   11.53 +command <span class='wf_code'>html_frag</span><sup>1</sup> in the
   11.54 +context of the caller. In the case of Woof!, this context is the
   11.55 +controller object handling the request. Therefore all commands and
   11.56 +variables defined in the context of that controller's methods are
   11.57 +available in the template with appropriate declarations.</p>
   11.58 +
   11.59 +<h3>Comments</h3>
   11.60 +
   11.61 +<p>You can insert comments into an HTML file by starting a line with
   11.62 +the sequence <span class='wf_code'>%#</span>. 
   11.63 +The <span class='wf_code'>%</span> indicates this is Tcl line, and
   11.64 +the <span class='wf_code'>#</span> is
   11.65 +the Tcl comment character.</p>
   11.66 +% # TBD - escaping special HTML characters
   11.67 +% # TBD - block Tcl code using %(%)
   11.68 +
   11.69 +<p><sup>1</sup> This command is based on an enhanced form of
   11.70 +the <span class='wf_code'>substify</span> command from
   11.71 +the <a href="http://wiki.tcl.tk/18455">Tcl wiki</a>.</p>
    12.1 --- a/public/stylesheets/_woof.css	Tue Nov 10 21:06:30 2009 +0530
    12.2 +++ b/public/stylesheets/_woof.css	Tue Nov 10 22:35:28 2009 +0530
    12.3 @@ -3,11 +3,16 @@
    12.4  
    12.5  /* FYI - The Woof logo main color is #DB7D2A */
    12.6  
    12.7 -h1,h2,h3,h4 {
    12.8 +h1,h2 {
    12.9    color: #888888;
   12.10    margin-bottom: 0.5em;
   12.11  }
   12.12  
   12.13 +h3,h4 {
   12.14 +  color: #777777;
   12.15 +  margin-bottom: 0.5em;
   12.16 +}
   12.17 +
   12.18  h4 {
   12.19    font-size: 93%;
   12.20  }