SiteVision Utilities API
The units of the Sitevision Utility API can be categorized as one of three main types:
- JCR operation utilities.
Helpers to make it easier to handle and operate on the JCR (Java Content Repository) Model. Typically: find a certain node, iterate only certain sub-nodes, get properties of a node etc.
- Additional functions.
Helpers for additional operations that typically doesn't involve a read operation of a JCR object in the data model tree. Typically: publish a page, send mail, do a REST call to an external API etc.
- JAAS (Java Authentication and Authorization Service).
Interfaces and classes needed to implement a custom JAAS module or a custom JAAS filter.
Accessing the utilities API
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");
Accessing utilities in Velocity
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:
- How to lookup the start page of the site?
The typical utility to use for lookup of a Node in the JCR tree is ResourceLocatorUtil.
- How to get the creating user from the start page?
First, we must determine the property name that depicts the "creating user". To do that we consult the node type documentation for the startpage, i.e. sv:sitePage.
Second, we must resolve the user Node from the property. Always use PropertyUtil to get properties.
- How to get the full name of the user Node?
The name of the "full name" property depends on what type the user node is. The node type candidates for a "user" are: sv:user, sv:simpleUser or sv:systemUser.
As mentioned above, always use PropertyUtil to get properties.
When we have consulted the Javadoc and the node type documentation we can write the actual code.
Example implementation in Velocity
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');