Commands Issued by Zim Server to ZimWeb

The output from the Zim Server agent is sent to ZimWeb and then to the client (web browser, cellphone, tablet, etc.). However, there are various commands that can be used to control how the Zim application output is processed, and how ZimWeb behaves.

ZimWeb expects that the Zim application will output a series of ZimWeb commands (one per line), a blank line, and then the actual content.

To send HTML to a web browser, the beginning of the application's output should be:

 

content-type:text/html

 

<html>

etc...

 

N.B. The blank line between the content-type: line and the start of the content is very important!

Commands are not case sensitive. In case you are wondering about the content-type line, it is not send directly to the web browser.

Commands Organized by Function Type

Content processing
content-type:<mime> Sets the response content type to <mime>.
You do not need to set this if you are applying an XSLT stylesheet with the apply-xslt: command and the ZimWeb is configured to use the output type specified in the stylesheet's output method.
If this is specified, and a stylesheet is being applied, then the content type specified will override the stylesheet's output method.
If the ZimWeb cannot determine the content type, it will assume it is text/html, except if the client requests no styling (parameter STYLE=none), then, if there is no content-type: command, the content will be assumed to be XML (mime type text/xml), since you can only style XML.
If that all sounds rather complicated, it's just trying to express explicitly some fairly reasonable and benign assumptions.
apply-xslt:<stylesheet> Apply XSLT stylesheet <stylesheet> to the Zim agent output.
The <stylesheet> parameter is a file path relative to the base path of the ZII application. If you have installed the ZimWeb in the manner described in the installation instructions then specifying the <stylesheet> as /styles/cool.xsl will refer to the file [TOMCAT_ROOT]/zii/styles/cool.xsl.
The <stylesheet> parameter can be overridden by the input parameter STYLE.
The ZimWeb automatically compiles and caches XSLT stylesheets in memory for maximum performance.
N.B. The ZII does not accept a URI for the stylesheet as running a stylesheet not under your control could be a security hazard.
apply-page-template:<form-template> Apply the page template <page-template> to the Zim agent output.
The <page-template> parameter is a file path relative to the base path of the ZimWeb application, just like the <stylesheet> parameter above.
The <page-template> parameter can be overridden by the input parameter PAGETEMPLATE.
The ZimWeb automatically compiles and caches page templates in memory for maximum performance.
Read more about using page templates.

N.B. ZimWeb does not accept a URI for the form template since this could be a security hazard.

apply-xslfo:<renderer> Treat the Zim agent output, or the result of the other content processing (typically XSLT, though it could be a page template), as XSL Formatting Objects and render it with the specifed <renderer>.
The two rendering options currently available are PDF (Adobe Portable Document Format), for which you would specify apply-xslfo:pdf, or alternatively RTF (Rich Text Format), for which you would specify apply-xslfo:rtf.
Note that rendering to PDF is much more accurate than rendering to RTF.
HTTP session parameter management
set-session-parm:<name>=<value> Sets the session parameter <name> to the value <value>.
If the parameter <name> already exisits, then its value is changed to <value>.
Once set, the parameter will be available for inclusion in the TEMPLATE parameter.
Session parameters remain set until they are cleared, or the session times out or is invalidated.
Session parameters are not sent to the client - they are managed by the ZII servlet.
N.B. Cookies should be enabled on the client's browser in order that http session parameters function correctly.
If the same parameter exists in several places then the form parameters have priority over the session parameters, and these have priority over the cookie parameters.
clear-session-parm:<name> Clears the session parameter <name>.
invalidate-session Terminates the client session and starts a new one.
This will cause all session parameters to be discarded.
session-timeout:<timeout> Sets the session timeout to <timeout> seconds.
If not specified, the session timeout defaults to the value specified in the Configuring ZimWeb .
N.B. It only changes the timeout for this session, not any other session, and it does not change the default session timeout.
Cookie parameter management
set-cookie-parm:<name>=<value> Sets the cookie parameter <name> to the value <value>.
If the parameter <name> already exisits, then its value is changed to <value>.
Once set, the parameter will be available for inclusion in the TEMPLATE parameter.
Cookie parameters remain set until they are cleared, or the cookie reaches its expiry time.
To work, using cookie parameters requires that the client has cookies enabled.
N.B. Cookies should be enabled on the client's browser in order that cookie parameters function correctly.
If the same parameter exists in several places then the form parameters have priority over the session parameters, and these have priority over the cookie parameters.
clear-cookie-parm:<name> Clears the cookie parameter <name>.
N.B. This will not clear the
JSESSIONID cookie which is required for session management.
clear-all-cookies Clears all the cookies set by the ZimWeb .
N.B. This will not clear the
JSESSIONID cookie which is required for session management.
cookie-timeout:<timeout> Sets the cookie timeout to <timeout> seconds, as opposed to the default cookie timeout, for cookies set after it in the ZimWeb commands.
A negative timeout indicates that the cookie will expire when the user exits the client. However, I would suggest you use a session parameter instead in that case.
N.B. It does not change the default cookie timeout.
Persistent Zim session management
start-zim-session Start a persistent Zim session. Key points to note about this are:-
  • This is the Zim application requesting that the Zim session is to persist, not a request by the client.
  • If the persistent Zim session is being managed by a SESSIONID parameter in the form parameters then the Zim procedure must include the SESSIONID parameter in its TEMPLATE in order that it can continue using that Zim session.
  • Unlike the ZimCGI, all Zim database agent requests have a SESSIONID; but of course Zim sessions that are not to persist are ended at the end of the request in which they were started.
end-zim-session Ends the current persistent Zim session.
cancel-zim-session Ends the current persistent Zim session without sending any response to client.
Status and error codes
set-status:<status-code> Set an HTTP status code (without a message - sending a message with a status code is depricated) to the client.
send-error:<status-code>[:<message>] Send an HTTP error code, with or without a message, to the client.
Authentication
request-authentication:<realm> Send a BASIC authentication request for a given realm to the client.
Miscellaneous
redirect:<URL> Redirect the client to a new URL.
set-cache-time:<seconds> Set the caching time for a response in seconds (normally the responses indicate that they cannot be cached).
set-header:<name>=<value> Set a string HTTP header to a given value.
set-int-header:<name>=<value> Set an integer HTTP header to a given value.
set-date-header:<name>=<value> Set a date HTTP header to a given value. N.B. Dates are in milliseconds since the epoch (midnight on January 1, 1970).