WebSiphon uses standard HTML files as its basic document format - no changes are needed to process any HTML file. However, to gain access to the real power and flexibility WebSiphon offers, the SiphonScript scripting language may be embedded directly into a document using special token characters to designate which sections, or blocks, of the document are HTML and which sections are SiphonScript. We define any document which contains SiphonScript code, and possibly HTML, as a template file.
Now that we have defined what a template is lets take a sample HTML document and add a few items to transform it into a template that will serve a dynamic page when requested from a browser.
Here is an HTML document which we will use for our examples:
Insertion Tokens<HTML> <HEAD><TITLE>WebSiphon Example</TITLE></HEAD> <BODY> <H1>WebSiphon Example</H1> <P> The current date is 11/21/00. <BR> The current time is 12:43 AM. </BODY> </HTML>
Obviously HTML example above does not produce anything special. Also the date and time will be wrong unless you hire a monkey to update the document every minute on the minute. So, we'll make this a dynamic document by adding a few of WebSiphon's built-in functions to insert the current date and time at the moment the page is served to a client. To do this, we use insertion token characters to insert the value of a variable or expression into the resulting HTML page. The insertion tokens are used in the HTML portion of a template, and begin with an open brace, "{", and end with a close brace, "}".
<HTML>
<HEAD><TITLE>WebSiphon Example</TITLE></HEAD>
<BODY>
<H1>WebSiphon Example</H1>
<P>
The current date is {currentDate()}.
<BR>
The current time is {currentTime()}.
<P>
Your machine's IP address is {client_ip_address}!
</BODY>
</HTML>
Now, when a user requests our page the exact date will be inserted in place of {currentDate()} and the exact time in place of {currentTime()}. In addition, we added another line which will insert the IP address of the client accessing the page, ie. "Your machine's IP address is 206.117.242.5!". Notice that there is a subtle difference between this new dynamic insertion of an IP address and the date and time insertions. The reason for this is because currentDate() and currentTime() are function calls and client_ip_address is a built-in variable. In addition to client_ip_address, there is a listing of all built-in variables available for use within any template in the section below.
Optional Insertion Tokens
Obviously, the use of { and } as insertion tokens can be a major concern to someone
using client-side JavaScript in their pages. The { and } characters in JavaScript code
get interpreted on the server-side by WebSiphon and will end up causing syntax errors when you try
to run the script.
Don't give up just yet. With WebSiphon 2.0.2, we've added an optional set of insertion tokens which addresses this situation. <?= and ?> are now synonymous with { and }. The optional escape sequences can be selected via the new #option directive (as shown below).
<<
#option sgml-escape
<< template_name: <?=template_name?> >>
#option brace-escape
<< template_name: {template_name} >>
>>
You can switch between the regular and optional insertion tokens anywhere in your template. The #option directive will stay in effect until it encounters another #option directive or until the end of the template. After the script executes, the #option directive reverts to the default state of using the { and } insertion tokens.
Now let's look at our example from above using the optional insertion tokens. You will notice this introduces the next section on block tokens (at the top of this example) where we need to escape from HTML mode and set the #option directive in SiphonScript.
<< #option sgml-escape >> <HTML> <HEAD><TITLE>WebSiphon Example</TITLE></HEAD> <BODY> <H1>WebSiphon Example</H1> <P> The current date is <?=currentDate()?>. <BR> The current time is <?=currentTime()?>. <P> Your machine's IP address is <?=client_ip_address?>! </BODY> </HTML>
Block Tokens (escaping from HTML)
As we saw in the example above, when adding script code to your templates you use
the other type of tokens WebSiphon recognizes, block token characters.
Block tokens are used to escape from HTML and putting you in "SiphonScript code mode".
The block tokens split a template into multiple sections, or blocks, of SiphonScript code and regular
HTML. The block tokens look much like standard HTML tags, but instead of a single <
or > character, two are used. To designate a block using these tokens, begin with
"<<" and end the block with ">>". Alternatively, the Macintosh extended
chevron characters may be used to designate blocks. The chevron symbols are yielded
with the key combinations option-backslash, "<<",
and shift-option-backslash, ">>".
|
<<
// WebSiphon Example Page
if user_agent contains "MSIE" then
the_browser = "Microsoft Internet Explorer";
else if user_agent contains "Mozilla" then
the_browser = "Netscape Navigator or Communicator";
else
the_browser = user_agent;
end if;
>>
<HTML>
<HEAD><TITLE>WebSiphon Example</TITLE></HEAD>
<BODY>
<H1>WebSiphon Example</H1>
<P>
The current date is {currentDate()}.
<BR>
The current time is {currentTime()}.
<P>
Your machine's IP address is {client_ip_address} and your
browser is {the_browser}!
</BODY>
</HTML>
With the above changes made to our template, we are actually including a bit of SiphonScript that figures out if the client is using a Microsoft or Netscape browser and reports this to the user. Looking at the above example, the first line after the opening block token is a single-line comment. Comments are just a simple way to document your scripts, and they are ignored by WebSiphon when it processes the template. The next part of the SiphonScript block uses an if/then statement to figure out what type of browser the client is using based on the user_agent built-in variable. The user_agent variable is a small string sent by a browser identifying what it is. So if the browser's identification contains the string "MSIE" we define a new variable named the_browser and set its value to "Microsoft Internet Explorer". However, if the browser's indentification does not match, we check to see if it contains the string "Mozilla" and if it matches set the_browser to "Netscape Navigator or Communicator". Lastly, if we were unable to match either of these cases we will just use the identification string sent by the browser itself by setting the_browser to the value of the built-in variable user_agent.
With that completed, we close out the SiphonScript block and make a small change in the HTML to report what browser the client is using by utilizing the insertion token to insert the value of our the_browser variable in the resulting page.
So what about results? Here is an example of the output produced when requesting this template with the Netscape Navigator browser.
Figure 1.1: Netscape Navigator example.
