HTML files can contain tags that are executed on the server. In addition to supporting the standard server-side tags, Web Server allows you to embed servlets and define your own server-side tags.
This chapter has the following sections:
The server parses server-side tags only if server-side parsing has been enabled. The following procedure describes how to enable server-side parsing using the Administration interface.
Login to Admin Console
Access the Edit Virtual Server , and click the Content Handling tab.
Click the General tab in the Content Handling screen.
Select the options to enable the server-parsed HTML and with exec tag.
In the parsed files drop-down list, select a resource for which the server will parse HTML.
Choose the virtual server or a specific directory within the virtual server. If you choose a directory, the server will parse HTML only when the server receives a URL for that directory or any file in that directory.
Choose the files to parse.
Files with the extension .shtml. The server parses only files with the extension .shtml. This option is the most common (and default) choice.
Files with the execute bit and the extension .html. (Unix and Linux only) The server parses files whose UNIX and Linux permissions specify that the execute bit is on. Using the execute permissions can be unreliable because in some cases the bit is set on files that are not executable.
All HTML files. The server parses all HTML files. Choosing this option can slow server performance.
Click Save.
Add the following directives are added to the magnus.conf file. Set NativeThread="no" for Web Server.
In addition, these functions now originate from Shtml.dll (or libShtml.so on UNIX), which is located in install_dirC:\Program Files\Sun\WebServer7 for Windows, and install_dir/sun/webserver7 for UNIX.
To enable parsing of server-side tags for files with extensions other than .shtml, add the extension to the appropriate line in the mime.types file.
For example, the following line in mime.types indicates that files with either a .shtml or .jbhtml extension are parsed for server-side tags:
type=magnus-internal/parsed-html exts=shtml,jbhtml |
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.
<!--#command attribute1 attribute2 [Please define the ellipsis text entity] -->
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 listed below, and described in this section:
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". For more information about time formats, see the Time Formats.
The sizefmt attribute determines the format of the file size for the fsize command. It can have one of these values:
<!--#config timefmt="%r %a %b %e, %Y" sizefmt="abbrev"-->
This example sets the date format to a value such as 10:45:35 AM Wed Apr 21, 2006, and the file size format to the number of KBytes or MBytes of characters used by the file.
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 in which they reside.
In Web Server, 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 file attribute is a relative path name from the current directory. It cannot contain elements such as ../ and it cannot be an absolute path.
<!--#include file="bottle.gif"-->
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 Environment Variables in Server-side HTML Commands.
<!--#echo var="DATE_GMT"-->
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.
<!--#fsize file="bottle.gif"-->
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.
<!--#flastmod file="bottle.gif"-->
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.
<!--#exec cgi="workit.pl"-->
In addition to the standard set of environment variables used in CGI, you can include the following variables in your parsed commands:
DOCUMENT_URI — Virtual path to the parsed file, for example, /shtml/test.shtml
QUERY_STRING_UNESCAPED — Unescaped version of any search query the client sent with all shell-special characters escaped with the slash character
DATE_GMT — Current date and time expressed in GMT (Greenwich Mean Time)
Web Server supports the <servlet> tag. This tag enables 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 in that 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:
The value of the url-pattern element defined in the web.xml file for the web application. For more information about web.xml, see the Java Servlet 2.4 specification (chapter SRV .13, “Deployment Descriptor”). You can find the specification at http://java.sun.com/products/servlet/download.html.
The value of the uri attribute defined in the web-apps.xml file for the web application.
For example, say you want to include the following servlet in your .shtml SHTML file:
<servlet name=pparams code="/PrintApp/PrintParams"> </servlet>
You need to include the following definition in your web-apps.xml file:
<web-app uri="/PrintApp" dir="/iws60/https-server.iplanet.com/acme.com/webapps/PrintApp"/>
You also need to include the following definition 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 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.
In Web Server , 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.
Defining the Functions that Implement a 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.
Write an initialization function that registers the tag using the shtml_add_tag function.
Loading a New Tag Into the Server.
These actions are described in the sections that follow.
Define the functions that implement the tags in C, using NSAPI.
Include the header shtml_public.h, which is in the directory install_dir/libinclude/shtml.
Link against the shtml shared library. On Windows, shtml.dll is in install_dir/lib 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.
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 by using the net_write NSAPI function. This function writes a specified number of bytes to a specified socket from a specified buffer.
For more information about NSAPI plugins and functions, see the Sun Java System Web Server 7.0 Update 6 NSAPI Developer’s Guide.
The tag execution function must return an int that indicates whether the server should proceed to the next instruction in obj.conf:
REQ_EXIT— The connection was lost
The other functions you must define for your tag are:
ShtmlTagInstanceLoad— Called when a page containing the tag is parsed. It is not called if the page is retrieved from the browser’s cache. This function basically serves as a constructor, the result of which is cached and is passed into ShtmlTagExecuteFunc whenever the execution function is called.
ShtmlTagInstanceUnload— 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 function enables you to make information persistent between occurrences of the same tag on the same page.
ShtmlTagPageUnLoadFn— Called after a page containing the tag has executed and gets passed the result returned from the ShtmlTagPageLoadFunc.
The signatures for these functions are:
The following example 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 */
To Reviewer: please review the above given code.
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.
After creating the shared library that defines the new tag, you load the library into Web Server by adding the following directives to the configuration file magnus.conf:
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, would be:Init funcs="mytag,mytag_init" shlib="install_dir/hello.so" fn="load-modules"
An 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"
The following table describes the format strings for dates and times used by server-parsed HTML.
Table 2–1 Time Formats
Symbol |
Meaning |
---|---|
%a | |
%d | |
%S |
Second as decimal number (00-59) |
%M |
Minute as decimal number (00-59) |
%H |
Hour in 24-hour format (00-23) |
%Y |
Year with century, as decimal number, up to 2099 |
%b | |
%h |
Abbreviated month name (3 characterss) |
%T |
Time "HH:MM:SS" |
%X |
Time "HH:MM:SS" |
%A |
Full weekday name |
%B |
Full month name |
%C |
"%a %b %e %H:%M:%S %Y" |
%c |
Date & time "%m/%d/%y %H:%M:%S" |
%D |
Date "%m/%d/%y" |
%e |
Day of month as decimal number (1-31) without leading zeros |
%I |
Hour in 12-hour format (01-12) |
%j |
Day of year as decimal number (001-366) |
%k |
Hour in 24-hour format (0-23) without leading zeros |
%l |
Hour in 12-hour format (1-12) without leading zeros |
%m |
Month as decimal number (01-12) |
%n |
Line feed |
%p |
A.M./P.M. indicator for 12-hour clock |
%R |
Time "%H:%M" |
%r |
Time "%I:%M:%S %p" |
%t |
Tab |
%U |
Week of year as decimal number, with Sunday as first day of week (00-51) |
%w |
Weekday as decimal number (0-6; Sunday is 0) |
%W |
Week of year as decimal number, with Monday as first day of week (00-51) |
%x |
Date "%m/%d/%y" |
%y |
Year without century, as decimal number (00-99) |
%% |
Percent sign |