WebSite Director (WSD) Directory Index Templates allow you to format directory indexes, if you have turned on Directory Indexing for your site. See the Directory Indexing Tutorial   for more information. 

This tutorial provides the following information:

1. Adding and Maintaining Templates
2. Directory Index-specific Template Commands
3. Custom SQL Queries
4. Microsoft Windows Non-ODBC MySQL or MiniSQL example queries
5. Microsoft Windows ODBC-accessed database  example queries
6. Unix Filesystem-based SQL database example queries
7. Advanced Custom SQL Queries
8. Sample Directory Index Template File

1. Adding and Maintaining Templates

The method that you can use to add and maintain templates for your site depends on the "Modify Templates" setting on the System Policies   screen:

• System Admin - you can revise templates immediately via the Maintain Templates screen (accessed from the System Administration screen). Warning: Templates that are created/modified using this interface will NOT be stored in the version history!  
• Submit Request -  changes must be made through the Submit New Request function available from the WSD Home page and the Edit Request screen.
• Both - you may use either method to add and maintain templates, depending on your permissions.Warning: Templates created/modified using the "System Admin" interface will NOT be stored in the version history!  

When a template is modified, you can immediately rebuild all indexes that use the template via the Apply Template function accessed from the System Administration screen.  See Apply Template . You may test a modified template by using the "Rebuild Index" function from within any directory that uses the template you have changed. 

Any WSD Template Language tags can be used in Directory Index Templates. See Template Language .

2. Directory Index-specific Template Commands

<$foreach $document> normal HTML text <$endfor>
<$for $parentdir> normal HTML text <$endfor>
<$foreach $siblingdir> normal HTML text <$endfor>
<$foreach $childdir> normal HTML text <$endfor>
<$ifcurrdir> normal HTML text <$endif>

WSD repeats the text between the $foreach or $ for and $endfor tags for each document or directory occurrence designated by the $foreach or $for tags. The $parentdir, $siblingdir, or $childdir tags specify the level of the directory hierarchy that should be listed relative to the directory that the index file is being built for. Any template variable tags specified in the Template Language tutorial can be used to retrieve information about the current document or directory that is being processed by the $foreach or $for tag.

WSD uses the $ifcurrdir tag to include special text specific to the directory entry that the index file is being built for.

3. Custom SQL Queries

A series of directory-index-specific template commands can be used to specify the SQL queries used to retrieve the lists of documents and directories used to build the directory index page. Custom queries can be specified to include documents from other directories or to specify special selection or sorting criteria. Any SQL query valid for the database server WSD is using can be used, as long as the records returned by the query match the record format of the built-in WSD queries. The template command is $setquery , and consists of the following types:

<$setquery doc="...document query...">
<$setquery docprop="...document properties query...">
<$setquery dir="...directory query...">
<$setquery dirprop="...directory properties query...">

When specifying a custom document or directory query, a similar custom query should be specified for the corresponding property records if the generated list of documents or directories will contain records that do not match the results of the built-in WSD property queries. The sort order of property queries is not important.

The custom query used in a $setquery command can contain property and field replacement variables in the same format as other commands that use computed strings, such as <$href {$prop:propname$} >  and <$include { $field:fieldname$}>. Unix file system directory name separators are "/" whereas Windows uses "\" as the directory name separator. Make sure that the slash characters are of the correct type when specifying directory path information in the query.

When WSD is running on a Windows server and using a MySQL or MiniSQL database, additional backslash characters are needed in directory names to "escape" the original backslash characters for recognition purposes in the database query interpreter. To provide "escaped" versions of the WSD directory properties when creating custom SQL queries using MySQL or MiniSQL , prepend the word "escape" to directory template variables (e.g. " escapedir" is an escaped version of " dir", " escapedirpath" is an escaped version of " dirpath", and " escapedirparent" is an escaped version of " dirparent").

When specifying a custom directory query, a new set of "$foreach" and/or "<$foreach $dir>" commands terminated by a <$endfor>, must be defined following each query set to walk the results of the query. The following examples show sets of sample custom queries in various environments, each of which generates the exact same document and directory lists as the standard WSD index template processing (the directory list matches the standard "$siblingdir " list). For ease of reading, each line of source code is shown as a bullet item. Warning: To function properly, the command shown following each bullet must be fully contained within a single line of source code without any line breaks.

4.Microsoft Windows Non-ODBC MySQL or MiniSQL example queries: 

• <$setquery doc="select wsd_documents.* from wsd_documents,wsd_document_props where wsd_documents.filename like '$prop:escapedirpath$\\\\%' and wsd_documents.filename not like '$prop:escapedirpath$\\\\%\\\\%' and wsd_documents.filename= wsd_document_props.filename and property= 'position' and propvalue != 0 order by propvalue">
• <$setquery docprop="select * from wsd_document_props where filename like '$prop:escapedirpath$\\\\%' and filename not like '$prop:escapedirpath$\\\\%\\\\%' order by filename">
• <$if $prop:dirparent$ eq "\">
• <$setquery dir="select * from wsd_directories where dirname like '\\\\_%' and dirname not like '\\\\%\\\\_%' and ! (flags & 1) order by dirname">
• <$setquery dirprop="select * from wsd_directory_props where dirname like '\\\\_%' and dirname not like '\\\\%\\\\_%' order by dirname">
• <$else>
• <$setquery dir="select * from wsd_directories where dirname like '$prop:escapedirparent$\\\\%' and dirname not like '$prop:escapedirparent$\\\\%\\\\_%' and ! (flags & 1) order by dirname">
• <$setquery dirprop="select * from wsd_directory_props where dirname like '$prop:escapedirparent$\\\\%' and dirname not like '$prop:escapedirparent$\\\\%\\\\_%' order by dirname">
• <$endif>

5.Microsoft Windows ODBC-accessed database  example queries: 

• <$setquery doc="select wsd_documents.* from wsd_documents,wsd_document_props where wsd_documents.filename like '$prop:dirpath$\\%' and wsd_documents.filename not like '$prop:dirpath$\\%\\%' and wsd_documents.filename= wsd_document_props.filename and property= 'position' and propvalue != 0 order by propvalue">
• <$setquery docprop="select * from wsd_document_props where filename like '$prop:dirpath$\\%' and filename not like '$prop:dirpath$\\%\\%' order by filename">
• <$if $prop:dirparent$ eq "\">
• <$setquery dir="select * from wsd_directories where dirname like '\\_%' and dirname not like '\\%\\_%' and ! (flags & 1) order by dirname">
• <$setquery dirprop="select * from wsd_directory_props where dirname like '\\_%' and dirname not like '\\%\\_%' order by dirname">
• <$else>
• <$setquery dir="select * from wsd_directories where dirname like '$prop:dirparent$\\%' and dirname not like '$prop:dirparent$\\%\\_%' and ! (flags & 1) order by dirname">
• <$setquery dirprop="select * from wsd_directory_props where dirname like '$prop:dirparent$\\%' and dirname not like '$prop:dirparent$\\%\\_%' order by dirname">
• <$endif>

The $if test around the directory queries in each of the previous examples is used to specify a different query format, required when the parent directory is the root directory.

Remember! While the above samples span multiple lines, each $setquery command must be all on one line in the actual template. The maximum length of a  $setquery command is 1024 characters. The query string may contain '<' and '>' characters as long as the entire query string is enclosed within quotes.

7.Advanced Custom SQL Queries

You can use multiple document properties in your custom SQL queries to create sophisticated extraction and/or ordering for the documents you are indexing. The following sample query (Unix platform) extracts a list of only those documents with a filename beginning with the word "agenda" and sorts them based on the values of 2 WSD properties: in descending order by $prop:publishdate$ and, within the same date, in ascending order by $prop:title$. See Notes for explanations of highlighted and underlined text within the query.

• <$setquery doc = " select distinct docs.* from wsd_documents as docs, wsd_document_props as prop1, wsd_document_props as prop2, wsd_document_props as prop3 where docs.filename like '$prop:dirpath$/agenda%' and docs.filename not like '$prop:dirpath$/%/%' and docs.filename=prop1.filename and docs.filename=prop2.filename and docs.filename=prop3.filename and prop1.property='title' and prop2.property='publish_date' and (prop3.property='position' and prop3.propvalue != 0) and ! (flags & 8) order by floor(prop2.propvalue/86400) desc, prop1.propvalue asc;">

Note-1: for readers not fully versed in SQL syntax:

• distinct eliminates duplicate document references when multiple properties exist for the same document
• as defines an "alias" (underlined text) used later within the query to create unique property references
• floor specifies the calculated value must always be rounded DOWN for comparison purposes
• desc spefies descending sort order
• asc specifies ascending sort order
• % - SQL "wildcard" reference, meaning "any value" (i.e. agenda% means select all filenames beginning with the word agenda, and %agenda% means select all filenames containing the word agenda anywhere in the name)

Other Notes: to clarify placement and associations for underlined text and symbols:

• prop1 - used to create a unique reference for the document "title" property
• prop2 - used to create a unique reference for the document "publishdate" property (the fieldname in the database is actually "publish_date" not "publishdate")
• prop3 - used to create a unique reference for the "Index Position" property
• flags - a set of indicators set/used by WSD, where (flags & 8) refers to the "document deleted" indicator

8. Sample Directory Index Template File

The following is a sample Directory Index template provided with WSD: 

<html> 
<title>Directory Index</title> 
<body bgcolor=#FFFFFF> 
<b><h2 align=center>Directory Index 
<p><$prop:dirsection$> <$prop:dirdesc$></b></h2> 
<p><h3>Summary</h3> 
<p><blockquote><$include {.summary}></blockquote> 
<p><h3>Contents of This Directory</h3> 
<ul> 
<$foreach $document><li><a href="<$prop:fname$>"><$prop:docnum$></a> <$prop:title$> <$endfor></ul> 
<p><h3>Nearby Directories</h3> 
<p><$for $parentdir><$prop:dirsection$> <a href=".."><$prop:dirdesc$></a><$endfor> 
<ul> 
<$foreach $siblingdir><li><$prop:dirsection$> <a href="../<$prop:dirname$>"> <$prop:dirdesc$></a> 
<$ifcurrdir> 
<ul> 
<$foreach $childdir><li><$prop:dirsection$> <a href="<$prop:dirname$>"><$prop:dirdesc$></a> 
<$endfor></ul> 
<$endif><$endfor></ul> 
<font size=-2>Copyright &#169; 2001 My Company. All rights reserved. 
Updated <$prop:currdate$><br></font></body></html>

Copyright 2000-2005 CyberTeams, Inc., http://www.cyberteams.com All rights reserved.
CyberTeams and WebSite Director are registered trademarks of CyberTeams, Inc. All other marks are the property of their respective owners.