Chapter 6 Creating
Custom Server-parsed HTML Tags

In Sun Java System Web Server 6.1, you can define your 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.

Define the Functions that Implement the Tag

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

Link against the SHTML shared library. On Windows, shtml.dll is in install_dir/bin. On UNIX platforms, libshtml.so or .sl is in install_dir/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.

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.

The tag execution function must
return an int that indicates whether the server should proceed to the next
instruction in obj.conf, 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. 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.

Load the New Tag into the Server

After creating the shared library that defines the new tag, you load
the library into the Sun Java System Web Server in the usual way for NSAPI
plug-ins. Add the following directives to the configuration file magnus.conf:

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: