Sun Java System Web Server 6.1 SP11 Programmer's Guide

Defining Customized Server-parsed HTML Tags

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

ProcedureTo define a customized server-parsed tag

  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 implements the tag in C, using NSAPI.

The other functions you must 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);

         

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 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 Sun Java System 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="install_dir/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"