VAT Module Instructions

VAT: Vhost Abstract Template Module Parameters

Files

• Tar file of vat.tcl and this file: Vat-0.3.tar.gz
• Vat.txt file so you can see what it is now. vat.txt
• dirlist.txt, which is an almost exact copy of _ns_dirlist procedure. dirlist.txt

Configuration File Parameters

Here is an example from a working nsd.tcl file. These are the parameters you will need to add to your file, in addition to the parameters already there.

ns_section "ns/server/${server}/modules"
ns_param vat  Tcl

ns_section "ns/server/${server}/module/vat"
# PathVars are directory names to template root, in order (from VhostRoot)
# These vars are set per connection.
ns_param PathVars        [list server version module name] 
ns_param VhostRoot       {/web/server1/vhost}
ns_param Precedence      [list tcl html adp htm]
ns_param pageroot        "/web/server1/www"
ns_param default_handler vat_default_handler
ns_param tcl_handler     vat_tcl_handler
ns_param html_handler    vat_adp_handler
ns_param adp_handler     vat_adp_handler
ns_param defaultServer   [ns_info server]
# Multiple methods can be set
# The default, is for GET POST and HEAD to be set
#ns_param Method          GET         ;

Servermap section is a pointer to the actual server name so that multiple domains can share a set of functionality

ns_section "ns/server/${servername}/module/vat/servermap"
ns_param {host.example.com}    server1
ns_param {other.example.com}   server1
ns_param {www.example.com}     server2
ns_param {example.net}         server3
ns_param {www.example.net}     server4

ns_section "ns/server/${servername}/module/vat/maps"
ns_param {*:server1}    {}
ns_param {*:server2}    {/web/server1/vhost/server2/www}
ns_param {*:server3}    {/web/server1/vhost/server3/www}
ns_param {*:server4}    {relative/pageroot/www}

Where will the files go?

1. vat.tcl

   This file goes in a new directory under your private tcl directory In ACS, this is usually /web/${server}/tcl Create a directory called vat and place this file in that directory. In this example the file is located at:

    /web/server1/tcl/vat/vat.tcl
    

2. Pageroot (www)

   Pageroot for each server is listed under the ".../vat/maps" ns_section

   • A blank map {} indicates that the server uses the default pageroot which is the pageroot parameter from the ".../modules/vat" ns_section In this case the default pageroot is /web/server1/www.
   • A map starting with '/' indicated an absolute pageroot. So server2's pageroot is /web/server1/vhost/server2/www.
   • A map starting with anything else indicates a pageroot relative to the default pageroot. So example.com's pageroot would be at: /web/server1/www/relative/pageroot/www.

3. Template Root

   This is more complicated because of the flexibility desired. You start at VhostRoot and add the variables found as a list under PathVars. You can add or remove variables from this list. Each time a user connects to your server the listed variables are set. Then the Template Root is determined by substituting the variables. In the above example Template Root is:

    /web/server1/vhost/$Template(server)/$Template(version)/$Template(module)/$Template(name)
    

   Just remember, that you can add or leave out as many variables as you want. All you need to do to add a variable is to put the Template array name in the PathVars list and define a proc to set the variable. If you wanted the day of week as variable:

     proc vat_set_template_day { key } {
         global Template
         set Template(day) [ns_fmttime [ns_time] %a]
         return
     }
     

   Note that the variable key is the method (GET,POST,HEAD) and the server name. The variable is not used in the supplied procs, but could be used for more targeted templating. Examples here would be:

   • GET:server1
   • POST:server2
   • HEAD:server3

4. Abstract Files

   Abstract files are simply urls without extensions. If you don't want .tcl or .html extensions on your files, or if you want everyone to think that you have a java based or asp based system, you can use this system to avoid or deceive.

   The point is that the extension is ignored (assuming there isn't an exact match). Then if you have an actual file index.adp, you can access this file as

   • index
   • index.html
   • index.tcl
   • index.jhtml
   • index.asp
   • etc.

   as long as your Precedence list includes adp

   The example configuration has a Precedence list of [list tcl html adp htm].

5. Template files look like: name-01.tcl, name-02.html

   All files in the template directory matching $Template(name)-[0-9][0-9].* are sourced in numeric order. I usually set up all variable in a tcl file and then use an adp file for the html/template.

6. Debugging:

   If you need more information on what parts of the filter are being used for a certain request, you can turn on debugging.

   Set the following parameter in your nsd.tcl file:

     
   ns_section "ns/parameters"
   ns_param   debug           true
       

7. Order of Search

   This filter looks for

   1. an exact match under pageroot
   2. an abstract file under pageroot
   3. a template
   4. exits with filter_ok, if nothing is found which:
   5. passes control back to the main server.

8. Using this filter with multiple ACS domains.

   You need to copy your /web/servername/parameters/${server}.ini file to a new file in the same directory. In this example, I have two OpenACS domains with the following .ini files:

   • server1.ini
   • server2.ini

   You have to set up the file replacing the original server name with the new name. In this example, server2 replaced server1:

   [ns/server/server1/acs] --- becomes -->   [ns/server/server2/acs]

   Also you have to add the following section:

   [ns/server/server2/db]
   Pools=*
   DefaultPool=main