[previous] [next] [top] [search] [index]

Wrappers and Includes

The WN server has extensive capabilities for automatically including files in one which is being served or "wrapping" a served file with another, i.e. inserting the requested file inside another file at a desired location. This latter is useful, for example, if you wish to place a standard message at the beginning or end (or both) of a large collection of files. All files included or used as wrappers must be listed in the index.cache file. They are not listed in the file in which they are to be included; only the location of the insertion is marked. To ensure security various options are available including the the requirement that a served file and all its includes and wrappers have the same owner as the index.cache file listing them. This is done with the -u option.

Another important application of wrappers is to customize the HTML documents returned listing the successful search matches. If, for example, a directory is assigned a wrapper the server assumes that it contains all text describing the search and it merely supplies an unordered list of links to the matching items.

Simple Including

Suppose your server offers the file foo.txt and you wish to have the file bar.txt automatically inserted at some point. You achieve this by use of the "Includes=" directive in the index file in the directory containing foo.txt. That index file should have an entry like 
     File=foo.txt
     Includes=bar.txt

and the file foo.txt should contain the line 

     <!-- #WN_include -->

The marker <!-- #WN_include --> should be the only thing on its line and should have no white space before it. All including of files by WN is done only for text files and only in units of lines.

If include marker is never found in foo.txt, then this file is served and the file bar.txt, is appended at the end. Thus the Includes= directive can be used to append a file without the need of any marker in the main file.

If you wanted to include two files in foo.txt, say bar.txt and bah.txt you would place the marker <!-- #WN_include --> at two places in foo.txt and have an entry in your index file like 

     File=foo.txt
     Includes=bar.txt,bah.txt

The two files will then be included at the marked spots in the order that they are listed in the Includes directive, i.e. bar.txt will be inserted at the first marker and bah.txt at the second. You can have as many included files as you wish. They should all be listed on the "Includes=" line separated by commas.

Including HTML files the "section" marker

Often you may want to include HTML files in a larger document. For example, a single logical HTML document often consists of a number of separate files. This can make it very difficult for a client to download and print the entire document. To alleviate this problem you could form a single document concatenating all the pieces, but that can be problematic when the document is altered or updated as it is necessary to change both the piece and the concatenation. WN offers a solution to this by allowing you to write a small skeleton document which includes all the pieces, forming a "virtual" document which is the concatenation. But if we just used the mechanism above the this the concatenation document would include the elements of all the pieces. To remedy this you use the marker 
     <!-- #WN_section -->

instead of <!-- #WN_include --> and the server will include only the portion of the HTML document between the special comments <!-- #WN_start --> and <!-- #WN_end --> inserted in that document. This requires that these starting and ending comments occur in the HTML document on lines by themselves and with no preceeding white space.

Wrapping Files

Suppose you have a large number of files and want a standard header or footer placed on all of them (perhaps a standar disclaimer). You could, of course, make many copies of the standard header with a different Includes= directive for each, but this is cumbersome. It has other drawbacks as well, such as the fact that grep and context searches do not search associated include files only the main file. To deal with this case WN uses wrappers Wrapping a file is the dual operation to including it. If you have an index file enty like 
     File=foo.txt
     Wrappers=bar.txt

then the server will send the file bar.txt looking for the marker <!-- #WN_include --> and inserting foo.txt at the line where it is found. So this is just like the Includes= directive except the role of which file is included in the other is reversed. If include marker is never found the entire wrapper, bar.txt, is sent first and the main file, foo.txt, is appended at the end. Thus the Wrappers= directive can be used to prepend a file without the need of any marker in the main file.

Search Wrappers

A search wrapper is a special kind of wrapper. It's function is to allow you to customize the results of user searches. It is normally associated with an entire directory in which case it applies to all title, keyword, field, grep and context searches of that directory (see the chapter on searching.)

A line like 

     SearchWrapper=foo.html
in the directory record of an index file will cause any search of that directory to return an unorder list of matches wrapped with the file foo.html. The list of matches will be inserted into foo.html at a point where the marker <!-- #WN_include --> is found. You can also insert the user supplied search term by using the marker <!-- #WN_query -->. Both of these markers must occur on a line by themselves with no leading white space.

Nested Including and Wrapping

Wrapping and including can be arbitrarily nested (though this is not true of Search Wrappers). It can be a little complicated to get the effect you want.

Here is how to do it. Think of all your files, wrappers, includes and the main file arranged as you wish them to be combined for the final served document. Now imagine inserting a opening (or left) parenthesis at the beginning of each file and insert a closing (or right) parenthesis at the end of each file. You should have a legally nested and balanced collection of parentheses. To each of the opening parentheses attach the name of the file which begins at that point. Then write down the list of all the file names in the order their corresponding opening parentheses occur. All the files which come before the main file should be wrappers and should be listed in the Wrappers line in the order in which they occur in this list. All the files after the main file should be in the Includes line and should occur in the order they occur in this list.

Here's a simple example. Suppose we have a main file M and other files A,B,C, and D which we want to have nested like 

     (D...(B...B)...(M...(A...(C...C)...A)...M)...D)

Then the entry in the index file should look like 

     File=M
     Wrappers=D,B
     Includes=A,C

WN -- for those who think the Web should be more than a user friendly version of ftp

John Franks <john@math.nwu.edu>
[previous] [next] [top] [search] [index]