Rendering Engines
The following subsections document the various styles of rendering that nevisLogRend offers.
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 of the scope of this document. Refer to the official Velocity documentation Velocity User‘s Guide, http://velocity.apache.org/engine/devel/user-guide.html 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):
| URL | Description |
|---|---|
| /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 individual templates for a file request (file templates) or even to mix the three approaches. Dialog templating might be suitable if some dialogs have to be rendered in a completely different fashion than others. File templating can be used to request specific Velocity files to be rendered.
The rendering engine will try to load and parse the dialog and default template in this order:
- Dialog template (${DialogName}.vm)
- 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.
| Name | Type/Description |
|---|---|
| login | 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.httpmethod | 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 | 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 | java.lang.String Convenience shortcut to the login application’s templates.#parse("${templatePath}/footer.vm") |
| text | 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|keyp2|p3|keyp3|keyp2|keyp1|keykey 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 | 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. |
In addition to these built-in tools, some useful tools from the Velocity tools project have been included.
| Name | Type/Description |
|---|---|
| browser | org.apache.velocity.tools.view.tools.BrowserSnifferTool User-Agent tool from Velocity tools project. See Velocity tools documentation for details. |
| number | org.apache.velocity.tools.generic.NumberTool Number tool from Velocity tools project. See Velocity tools documentation for details. |
| iterator | org.apache.velocity.tools.generic.IteratorTool Iterator tool from Velocity tools project. See Velocity tools documentation for details. |
| sort | org.apache.velocity.tools.generic.SortTool Sort tool from Velocity tools project. See Velocity tools documentation for details. |
| list | org.apache.velocity.tools.generic.ListTool List tool from Velocity tools project. See Velocity tools documentation for details. |
| alternator | org.apache.velocity.tools.generic.AlternatorTool Alternator tool from Velocity tools project. See Velocity tools documentation for details. |
| link | org.apache.velocity.tools.view.tools.LinkTool Link tool from Velocity tools project. See Velocity tools documentation for details. |
| params | org.apache.velocity.tools.view.tools.Parameterparser ParameterParser tool from Velocity tools project. See Velocity tools documentation for details. |