Programmer's Guide to Enterprise Server 4.0
Table of Contents | Previous | Next | Index | Bookshelf

Programmer's Guide to Enterprise Server 4.0

Chapter 3. Server-Parsed HTML Tags

HTML files can contain tags that are executed on the server. In addition to supporting the standard server-side tags, Enterprise Server 4.0 allows you to define your own server-side tags.

This chapter has the following sections:

Note: The server parses server-side tags only if server-side parsing has been activated. Use the "Parse HTML" page in the Content Management tab of the Server Manager interface to enable or disable the parsing of server-side tags.

When you activate parsing, you need to be sure that the following directives are added to your obj.conf file (Note that native threads are turned off.): 
Init funcs="shtml_init,shtml_send" shlib="/bin/https/bin/ Shtml.dll" NativeThreads="no" fn="load-modules"

Init LateInit = "yes" fn="shtml_init"

Using Server-Side HTML Commands

This section describes the HTML commands for including server-parsed tags in HTML files. These commands are embedded into HTML files which are processed by the built-in SAF parse-html.

The server replaces each command with data determined by the command and its attributes.

The format for a command is:

<!--#command attribute1 attribute2 ... -->
The format for each attribute is a name-value pair such as:

name="value"
Commands and attribute names should be in lower case.

The commands are "hidden" within HTML comments so they are ignored if not parsed by the server.The standard server-side commands are:

config

The config command initializes the format for other commands.

This sets the date format to a value such as 08:23:15 AM Wed Apr 15, 1996, and the file size format to the number of KB or MB of characters used by the file.

include

The include command inserts a file into the parsed file (it can't be a CGI program). You can nest files by including another parsed file, which then includes another file, and so on. The client requesting the parsed document must also have access to the included file if your server uses access control for the directories where they reside.

echo

The echo command inserts the value of an environment variable. The var attribute specifies the environment variable to insert. If the variable is not found, "(none)" is inserted. For a list of environment variables, see the section "Environment Variables in Server-Side HTML Commands."

Example

<!--#echo var="DATE_GMT"-->

fsize

The fsize command sends the size of a file. The attributes are the same as those for the include command (virtual and file). The file size format is determined by the sizefmt attribute in the config command.

Example

<!--#fsize file="bottle.gif"-->

flastmod

The flastmod command prints the date a file was last modified. The attributes are the same as those for the include command (virtual and file). The date format is determined by the timefmt attribute in the config command.

Example

<!--#flastmod file="bottle.gif"-->

exec

The exec command runs a shell command or CGI program.

Environment Variables in Server-Side HTML Commands

In addition to the normal set of environment variables used in CGI, you may include the following variables in your parsed commands:

Defining Customized Server-Parsed HTML Tags

The parsing of server-side tags in .shtml files in Enterprise Server 4.0 has been substantially improved over previous releases of Enterprise Server. First, the performance of handling server-side tags has been significantly speeded up. Secondly, users can now define their own server-side tags.

For example, you could define the tag <PRICE> to invokes a function that calculates and displays the price of a product. Then in your .shtml file you could have code such as:

<H2>Product Prices</H2> 
<UL> 
<LI>Oak Table: <PRICE product="oaktable"> 
<LI>Pine Bench: <PRICE product="pinebench"> 
<LI>Patio Chair: <PRICE product="patiochair"> 
</UL>
When the browser displays this code, each occurrence of the <PRICE> tag calls the function that is associated with that tag, and returns the price of the relevant product. The result in the browser might look like:

Product Prices

The Mechanics

The steps for defining a customized server-parsed tag are:

  1. Define the Functions that Implement the Tag.
    2. You must define the tag execution function, and you can optionally also define other functions that are called on tag loading and unloading and on page loading and unloading.

  2. Write an Initialization Function to Register the New Tag.
    3. Write an initialization function that registers the tag using the shtml_add_tag function.

  3. Load the New Tag into the Server.

Define the Functions that Implement the Tag

Define the functions that implement the tags in C, using NSAPI.

ShtmlTagExecuteFunc is the actual tag handler. It gets called with the usual NSAPI pblock, Session and Request variables. In addition, it also gets passed the TagUserData created from the result of executing the tag loading and page loading functions (if defined) for that tag.

The signature for the tag execution function is:

typedef int (*ShtmlTagExecuteFunc)(
pblock*, Session*, Request*, TagUserData, TagUserData);
Write the body of the tag execution function to generate the output to replace the tag in the .shtml page. Do this in the usual NSAPI way, using the net_write() NSAPI function, which writes a specified number of bytes to a specified socket from a specified buffer.

For more information about writing NSAPI plugins see Chapter 4, "Writing Custom SAFs" in the NSAPI Programmer's Guide at:

http://developer.netscape.com/docs/manuals/enterprise/nsapi/4.0/index.htm
For more information about net_write() and other NSAPI functions, see Chapter 5, "NSAPI Function Reference" of the NSAPI Programmer's Guide.

The tag execution function must return an int that indicates whether the server should proceed to the next instruction in obj.conf or not, which is one of:

The other functions you can define for your tag are:

The signatures for these functions are:

#define TagUserData void*
typedef TagUserData (*ShtmlTagInstanceLoad)(
   const char* tag, pblock*, const char*, size_t);
typedef void (*ShtmlTagInstanceUnload)(TagUserData);
typedef int (*ShtmlTagExecuteFunc)(
   pblock*, Session*, Request*, TagUserData, TagUserData);
typedef TagUserData (*ShtmlTagPageLoadFunc)(
   pblock* pb, Session*, Request*);
typedef void (*ShtmlTagPageUnLoadFunc)(TagUserData);

Write an Initialization Function to Register the New Tag

In the initialization function for the shared library that defines the new tag, register the tag using the function shtml_add_tag(). The signature is:

NSAPI_PUBLIC int shtml_add_tag (
   const char* tag, 
   ShtmlTagInstanceLoad ctor,
   ShtmlTagInstanceUnload dtor,
   ShtmlTagExecuteFunc execFn,
   ShtmlTagPageLoadFunc pageLoadFn,
   ShtmlTagPageUnLoadFunc pageUnLoadFn);
Any of these arguments can be NULL except for the tag and execFn.

Load the New Tag into the Server

After creating the shared library that defines the new tag, you load the library into the Enterprise Server in the usual way for NSAPI plugins.That is, add the following directives to the configuration file obj.conf:

  1. Add an Init directive whose fn parameter is load-modules and whose shlib parameter is the shared library to load. This directive must have native threads turned off. You could use a directive similar to this:
    2. Init funcs="shtml_init,shtml_send" shlib="<install_dir>/bin/https/bin/Shtml.dll" NativeThreads="no" fn="load-modules"

  2. Add a directive to set LateInit for shtml_init:
    3. Init LateInit = "yes" fn="shtml_init"

  3. Add another Init directive whose fn parameter is the initialization function in the shared library that uses shtml_add_tag() to register the tag.
Table of Contents | Previous | Next | Index | Bookshelf

Last Updated: 08/12/99 12:35:17

Copyright ©1999 Netscape Communications Corp. All rights reserved.