Previous     Contents     Index     DocHome     Next     
iPlanet Web Server, Enterprise Edition Programmer's Guide



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, iPlanet Web Server 6.0 allows you to embed servlets and define your own server-side tags.

This chapter has the following sections:

  • Using Server-Side HTML Commands

  • Embedding Servlets

  • Defining Customized Server-Parsed HTML Tags


    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 Class Manager interface to enable or disable the parsing of server-side tags. (To display the Class Manager, select the Manage Classes page on the Virtual Server Class tab in the Server Manager, select a class from the list, then select the Manage button.)


When you activate parsing, you need to be sure that the following directives are added to your magnus.conf file (note that native threads are turned off):

Init funcs="shtml_init,shtml_send" shlib="install_dir/bin/https/bin/Shtml.dll" NativeThreads="no" fn="load-modules"

Note that you must set NativeThread="no" for 6.0 iPlanet Web Servers. In addition, these functions now originate from Shtml.dll (or libShtml.so on Unix), which is located in install_dir/bin/https/bin for Windows NT (and install_dir/bin/https/lib for Unix).

In addition, be sure that the following directive is added to your obj.conf file:

<Object name="default">
...
...
Service fn="shtml_send" type="magnus-internal/parsed-html" method="(GET|HEAD)"
...
</Object>



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 <Body>... -->

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.

  • The errmsg attribute defines a message sent to the client when an error occurs while parsing the file. This error is also logged in the error log file.

  • The timefmt attribute determines the format of the date for the flastmod command. It uses the same format characters as the util_strftime function. The default time format is: "%A, %d-%b-%y %T".

    Refer to the Time Formats appendix in the NSAPI Programmer's Guide for iPlanet Web Server for details about time formats.

  • The sizefmt attribute determines the format of the file size for the fsize command. It can have one of these values:

    • bytes to report file size as a whole number in the format 12,345,678.

    • abbrev (the default) to report file size as a number of KB or MB.

Example:

<!--#config timefmt="%r %a %b %e, %Y" sizefmt="abbrev"-->

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. 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.

In iPlanet Web Server 6.0, you can use the include command with the virtual attribute to include a CGI program file. You must also use an exec command to execute the CGI program.

  • The virtual attribute is the URI of a file on the server.

  • The file attribute is a relative path name from the current directory. It cannot contain elements such as ../ and it cannot be an absolute path.

Example:

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


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.

  • The cmd attribute (Unix only) runs a command using /bin/sh. You may include any special environment variables in the command.

  • The cgi attribute runs a CGI program and includes its output in the parsed file.

Example:

<!--#exec cgi="workit.pl"-->


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:

  • DOCUMENT_NAME

    is the file name of the parsed file.

  • DOCUMENT_URI

    is the virtual path to the parsed file (for example, /shtml/test.shtml).

  • QUERY_STRING_UNESCAPED

    is the unescaped version of any search query the client sent with all shell-special characters escaped with the \ character.

  • DATE_LOCAL

    is the current date and local time.

  • DATE_GMT

    is the current date and time expressed in Greenwich Mean Time.

  • LAST_MODIFIED

    is the date the file was last modified.



Embedding Servlets

iPlanet Web Server 6.0 supports the <SERVLET> tag as introduced by Java Web Server. This tag allows you to embed servlet output in an SHTML file. No configuration changes are necessary to enable this behavior. If SSI and servlets are both enabled, the <SERVLET> tag is enabled.

The <SERVLET> tag syntax is slightly different from that of other SSI commands; it resembles the <APPLET> tag syntax:

<servlet name=name code=code codebase=path iParam1=v1 iParam2=v2>
<param name=param1 value=v3>
<param name=param2 value=v4>
.
.
</servlet>

If the servlet is part of a web application, the code parameter is required and other parameters are ignored. The code parameter must include:

For example, if you wanted to include the following in your SHTML file:

<servlet name=pparams code="/PrintApp/PrintParams">
</servlet>

you would need to include the following in your web-apps.xml file:

<web-app uri="/PrintApp" dir="/iws60/https-server.iplanet.com/acme.com/webapps/PrintApp"/>

you would also need to include the following in your web.xml file:

<servlet>
   <servlet-name> pparams </servlet-name>
   <servlet-class> PrintPackage.PrintParams </servlet-class>
</servlet>
<servlet-mapping>
   <servlet-name> pparams </servlet-name>
   <url-pattern> /PrintParams </url-pattern>
</servlet-mapping>

You must also include any servlet initialization parameters in the web.xml file.

For legacy (iPlanet Web Server 4.x) servlets, the code parameter specifies the .class file for the servlet and is required. The codebase parameter is required if the servlet is not defined in the servlets.properties file and the .class file is not in the same directory as the HTML file containing the <SERVLET> tag. Legacy servlets must be configured in the default virtual server and do not require a web.xml file.

For more information about creating servlets, see the Programmer's Guide to Servlets in iPlanet Web Server.



Defining Customized Server-Parsed HTML Tags


In iPlanet Web Server 6.0, users can define their own server-side tags. For example, you could define the tag HELLO to invoke a function that prints "Hello World!" You could have the following code in your hello.shtml file:

<html>
<head>
<title>shtml custom tag example</title>
</head>
<body>
<!--#HELLO-->
</body>
</html>

When the browser displays this code, each occurrence of the HELLO tag calls the function.


The Mechanics

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

  1. Define the Functions that Implement the Tag.

    You must define the tag execution function. You must 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.

    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.

  • Include the header shtml_public.h, which is in the directory install_dir/plugins/include/shtml.

  • Link against the shtml shared library. On Windows NT, shtml.dll is in install_dir/bin/https/bin. On Unix platforms, libshtml.so or .sl is in install_dir/bin/https/lib.

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, "Creating Custom SAFs," in the NSAPI Programmer's Guide for iPlanet Web Server.

For more information about net_write and other NSAPI functions, see Chapter 5, "NSAPI Function Reference," of the NSAPI Programmer's Guide for iPlanet Web Server.

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:

  • REQ_PROCEED -- the execution was successful.

  • REQ_NOACTION -- nothing happened.

  • REQ_ABORTED -- an error occurred.

  • REQ_EXIT -- the connection was lost.

The other functions you must define for your tag are:

  • ShtmlTagInstanceLoad

    This is called when a page containing the tag is parsed. It is not called if the page is retrieved from the browser's cache. It basically serves as a constructor, the result of which is cached and is passed into ShtmlTagExecuteFunc whenever the execution function is called.

  • ShtmlTagInstanceUnload

    This is basically a destructor for cleaning up whatever was created in the ShtmlTagInstanceLoad function. It gets passed the result that was originally returned from the ShtmlTagInstanceLoad function.

  • ShtmlTagPageLoadFunc

    This is called when a page containing the tag is executed, regardless of whether the page is still in the browser's cache or not. This provides a way to make information persistent between occurrences of the same tag on the same page.

  • ShtmlTagPageUnLoadFn

    This is called after a page containing the tag has executed. It provides a way to clean up any allocations done in a ShtmlTagPageLoadFunc and hence gets passed the result returned from the ShtmlTagPageLoadFunc.

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);

Here is the code that implements the HELLO tag:

/*
 * mytag.c: NSAPI functions to implement #HELLO SSI calls
 *
 *
 */

#include "nsapi.h"
#include "shtml/shtml_public.h"

/* FUNCTION : mytag_con
 *
 * DESCRIPTION: ShtmlTagInstanceLoad function
 */
#ifdef __cplusplus
extern "C"
#endif
TagUserData
mytag_con(const char* tag, pblock* pb, const char* c1, size_t t1)
{
   return NULL;
}

/* FUNCTION : mytag_des
 *
 * DESCRIPTION: ShtmlTagInstanceUnload
 */
#ifdef __cplusplus
extern "C"
#endif
void
mytag_des(TagUserData v1)
{

}

/* FUNCTION : mytag_load
 *
 * DESCRIPTION: ShtmlTagPageLoadFunc
 */
#ifdef __cplusplus
extern "C"
#endif
TagUserData
mytag_load(pblock *pb, Session *sn, Request *rq)
{
   return NULL;
}

/* FUNCTION : mytag_unload
 *
 * DESCRIPTION: ShtmlTagPageUnloadFunc
 */
#
#ifdef __cplusplus
extern "C"
#endif
void
mytag_unload(TagUserData v2)
{

}

/* FUNCTION : mytag
 *
 * DESCRIPTION: ShtmlTagExecuteFunc
 */
#ifdef __cplusplus
extern "C"
#endif
int
mytag(pblock* pb, Session* sn, Request* rq, TagUserData t1, TagUserData t2)
{
   char* buf;
   int length;
   char* client;
   buf = (char *) MALLOC(100*sizeof(char));
   length = util_sprintf(buf, "<h1>Hello World! </h1>", client);
   if (net_write(sn->csd, buf, length) == IO_ERROR)
   {
      FREE(buf);
      return REQ_ABORTED;
   }
   FREE(buf);
   return REQ_PROCEED;
}

/* FUNCTION : mytag_init
*
* DESCRIPTION: initialization function, calls shtml_add_tag() to
* load new tag
*/
#
#ifdef __cplusplus
extern "C"
#endif
int
mytag_init(pblock* pb, Session* sn, Request* rq)
{
   int retVal = 0;
// NOTE: ALL arguments are required in the shtml_add_tag() function
   retVal = shtml_add_tag("HELLO", mytag_con, mytag_des, mytag, mytag_load, mytag_unload);

   return retVal;
}
/* end mytag.c */


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 return 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 iPlanet Web Server in the usual way for NSAPI plugins. That is, add the following directives to the configuration file magnus.conf:

  1. Add an Init directive whose fn parameter is load-modules and whose shlib parameter is the shared library to load. For example, if you compiled your tag into the shared object install_dir/hello.so, it would be:

    Init funcs="mytag,mytag_init" shlib="installdir/hello.so" fn="load-modules"

  2. Add another Init directive whose fn parameter is the initialization function in the shared library that uses shtml_add_tag to register the tag. For example:

    Init fn="mytag_init"


Previous     Contents     Index     DocHome     Next     
Copyright © 2001 Sun Microsystems, Inc. Some preexisting portions Copyright © 2001 Netscape Communications Corp. All rights reserved.

Last Updated May 14, 2001