Sitevision Utilities API

The units of the Sitevision Utility API can be categorized as one of three main types:

  1. 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.
  2. 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.
  3. JAAS (Java Authentication and Authorization Service).
    Interfaces and classes needed to implement a custom JAAS module or a custom JAAS filter.

The Sitevision Public API Javadoc can be found here.

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");

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.

Excerpt of Javadoc for PropertyUtil

Public API documentation example (the PropertyUtil interface)

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

Accessing utilities in (server-side) JavaScript

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!

Permissions

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.

Potential difficulties

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!

Example

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:

  1. 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.

  2. 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.

  3. 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'))

Example implementation in (server-side) Javascript

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');