With WML, it is straightforward to create and maintain an overall look-and-feel template for a web site. HTML code for specific sections of the page can be included on every page so that the header, footer, left and right rails, etc., look the same on every page:
#include header.wml #include "banner.wml"
WML makes an important distinction between single and double quotes. Single quotes mean that the file is loaded from the current working directory only, which can be used to force the loading of the local file. If double quotes are used, WML searches for the file in all the directories listed after the -I option ( include ). By default, the current working directory is searched first. Next , if the file is not found, directories are searched in the order specified by the -I option, and the first filename matched is used. In the previous example, if there is a banner.wml in the current working directory, it is the one used.
Let's start with a simple example that includes a header and a footer. Just for a change, the body of the file prints "hello, world!" The header file /var/www/html/wml/head1.wml is simply basic HTML that is at the head of an HTML page:
<html> <head> <title>WML hello1.wml</title> </head> <body bgcolor=#ffffff>
Similarly, the footer ( /var/www/html/wml/foot1.wml ) is:
Again, that is just simple HTML that gracefully ends the code started in head1.wml .
The WML program is /var/www/wml/hello1.wml :
#include "head1.wml" hello, world! #include "foot1.wml"
When invoked, wmk calls wml , which during Pass 1 includes head1.wml ; then adds the body, "hello, world!" from hello1.wml ; and finally includes foot1.wml .
To build the HTML, execute the wmk command:
$ wmk hello1.wml wml -n -o hello1.html hello1.wml
That generates /var/www/html/wml/hello1.html , the contents of which are:
<html> <head> <title>WML hello1.wml</title> </head> <body bgcolor="#ffffff"> hello, world! </body> </html>
Load this in the browser by going to either http://localhost/wml/hello1.html or www.opensourcewebbook.com/wml/hello1.html. The result can be seen in Figure 6.1.
Figure 6.1. hello, world! Version 1 with WML
The two blank lines above and below the text "hello, world!" in hello1. wml did not end up in the resulting hello1.html , because one feature of WML is to remove any extraneous characters , such as whitespace.
Also, in head1.wml the background color #ffffff did not have double quotes around it, as it should in valid HTML, so WML is kind enough to put the proper quotes in the resulting hello1.html . This is a very nice feature of WML, though of course one shouldn't rely on it to fix everything.
6.4.1 Varying the Template Files
Although all this is static HTML, not every page will have the same title. WML allows you to pass parameters to the files:
#include "head.wml" title="Just Say Hello"
Then, in the WML file head.wml , the value passed is available as $(title) (these WML variables look just like those in a shell program). Those parentheses are important. It's $(title) , not $title .
The new header file using the passed parameter is /var/www/html/wml/head2.wml . Between the <title> tags the value of $(title) is evaluated. In this example, the background color is also passed into the file through $(bgcolor) .
<html> <head> <title>$(title)</title> </head> <body bgcolor=$(bgcolor:-"#ffffff")>
The background color is set with the syntax $(bgcolor:-"#ffffff") . This shell-like syntax means "use the value of $(bgcolor) if it has a value, else use the default value #ffffff ." 
Similarly, in the footer /var/www/html/wml/foot2.wml , the author can be supplied through the $(author) variable:
<hr> Written by: <b>$(author)</b> </body> </html>
The WML file that includes these two files is /var/www/html/wml/hello2.wml :
#include "head2.wml" title="WML hello2.wml" hello, world! <hr> <pre> here is some preformatted text </pre> #include "foot2.wml" author="Ron Ballard"
To build the HTML, use:
$ wmk hello2.wml wml -n -o hello2.html hello2.wml
The result is written to /var/www/html/wml/hello2.html (via the -o hello2.html switch). In this case, hello2.wml does not pass the background color into head2.wml , so the default value #ffffff is used.
<html> <head> <title>WML hello2.wml</title> </head> <body bgcolor="#ffffff"> hello, world! <hr>
here is some
Written by: <b>Ron Ballard</b>
Here the title ends up between the <title> tags, the background color is in the <body> tag, and the author is in the footer area between the <b> ... </b> tags.
Again, the unnecessary whitespace disappears ”newlines, extra spaces. Even the extra whitespace characters in this line:
Written by: <b>$(author)</b>
But the important whitespace within the <pre> ... </pre> tags is maintained . Cool, huh?
To see this program in action, go to either http://localhost/wml/hello2.html or www.opensourcewebbook.com/wml/hello2.html. The result can be seen in Figure 6.2.
Figure 6.2. hello, world! Version 2 with WML
6.4.2 The use Statement
As the WML system gets more complicated, it's easy to imagine that a file could be include d more than once if the programmer were to lose track of things.
To preclude this situation, one can implement the #use directive instead of the #include . The statement:
is written with #use as:
Similarly, this statement:
#include "directory/file.wml" name="John Doe"
is written with #use as:
#use wml::directory::file name="John Doe"
Since use is more useful, we'll forget about include for everything else we do with WML.
WML comes with many standard files for commonly used functions. They are usually use d like this:
This specifies the file info.wml in the standard WML system include directory /usr/local/lib/wml/include/std/ . This particular file includes definitions of information about the page. The information is made available by using the <info> tag. This standard include file allows us to include comments in the file, such as who wrote the file.
An example of wml::std::info is just around the corner.
Other information can be added to the HTML file, such as the filename ( __FILE__ ) and the line number in the file ( __LINE__ ). This information is useful for debugging but less so for security. Think carefully before advertising the name of the file to all the possible crackers out there.
Comments are begun with the pound sign ( # ), with the obvious exception of statements such as #include and #use . The end-of-line ends the comments, so each new line of the comment must begin with a new # . Lines that have a pound sign after only whitespace are comments, too. If the # occurs anywhere except at the beginning of the line or after whitespace, it is not treated as a comment. For example:
# here is a comment # another comment # here is a comment preceded by only whitespace this is not a # comment and will be compiled by WML
You can also add a marker to the file ( __END__ ) that indicates that the WML code is finished. Any text that follows is thus a comment and not compiled as WML code.
To illustrate all these concepts, let's look at another variation of "hello, world!" The header file is /var/www/html/wml/head3.wml :
# use std/info.wml so we can use # the <info> tag #use wml::std::info <html> <head> <info style=comment domainname="opensourcewebbook.com" copyright="2002 James Lee, Brent Ware http://www.opensourcewebbook.com/"> <title>$(title)</title> </head> <body bgcolor=$(bgcolor:-"#ffffff")> <h3>Header Stuff</h3> File: <b>__FILE__</b><br> Line: <b>__LINE__</b>
This header uses wml::std::info so that we can use the <info> tag. The tag includes information about the file using the comment style (all the information is within an HTML comment). This file also prints the filename ( __FILE__ ) and line number ( __LINE__ ). Similarly, we can use these in the footer in /var/www/html/wml/foot3.wml :
<hr> <h3>Footer Stuff</h3> Written by: <b>$(author)</b> <br> File: <b>__FILE__</b><br> Line: <b>__LINE__</b> </body> </html>
The only new thing here is the use of __FILE__ and __LINE__ .
Here is the WML file that will use these two files, /var/www/html/wml/hello3.wml :
#use head3.wml, setting the background color to #ffffcc #use wml::head3 title="WML hello3.wml" bgcolor="#ffffcc" # here is the body stuff <h3>Body Stuff</h3> hello, world!<br> File: <b>__FILE__</b><br> Line: <b>__LINE__</b> # here is the footer #use wml::foot3 author="Ron Ballard" __END__ After the above marker, we can put any text in the file and it would be treated as a comment.
Note the generous use of comments. Values are passed into head3.wml , including a value for the background color. The body HTML is written, including __FILE__ and __LINE__ . Then the footer is use d, including the author's name. Finally, after the __END__ marker, a section can be added for additional comments.
The following command generates the HTML:
$ wmk hello3.wml wml -n -o hello3.html hello3.wml
which looks like this ( hello3.html ):
<html> <head> <!-- Copyright (c) 2002 James Lee, Brent Ware http://www.opensourcewebbook.com/ Author: James Lee (firstname.lastname@example.org) Modified: 2002-01-25 07:22:57. Generated from ``hello3.wml via WML 2.0.8 (30-Oct-2001). by James Lee (email@example.com) on 2002-01-25 07:22:59. DO NOT EDIT THIS FILE DIRECTLY! INSTEAD EDIT ``hello3.wml. --> <title>WML hello3.wml</title> </head> <body bgcolor="#ffffcc"> <h3>Header Stuff</h3> File: <b>./head3.wml</b><br> Line: <b>14</b> <h3>Body Stuff</h3> hello, world!<br> File: <b>./hello3.wml</b><br> Line: <b>14</b> <hr> <h3>Footer Stuff</h3> Written by: <b>Ron Ballard</b><br> File: <b>./foot3.wml</b><br> Line: <b>5</b> </body> </html>
One useful reminder that we got for free with the <info> tag was the inclusion of this comment in the header:
DO NOT EDIT THIS FILE DIRECTLY! INSTEAD EDIT ``hello3.wml.
which should be perfectly obvious in its meaning. Any changes made to hello3.html will be overwritten the next time wmk is run. WML Rule Number 1 is "change only the .wml files."
To see what the HTML looks like, go to http://localhost/wml/hello3.html or www.opensourcewebbook.com/wml/hello3.html. The result can be seen in Figure 6.3.
Figure 6.3. hello, world! Version 3 with WML