6.6 Diversion

In the process of making the HTML files, WML implements a text diversion filter . That bit of jargon means that a section of text can be created in one place in a file, or in a completely separate file, and then included somewhere else within the HTML. This is most helpful with templates, because a template is an HTML file that usually defines the outer HTML (the top, sides, and bottom), and the inner HTML (the page contents) is in a separate file.

This is one syntax to create a diversion:

 ..DIVERSION>>This is the diversion text<<..

The marker ..DIVERSION>> begins the text. The name DIVERSION is all uppercase by convention. The diversion does not have to be named DIVERSION ; it can be named anything you want as long as the name begins with an alpha and is followed by zero or more alphas, digits, or underscores, upper-or lowercase. The text in the diversion continues until the end-of-diversion marker <<.. is found.

To use the diversion later (or even before its definition) use this:

 <<DIVERSION>>

This causes the text in the definition to be included at this point.

An example can be found in /var/www/html/wml/diversion.wml :

 ..NAME>>John Doe<<..  Hello <<NAME>>!  <br>  Here is my message: <<MSG>>  ..MSG>>  WML is cool!  <<..

The example starts with a diversion definition for NAME , "John Doe." The next line uses the diversion <<NAME>> in the text:

 Hello <<NAME>>!

This line becomes this, after WML is finished processing:

 Hello John Doe!

The definition of NAME comes before its use. That's fine. The next line, however, uses a diversion not yet defined:

 Here is my message: <<MSG>>

The diversion for MSG is defined after it is used. That's kosher ”because WML is a multipass process, the definition can be before or after. This definition:

 ..MSG>>  WML is cool!  <<..

spans multiple lines. That's fine too ”you are free to add whitespace as needed or desired.

To build the HTML, make the WML in the usual fashion:

 $  wmk diversion.wml  wml -n -o diversion.html diversion.wml

The resulting HTML file is:

 Hello John Doe!  <br>  Here is my message:  WML is cool!

If you want to see this example, check out http://localhost/wml/diversion.html or www.opensourcewebbook.com/wml/diversion.html.

There are other diversion syntaxes as well. One such syntax is:

 # create the diversion to use later  {#NAME#:  John Doe  :##}  # use the diversion  My name is: {#NAME#}!

This is another syntax, which requires the use of wml::std::tags :

 #use wml::std::tags  <divert NAME>John Doe</divert>  My name is: <dump NAME>!

We most often use the ..NAME>> ... <<.. syntax, but on occasion we use the <divert NAME> ... </divert> syntax ”TMTOWTDI (in WML as well as in Perl and most things LAMP).