PingDirectory

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 WithHtml. For example, $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:

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.