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.
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.
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.
axvelocity
palette and drag and drop the VelocityServlet into the Station.file:^test.vm
.numPoint
.boolPoint
.vm
file you created earlier.
<!DOCTYPE html>
<html>
<head>
<title>My first Velocity test!</title>
</head>
<body>
<p>Boolean Point: $boolPoint</p>
<p>Numeric Point: $numPoint</p>
</body>
</html>
admin
will do.http://localhost/velocity/test
(localhost can be changed to an IP address of your choice).
velocity
is the name of the servlet.test
is the name of the Document Component you created earlier.vm
file has been used for this view.$boolPoint
and $numPoint
has been replaced with real point data.http://yourIpAddress/velocity
. Please note the name of the Servlet can be changed from ‘velocity’ to something else in the Velocity Document Manager View. The Velocity Document Manager is the default view for this Component.useProfile
Property set to true, this Profile will be used to generate the outer HTML page. For more information, please see the section on profiling.Only a user with operator read permissions on a VelocityDoc Component can access that through the Velocity Servlet.
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.
http://localhost/velocity
- this will redirect to the first valid VelocityDoc that can be found for the user.http://localhost/velocity/test
- this will load the VelocityDoc named test
.http://localhost/ord?station:%7Cslot:/VelocityServlet
- this will redirect to the first valid VelocityDoc that can be found for the user.http://localhost/ord?station:%7Cslot:/VelocityServlet%7Cview:test
- this will redirect to the VelocityDoc named test
.station:|slot:/VelocityServlet|view:test
- an ORD that can be used as a hyperlink in a Px page. This will redirect to the VelocityDoc named test
.Specifying the ORD to the Servlet Component in a NavFile is a really great way to get to your VelocityDoc using Niagara.
Parameters can be passed into a view via a URI (or ORD that redirects to a URI). For instance…
http://localhost/velocity/test?param1=val1¶m2=val2
- passes two parameters into a view.station:|slot:/VelocityServlet|view:test?param1=val1;param2=val2
- an ORD that can be used as a hyperlink in a Px page. This will redirect to the VelocityDoc named test with the specified parameters.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 is an advanced feature of working with VelocityDoc Station Components. A Profile generates the outer HTML content while the VelocityDoc generates the inner.
Velocity Doc Web Profile
.
file:^profile.vm
). The VM file should have code similar to the following…<!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>
#parse("$ax.viewTemplate")
to the inner HTML.
$generateHeader
flag is used to determine whether the header of the body of the HTML document is being generated.useProfile
Property set to true.
useProfile
Property is set to false, the VelocityDoc is responsible for generating the whole of the HTML document (just as before).#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!
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 extends BServletView. This class forms the basis for any Velocity based view. A view may or may not work in conjunction with a BVelocityWebProfile.
getTemplateFileMethod
.
module
ORD scheme).initVelocityContext
method.
An interface used by any profile that wants to act as a Velocity Web Profile.
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.
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.
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.
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')
.
An Hx Field Editor that uses Velocity.
An Hx Px Widget that uses Velocity.
Common to all Velocity based views are some really useful Niagara related methods and properties that are accessed through the Velocity Context.
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!
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).
$ax.session
: the HttpSession being used to the current request.$ax.target
: the OrdTarget for the current request.$ax.cx
: the Context for the current request.$ax.op
: the WebOp for the current request.$ax.obj
: the resolved object for the current request (from OrdTarget#get()
).$ax.profile
: the web profile being used.$ax.Flags
: javax.baja.sys.Flags.$ax.lang
: the language for the current request.$ax.user
: the user for the current request.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…
$util.get("station:|slot:/")
: resolves an ORD returns the object. If the result is a mounted Component, it will be leased.
$util.get("slot:BooleanWritable", "station:|slot:/")
: same as above except this can also take a base to help ORD resolution.$util.resolve("station:|slot:/")
: same as ‘get’ except this resolves to an OrdTarget.$util.resolve("slot:BooleanWritable", "station:|slot:/")
: same as ‘get’ except this resolves to an OrdTarget.$util.getChildren(complex)
: return an array of children of a BComplex.
$util.getChildren(complex, "myModule:MyType")
: return an array of children from a Complex of a specific Type.
$util.is(complex, "myModule:MyType")
: returns a boolean indicating whether the specified value is of the specified Type.
$util.ord("station:|slot:/", "bql:select * from baja:Component")
: creates a normalized ORD from a base and child. The argument can be BOrd or String.$util.lex("bajaui").get("dialog.ok")
: get a Lexicon value.
$util.lex("bajaui").getText("fileSearch.scanningFiles", "first", "second")
: get a Lexicon value with parameters.$util.lex("bajaui")
simply returns the Lexicon for the given module name.$util.requirejs()
: adds require js support. You need to add this at the top of the document if you want to use BajaScript or any of the new web technologies added to Niagara 4.$util.getDisplay(complex)
: returns a display string for the given complex.
$util.getDisplay("slot:BooleanWritable", base)
: returns a display string for the given complex. If an ORD is specified as the argument then the base is used to help resolve it.
$util.getDisplayFromProperty(complex, prop)
: returns a display string for the given complex and Property.
$util.getDisplayFromProperty(complex, prop, base)
: returns a display string for the given complex and Property.
$util.isHidden(complex, slot)
: returns a boolean indicating whether the specified slot should be hidden.
$util.canRead(component)
: returns a boolean whether the currently logged on user has read permissions on the specified Component.
$util.canRead(component, slot)
: returns a boolean whether the currently logged on user has read permissions to access the specified Slot.
$util.canWrite(component, slot)
: returns a boolean whether the currently logged on user has write permissions to access the specified Slot.
$util.canInvoke(component, slot)
: returns a boolean whether the currently logged on user has invoke permissions to access the specified Slot.
$util.jQuery()
: returns the HTML script tag to include jQuery.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.
$util.startActivityMonitor()
: Helps send periodic user activity back to the server.$util.keepSessionAlive()
: Sends periodic status requesting the server not to auto log off in case of no activity.$util.releaseKeepAliveToken()
: Call this when your view is unloaded or you no longer require to keep the view alive.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>
Copyright © 2000-2019 Tridium Inc. All rights reserved.