The units of the SiteVision Utility API can be categorized as one of three main types:
The main entrypoint to the utilities API is the Utils interface. It is a factory that provides methods to get actual implementations of individual utilities interfaces.
The Utils instance is always available as a request attribute of current javax.portlet.PortletRequest:
// Get the Utils instance from the portlet request
Utils sitevisionUtils = (Utils) aPortletRequest.getAttribute("sitevision.utils");
The documentation of each utility always contains information about how to get an instance of it. Most utilities is typically accessed directly via the Utils instance. Some utilities also have a @Requireable shortcut that is of interest when developing server-side Javascript.
Public API documentation example (the PropertyUtil interface)
The Utils instance is available as $sitevisionUtils in all JCR capable SiteVision modules that exposes a custom Velocity template.
## The Utils instance is available on the Velocity context as 'sitevisionUtils'
$sitevisionUtils
## Get a PropertyUtil instance, i.e. invoke the getPropertyUtil() method
#set ($propertyUtil = $sitevisionUtils.PropertyUtil)
Visit the Velocity jumpstart section if you are new to Velocity
The context of server-side Javascripts typically contains current PortletRequest as request.
// Get a PropertyUtil instance (via the Utils instance)
var sitevisionUtils = request.getAttribute('sitevision.utils'),
propertyUtil = sitevisionUtils.getPropertyUtil();
Utilities that are annotated with the @Requireable annotation can be accessed directly via the require function in server-side Javascripts. This bypasses the obtrusive boilerplate and overhead of having to go via the PortletRequest attribute as demonstrated above.
// Get a PropertyUtil instance
var propertyUtil = require('PropertyUtil');
Always use the require function to access utilities whenever applicable!
All data in the Utility API requires exactly the same permission as in the SiteVision editor in order to access data or perform operations. For example: to publish a page, current user (the one that is executing the actual code) must be authenticated and have PUBLISH permission on that page.
Using the SiteVision Utility API is quite straightforward since all interfaces, methods and enums are documented in the Javadoc. The tricky part is that you typically must combine utilities with access of actual data in the JCR model tree of the site. This requires knowledge of the tree layout, the node types and their properties. Hence, reading and understanding the Javadoc alone is often not enough to be able to implement specific functionality!
To illustrate some of the most used utilities, we do an example by writing the typical code needed to answer the question:
"What is the full name of the user that created the start page?"
To be able to answer this question, there are (at least) three specific problems we must solve:
When we have consulted the Javadoc and the node type documentation we can write the actual code.
We assume this code is written in a "custom template" of a JCR-capable module so the Util instance is available on the Velocity context.
## Get the utilities we need
#set ($resourceLocatorUtil = $sitevisionUtils.ResourceLocatorUtil)
#set ($propertyUtil = $sitevisionUtils.PropertyUtil)
## 1. Lookup the start page
#set ($startPage = $resourceLocatorUtil.getSitePage())
## 2. Get the user node
#set ($user = $propertyUtil.getNode($startPage, 'createdBy'))
## 3. Get the name of the user
#set ($name = $propertyUtil.getString($user, 'displayName'))
Note! The step 2 and step 3 can actually be utilized as a single operation with a "nested" convenicence method of PropertyUtil:
#set ($name = $propertyUtil.getNestedString($startPage, 'createdBy', 'displayName'))
This code would typically be written in the SiteVision Script module (potentially wrapped in a Element) or in a WebApp or a RESTApp.
// Get the utilities and variables we need
var resourceLocatorUtil = require('ResourceLocatorUtil'),
propertyUtil = require('PropertyUtil'),
startPage,
user,
name;
// 1. Lookup the start page
startPage = resourceLocatorUtil.getSitePage();
// 2. Get the user node
user = propertyUtil.getNode(startPage, 'createdBy');
// 3. Get the name of the user
name = propertyUtil.getString(user, 'displayName');
Note! As with the Velocity example above - step 2 and 3 can be utilized as a single operation:
name = propertyUtil.getNestedString(startPage, 'createdBy', 'displayName');
© 2019 SiteVision AB