Apache Velocity

Apache Velocity is an open source web template engine that’s now integrated into the Niagara framework. It provides users with the ability to script an HTML page together using a very simple scripting language.

For more information on understanding what Velocity is, please visit the Apache website here.

The user guide for using Velocity can be found here.

Velocity support was added to Niagara AX in version 3.7.

Users

The Velocity API is not just for developers but can also be used by advanced users. Advanced users can take advantage of Velocity through Station Components that one can configure from the axvelocity palette.

Velocity Station Components

The AX Velocity Station Components require the ‘axvelocity’ license feature.

There are multiple ways to use Velocity. Advanced users (who aren’t necessarily fully trained Niagara developers) can configure a Station using Components from the axvelocity palette.

Getting Started

<!DOCTYPE html>
<html>
  <head>
    <title>My first Velocity test!</title> 
  </head>
  <body>   
    <p>Boolean Point: $boolPoint</p> 
    <p>Numeric Point: $numPoint</p>      
  </body>
</html>

Component Description

Security

Only a user with operator read permissions on a VelocityDoc Component can access that through the Velocity Servlet.

Navigation

Accessing a particular VelocityDoc through a browser can be done in a variety of ways. For example…

The velocity Servlet name can be changed by a user.

Specifying the ORD to the Servlet Component in a NavFile is a really great way to get to your VelocityDoc using Niagara.

View parameters

Parameters can be passed into a view via a URI (or ORD that redirects to a URI). For instance…

The parameters can be picked up from VTL code. For example…

## Iterate through any query parameters used in the URL
#set( $parameters = $ax.op.getRequest().getParameterNames() )
#foreach ( $param in $parameters )
<p>
  Found parameter: $param - $ax.op.getRequest().getParameter($param) 
</p>
#end

Profiling

Profiling is an advanced feature of working with VelocityDoc Station Components. A Profile generates the outer HTML content while the VelocityDoc generates the inner.

Getting Started

<!DOCTYPE html>
<html>
  <head>
    <title>Velocity Profile</title> 
    #set($generateHeader = true)

    ## Parse the inner view for the header...
    #parse("$ax.viewTemplate")

    #set($generateHeader = false)
  </head>
  <body>            
    <h2>Path: $ax.target.getPathInfo()</h2>

    ## Parse the inner view for the header...  
    #parse("$ax.viewTemplate")

  </body>
</html>
#if ($generateHeader)
  ## Anything for the header of the HTML page goes here.
#else
  ## Anything for the body of the HTML page goes here.
  <h3>This is from the body of the view</h3>
#end

*Note how the $generateHeader (created by the Profile) is used to determine whether code is being generated for the HTML document’s header or body.

The ‘Velocity Doc Web Profile’ must always be used to access VelocityDoc views that have their ‘useProfile’ Property set to true!

Standard Velocity Java API

Velocity can be used by Java developers to create Velocity based views. A developer who uses this API should have been on the Developer Course and hence should be a fully trained Niagara Jedi.

BVelocityView

BVelocityView extends BServletView. This class forms the basis for any Velocity based view. A view may or may not work in conjunction with a BVelocityWebProfile.

Getting Started

BIVelocityWebProfile

An interface used by any profile that wants to act as a Velocity Web Profile.

BVelocityWebProfile

A Web Profile that implements BIVelocityWebProfile.

A Velocity Web Profile has it’s own VM file used to render the overall page. In the Velocity Context, there’s a symbol called $ax.viewTemplate that be then be used by the profile VTL to render the underlying view.

VelocityContextUtil

This is a useful library of functions that can be called via VTL. In VTL, this library can be referenced via ‘$ax.util’ or ‘$util’. For more information on use please see Niagara VTL.

Hx Velocity Views

To enhance Hx development, some Hx Velocity views have been added.

In Hx development, a developer would normally write out an Hx view’s initial HTML by overriding BHxView’s write method. In the following Velocity Hx classes, this method has already been overridden and will return output from Velocity.

BVelocityHxView

This class extends BHxView.

This class follows the same design as BVelocityView.

Note: the HxOp can be referenced from the VTL from $ax.op. For instance, $ax.op.scope('idOrName').

BVelocityHxFieldEditor

An Hx Field Editor that uses Velocity.

BVelocityHxPxWidget

An Hx Px Widget that uses Velocity.

Niagara VTL

Common to all Velocity based views are some really useful Niagara related methods and properties that are accessed through the Velocity Context.

Use Cases

There’s a LOT we could add to the VelocityContext. However, to try and stem the tide, we’ve developed this feature around the following use cases…

*For anything ‘live’, please consider using BajaScript. It does all of the ‘live’ things (like invoking an Action for instance) that Velocity isn’t designed to do!

API

The core Niagara Velocity related methods and properties are part of the $ax namespace. Some sub-namespaces (i.e. $ax.util) are consider so useful that we’ve also added them to the global namespace (i.e. $util).

Core ax namespace

Util namespace

This can be accessed via $ax.util or $util.

All methods are fully listed (and commented) in javax.baja.velocity.VelocityContextUtil.

The methods are designed to be easy to use and in some cases can take a variety of argument Types (just like in JavaScript).

For convenience here’s an overview…

Value Access

Misc

Display

Slot Access

jQuery

Activity Monitoring

Auto Log Off automatically logs a user off if there is no activity for a set period of time. Activity monitoring helps notify the server that the user is still active and prevents the server from
invalidating the session if there is any valid activity. Auto log off support is built right into the Velocity context and can be accessed via utility methods.

Note: If RequireJS is available use $util.requirejs() before using the activity monitoring utilities.

Sample usage:


<!DOCTYPE html>
<html>
  <head>
    <title>My first Velocity test!</title>
    $util.startActivityMonitor()
  </head>
  <body>   
    <p>Boolean Point: $boolPoint</p> 
    <p>Numeric Point: $numPoint</p>      
  </body>
</html>