Skip to main content

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(value) Removing leading and trailing whitespace
    • $utils.escape(value) Encode for output depending on the content type (HTML and Javascript are supported)
    • $utils.escapeJs(value) Escapes ECMA sript.
    • $utils.escapeJson(value) JSON specific escaping.
    • $utils.escapeHtml(value) Escapes HTML4 entities.
    • $utils.escapeHtmlAttribute(value) Escapes \, <, > & characters.
    • $utils.escapeUrl(value) UTF-8 URL encoding.
    • $utils.escapeXml(value) XML 1.1 specific escaping.
    • $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.