ZimWeb Commands
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
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: |
Sets the response content type to .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: |
Apply XSLT stylesheet to the Zim agent output.The 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 as /styles/cool.xsl will refer to the file [TOMCAT_ROOT]/zii/styles/cool.xsl .The 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: |
Apply the page template to the Zim agent output.The parameter is a file path relative to the base path of the ZimWeb application, just like the parameter above.The 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: |
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 .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: |
Sets the session parameter to the value .If the parameter already exisits, then its value is changed to .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: |
Clears the session parameter . |
invalidate-session |
Terminates the client session and starts a new one. This will cause all session parameters to be discarded. |
session-timeout: |
Sets the session timeout to 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: |
Sets the cookie parameter .If the parameter already exisits, then its value is changed to .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: |
Clears the cookie parameter .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: |
Sets the cookie timeout to 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:-
|
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: |
Set an HTTP status code (without a message – sending a message with a status code is depricated) to the client. |
send-error: |
Send an HTTP error code, with or without a message, to the client. |
Authentication | |
request-authentication: |
Send a BASIC authentication request for a given realm to the client. |
Miscellaneous | |
redirect: |
Redirect the client to a new URL. |
set-cache-time: |
Set the caching time for a response in seconds (normally the responses indicate that they cannot be cached). |
set-header: |
Set a string HTTP header to a given value. |
set-int-header: |
Set an integer HTTP header to a given value. |
set-date-header: |
Set a date HTTP header to a given value. N.B. Dates are in milliseconds since the epoch (midnight on January 1, 1970). |