Velocity templates
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.
expose-*
properties
Velocity extensions can be configured to expose several objects in the context using the expose-*
properties:
expose-request-attributes
-
Indicates whether HTTP request attributes are accessible to templates using the
$ubid_request
variable. 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. expose-session-attributes
-
Indicates whether HTTP session attributes are accessible to templates using the
$ubid_session
variable. 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. expose-server-context
-
Indicates whether a Server SDK server context is accessible to templates using the
$ubid_server
variable. 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:
description
-
A description of the extension.
cross-origin-policy
-
Defines a cross origin policy for this extension.
base-context-path
-
URL base context for the Velocity Servlet.
static-content-directory
-
In addition to templates, the Velocity Servlet will serve miscellaneous static content related to the templates. By default this is
config/velocity/statics
. require-authentication
-
Requires credentials to access Velocity content.
identity-mapper
-
Maps user credentials to backend entries. If the
require-authentication
property 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. static-custom-directory
-
If static content is customized, it resides in
velocity/statics
by default. template-directory
-
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. static-context-path
-
URL path beneath the base context where static content can be accessed.
allow-context-override
-
Indicates whether context providers can override existing context objects with new values.
mime-types-file
-
Specifies a file that is used to map file extensions of static content to a Content Type to be returned with requests.
default-mime-type
-
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:
http://example.com:8080/view/hello?name=Joe
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 values.
For security, all template substitutions are HTML escaped by default. To substitute unescaped content, you must use a variable name ending with |
A debug option can be used in any Velocity template for verifying available information in the Velocity Context:
parse("_debug.vm") debug()
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 $undefined_variable
.
By default, the Velocity Servlet Extension expects to access content in subdirectories of the server’s config/velocity
directory:
- templates
-
This directory contains Velocity template files that are used to generate pages in response to client requests.
- statics
-
This directory contains static content such as CSS, HTML, and Javascript files as well as images and third-party libraries.