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 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
// Get a PropertyUtil instance (via the Utils instance) var sitevisionUtils = request.getAttribute('sitevision.utils'), propertyUtil = sitevisionUtils.getPropertyUtil();
// 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.
// 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');