Velocity template files contain presentation content and variables that are replaced when the content is requested.
The PingDataMetrics Server exposes Velocity pages through an HTTP Servlet Extension. If the HTTP Connection Handler is enabled, the Velocity extension is enabled.
$ bin/dsconfig set-connection-handler-prop \ --handler-name "HTTPS Connection Handler" \ --add http-servlet-extension:Velocity
Variables are expressed using a
$ followed by an identifier that
refers to an object put into a context (VelocityContext) by the server.
Velocity extensions can be configured to expose a number of objects in the context
- Indicates whether HTTP request attributes are accessible to templates using
$ubid_requestvariable. In general, request attributes are added by server components processing the HTTP request. Also the HTTP request parameters map is available as
$ubid_request.parameters. Request parameters are supplied by the requester, usually in the request URL query string or in the body of the request itself.
- Indicates whether HTTP session attributes are accessible to templates using
$ubid_sessionvariable. Like request attributes, session attributes are also added by server components processing the HTTP request. The lifetime of these attributes persists until the user’s session has ended.
- Indicates whether a Server SDK server context is accessible to templates
$ubid_servervariable. The server context provides access to properties and additional information about the server. See the Server SDK documentation for details.
Velocity HTTP servlet extension properties
The following are other properties of the Velocity HTTP Servlet Extension:
- A description of the extension.
- Defines a cross origin policy for this extension.
- URL base context for the Velocity Servlet.
- In addition to templates, the Velocity Servlet will serve miscellaneous static content related to the templates. By default this is config/velocity/statics.
- Requires credentials to access Velocity content.
- Maps user credentials to backend entries. If the
require-authenticationproperty is set, use this property to map bind credentials from a users backend. This is set to Exact Match by default. PingDataMetrics Server Velocity template authentication should share the api-users LDIF backend used by the REST API. Details are available in the PingDataMetrics Server REST API servlet configuration, and in the Connection and Security section.
- If static content is customized, it resides in velocity/statics by default.
- The template directory from which templates are read. By default this is config/velocity/templates. This directory also serves as a default for Template Loaders that do not have a template directory specified.
- URL path beneath the base context where static content can be accessed.
- Indicates whether context providers can override existing context objects with new values.
- Specifies a file that is used to map file extensions of static content to a Content Type to be returned with requests.
- The default Content Type for HTTP responses. Additional content types are supported by defining one or more additional Velocity Template Loaders.
The VelocityContext object can be further customized by configuring additional Velocity context providers. The dot notation used for context references can be extended to access properties and methods of objects in context using Java Bean semantics. For example, if the HTTP request URL includes a name query string parameter like:
An HTML template like the following could e used to generate a page containing a friendly greeting to the requestor:
<html> <body> Hello $ubid_request.parameters.name </body> </html>
A pop-up window displays a table on the page that lists all variables that are in the Velocity
Context. References like
$ubid_request can appear in the template
file and be replaced when the template is rendered. This information can be used to
check which variables are permitted to be in the template along with the variable
For security, all template substitutions are HTML escaped by default. To substitute unescaped
content, you must use a variable name ending with WithHtml. For
$addressWithHtml, would substitute the contents of the
$addressWithHtml variable into the page generated from the
HTML template without escaping it.
A debug option can be used in any Velocity template for verifying available information in the Velocity Context:
If a variable is added to a template for something that does not exist, the rendered
page will contain a literal string of the unfulfilled variable, such as
By default, the Velocity Servlet Extension expects to access content in subdirectories of the server’s config/velocity directory:
- This directory contains Velocity template files that are used to generate pages in response to client requests.