Rendering Engines

The only rendering style currently supported is Velocity.

Velocity

Velocity is a templating engine that can be used to build arbitrary documents including, in our case, web pages. Velocity has a simple and intuitive interface, but is still flexible enough to build complex dialogs. Describing the functionality of Velocity is outside the scope of this document. Refer to the official Velocity documentation Velocity User‘s Guide and the tutorial section Writing Login Applications using Velocity Rendering of this document for details. The rest of this section is devoted to the way nevisLogRend interacts with the Velocity engine.

Engine Invocation

The Velocity rendering engine is invoked for the following URLs (the context root nevislogrend is not shown):

• /index.vm Velocity engine entry point
• /auth/\* Authentication filter requests

Template Selection

Templates are selected based on the HTTP request, particularly the Accept header and the name of the GUI descriptor sent in the HTTP body. Typically, content is served as text/html, but JSON is also supported by default.

Velocity templates are located in the login application's webdata/template subdirectory. The templates provided by default are:

• default.vm
• footer.vm
• form.vm
• header.vm
• json.vm
• macros.vm

In general, you can choose either to implement the whole login application in one template (the default template), to provide in

The rendering engine will try to load and parse the dialog and default template in this order:

1. Dialog template (${DialogName}.vm)
2. Default template (default.vm)

For specific file requests, the rendering engine will first check whether the file exists, i.e., look for an exact match. If there is no exact match, the engine will look for a Velocity template that has the same file name, but a .vm file extension.

By default, the default.vm decides which content to serve. The Accept header is analyzed and other Velocity files are included based on its rules. For example, if Accept: application/json is received, the json.vm Velocity file is rendered and served.

Context Objects

Velocity templates can use Java objects placed in the Velocity context. How a reference is mapped to a concrete method (e.g., a getter method) is described in the Velocity User's Guide. The following table lists the names and types of the objects nevisLogRend populates the context with. Common use cases involving these objects are described in the tutorial section Writing Login Applications using Velocity Rendering.

• login

  Class: ch.nevis.logrend.beans.LoginBean

  The login context.

  Commonly used properties and methods:

  • $login.currentDialog Current login dialog
  • $login.language ISO language code (e.g., en)
  • $login.date Current date
  • $login.userAgent User agent
  • $login.requestURI Request URI
  • $login.requestHeaders Request headers
  • $login.requestParameters Request parameters
  • $login.method HTTP method
  • $login.getOperatingInfos(encode) Get operating infos file, optionally encoded depending on the content type.
  • $login.getSecurityInfos(encode) Get security infos file, optionally encoded depending on the content type.
  • $login.getDefaultString(property) Get property value from default.conf
  • $login.getDefaultStringOptional(property, defaultValue) Get property value from default.conf or defaultValue if the property is not defined in the default.conf file.

• gui

  Class ch.nevis.esauth.guidesc.GuiBean

  The GUI descriptor.

  Commonly used properties and methods:

  • $gui.target GUI target attribute, form submission target
  • $gui.getGuiElem("lasterror") Getting a GUI element

• templatePath

  Class: java.lang.String

  Convenience shortcut to the login application’s templates.

  Example: #parse("${templatePath}/footer.vm")

• text

  Class: ch.nevis.logrend.servlets.utils.BundleTool

  Accessor to localized text bundle.

  Commonly used properties and methods:

  • $text.disclaimer Look up the text disclaimer

  • $text.getFormatted("You have {0} tries left", $num) Formatted output

  • $text.getFormattedFromConfig("Password is at least {0} characters", "password.minLength") Formatted output with configuration lookup in logrend.properties.

  • $text.getAdvancedLitdictEntry($prefix, $key)

    Get from litdict with "magic"/advanced prefix: it tries to find a key composed from multiple parts. E.g., in the litdict we have entries like p1|p2|..|pn|realKey=val, this method tries to find prefix|key, with prefix=pStart|pRest. If prefix|key is not found, it tries pRest|key, if this is not found, it tries pStart|key. At the very end, the pure key is tried. This is done recursively (except pure key which is only tried once at the end). For p1|p2|p3|key=val this means that the following are tried in that order:

    p1|p2|p3|key
    p2|p3|key
    p3|key
    p2|key
    p1|key
    key

    Syntax for parametrized entries in LitDict: parameterized.label=Mary had a little {0} whose {1} was {2} as {3}

    Syntax for keys: parameterized.label[lamb][fleece][white][snow]

• utils

  Class: ch.nevis.logrend.servlets.utils.VelocityUtils

  Utilities.

  Commonly used properties and methods:

  • $utils.trim($string) Removing leading and trailing whitespace
  • $utils.escapeHtmlAttribute($url) Escapes a string to be used in an Html attribute.
  • $utils.escape(value) Encode for output depending on the content type (HTML and Javascript are supported)
  • $utils.getConfigParameter(name) Get a configuration parameter from logrend.properties.
  • $utils.getConfigParameters(prefix) Get all configuration parameters from logrend.properties that match the prefix (null or "" for all). The values are returned as a Map<String key, String value>. The prefix is removed from the returned keys.

Third-party Velocity tools

In addition to these built-in tools, some useful tools from the Velocity tools project have been included.

• browser

  Class: org.apache.velocity.tools.view.BrowserTool

  User-Agent tool from the Velocity tools project. See the Velocity tools documentation for details.

• number

  Class: org.apache.velocity.tools.generic.NumberTool

  Number tool from the Velocity tools project. See the Velocity tools documentation for details.

• iterator

  Class: org.apache.velocity.tools.generic.LoopTool

  Loop tool from the Velocity tools project. See the Velocity tools documentation for details.

• sort

  Class: org.apache.velocity.tools.generic.CollectionTool

  Collection tool from the Velocity tools project. See the Velocity tools documentation for details.

• link

  Class: org.apache.velocity.tools.view.LinkTool

  Link tool from the Velocity tools project. See the Velocity tools documentation for details.

• params

  Class: org.apache.velocity.tools.view.ParameterTool

  Parameter tool from the Velocity tools project. See the Velocity tools documentation for details.