• 
• Updated On 4.1.0

Groovy Development

CrafterCMS supports server-side development with Groovy. By using Groovy, you can create RESTful services, MVC controllers, code that runs before a page or component is rendered, servlet filters, scheduled jobs, and entire backend applications.

Groovy API

CrafterCMS provides a number of useful global variables that can be used in all the different types of scripts available:

Name	Description	Type
siteItemService	Allows access to the site content.	SiteItemService
urlTransformationService	Service for transforming URLs, like transforming the content URL of a page to the web or render URL.	UrlTransformationService
search	Service that can be used to execute search queries against OpenSearch.	OpenSearchWrapper
applicationContext	Provides access to the Crafter Engine’s Spring beans and site beans defined in config/spring/application-context.xml	ApplicationContextAccessor
globalProperties	Provides access to global configuration properties defined in server-config.properties. |	PropertySourcesPropertyResolver
navBreadcrumbBuilder	Helper class that returns the list of path components in an URL, to create navigation breadcrumbs. |	BreadcrumbBuilder
navTreeBuilder	Helper class that creates navigation trees to facilitate rendering	NavTreeBuilder
tenantsResolver	Can be used to retrieve the Profile tenants associated to the current site. |	TenantsResolver
profileService	Provides access to the Crafter Profile API for profiles. |	ProfileService
tenantService	Provides access to the Crafter Profile API for tenants. |	TenantService
authenticationService	Provides access to the Crafter Profile API for authentication. |	AuthenticationService
authenticationManager	Manages Crafter Security Provider based authentications. |	AuthenticationManager
textEncryptor	Utility class for encrypting/ decrypting text with AES. |	See TextEncryptor under org.springframework.security.crypto.encrypt in the Spring Security apidocs
modePreview	Flag that indicates that Engine is being executed in preview mode (also the value of the crafter.engine.preview property)	Boolean
crafterEnv	Indicates the value of the crafter.engine.environment property	String
logger	The GroovyUtils SLF4J logger	Logger
siteConfig	The current site Configuration, loaded from /config/site.xml. |	See XMLConfiguration under org.apache.commons.configuration2 in the Apache Commons apidocs
siteContext	The current SiteContext	SiteContext

There are also several other variables available to scripts that are executed during the scope of a request (REST scripts, controller scripts, page/component scripts and filter scripts):

Name	Description	API
request	The current request	HttpServletRequest
response	The current response	HttpServletResponse
params	The parameter values for the current request	Map
headers	The header values for the current request	Map
cookies	The cookie values for the current request	Map
session	The current session, if it has been created	HttpSession
locale	The current locale for the current user	Locale
authToken	The current authentication (if the user has logged in), created by Spring Security	Authentication

The following variables are provided for backward compatibility when using Crafter Profile, should be replaced with authToken if possible:

Name	Description	API
authentication	The current authentication (if the user has logged in), created by the Crafter Security Provider	Authentication
profile	The current profile (if the user has logged in), created by the Crafter Security Provider	Profile

Note

The variables profile and authentication listed above will be null in most cases and should not be used anymore

The following variables are restricted by default, to use them see Configuration Related to Building Custom Services

Name	Description	API
application	The servlet context	ServletContext

All scripts are executed in a sandbox to prevent insecure code from running, to change the configuration see Groovy Sandbox Configuration

To create unit tests for your groovy code, see Unit Testing CrafterCMS Groovy Code

Types of Scripts

There are different types of scripts you can create, depending on the subfolder under Scripts where they’re placed. The following are the ones currently supported:

REST Scripts

REST scripts function just like RESTful services. They just need to return the object to serialize back to the caller. REST scripts must be placed in any folder under Scripts > rest.

A REST script URL has the following format: it starts with /api/1/services, then contains all the folders that are part of the hierarchy for the particular script, and ends with the script name, the HTTP method and the .groovy extension. So, a script file at Scripts > rest > myfolder > myscript.get.groovy will respond to GET method calls at http://mysite/api/1/services/myfolder/myscript.json.

The following is a very simple sample script that returns a date attribute saved in the session. If no attribute is set yet, the current date is set as the attribute. Assume that the REST script exists under Scripts > rest > session_date.get.groovy

import java.util.Date

if (!session) {
    session = request.getSession(true)
}

def date = session.getAttribute("date")
if (!date) {
    date = new Date()

    session.setAttribute("date", date)
}

return ["date": date]

Controller Scripts

Controller scripts are very similar to REST scripts. They have the same variables available, but instead of returning an object, they return a string with the view to render. Most of the time, this is just the template path, like in the following snippet:

return "/templates/web/registration.ftl"

Controller scripts basically work like a controller in the MVC pattern. They should be put under Scripts > controllers, and similarly to REST scripts, the URL is made up of the directory hierarchy, the script name and the HTTP method. For example, a script at Scripts > controllers > myfolder > mycontroller.get.groovy will respond to GET calls at http://mysite/myfolder/mycontroller.

The following is a very simple example script that will do the sum of 2 parameters, put the result in the templateModel and return the path of the FTL template that will render the result:

templateModel.result = Integer.parseInt(params.num1) + Integer.parseInt(params.num2)

return "/templates/web/sum.ftl"

One very common controller script is the sitemap.groovy. A sitemap is used by search engines to have a better idea of how to “crawl” a website. A sitemap is an XML with references to most of the site’s pages, and basically looks like this:

<?xml version="1.0" encoding="UTF-8"?>
<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">
    <url>
        <loc>http://www.domain.com /</loc>
        <lastmod>2008-01-01</lastmod>
        <changefreq>weekly</changefreq>
        <priority>0.8</priority>
    </url>
    <url>
        <loc>http://www.domain.com/catalog?item=vacation_hawaii</loc>
        <changefreq>weekly</changefreq>
    </url>
    <url>
        <loc>http://www.domain.com/catalog?item=vacation_new_zealand</loc>
        <lastmod>2008-12-23</lastmod>
        <changefreq>weekly</changefreq>
    </url>
    <url>
        <loc>http://www.domain.com/catalog?item=vacation_newfoundland</loc>
        <lastmod>2008-12-23T18:00:15+00:00</lastmod>
        <priority>0.3</priority>
    </url>
    <url>
        <loc>http://www.domain.com/catalog?item=vacation_usa</loc>
        <lastmod>2008-11-23</lastmod>
    </url>
</urlset>

Search engines look for the sitemap just after the domain, so a sitemap URL would look like www.domain.com/sitemap. The sitemap controller then must be placed in Scripts > controllers > sitemap.groovy. The code would be similar to this:

import groovy.xml.MarkupBuilder
import groovy.xml.MarkupBuilderHelper

def sitemap = []
def excludeContentTypes = ['/component/level-descriptor']

parseSiteItem = { siteItem ->
    if (siteItem.isFolder()) {
        def children = siteItem.childItems;
        children.each { child ->
            parseSiteItem(child);
        }
    } else {
        def contentType = siteItem.queryValue('content-type')
        if (!excludeContentTypes.contains(contentType)) {
            def storeUrl = siteItem.getStoreUrl();
            def location = urlTransformationService.transform('storeUrlToFullRenderUrl', storeUrl);
            sitemap.add(location);
        }
    }
}

def siteTree = siteItemService.getSiteTree("/site/website", -1)
if (siteTree) {
    def items = siteTree.childItems;
    items.each { siteItem ->
        parseSiteItem(siteItem);
    }
}

response.setContentType("application/xml;charset=UTF-8")

def writer = response.getWriter()
def xml = new MarkupBuilder(writer)
def xmlHelper = new MarkupBuilderHelper(xml)

xmlHelper.xmlDeclaration(version:"1.0", encoding:"UTF-8")

xml.urlset(xmlns:"http://www.sitemaps.org/schemas/sitemap/0.9") {
    sitemap.each { location ->
        url {
            loc(location)
            changefreq("daily")
        }
    }
}

response.flushBuffer()

return null

Page and Component Scripts

Crafter page and components can have their own controller scripts too, that are executed before the page or component is rendered, and that can contribute to the model of the template. These scripts, besides the common variables, have the following model related variables:

Model Related Variable	Description
contentModel	The XML descriptor content It is an instance of the SiteItem class
templateModel	The actual map model of the template It is an instance of the AllHttpScopesAndAppContextHashModel class

As mentioned in the table above, the templateModel is the actual map model of the template, and any variable put in it will be accessible directly in the template, eg. if the script has the line templateModel.var = 5, then in the template the var’s value can be printed with ${var}. The scripts don’t have to return any result, just populate the templateModel.

There are 2 ways in which you can “bind” a script to a page or component:

1. Put the script under Scripts > pages or Scripts > components, and name it after the page or component content type.

2. When creating the content type for the page or component, add an Item Selector with the variable name scripts. Later when creating

   a page or component of that type, you can select multiple scripts that will be associated to the page or component.

The following is an example of a component script. The component content type is /component/upcoming-events. We can then place the script in Scripts > components > upcoming-events.groovy so that it is executed for all components of that type.

scripts/components/upcoming-events.groovy

import org.craftercms.engine.service.context.SiteContext

import utils.DateUtils

def now = DateUtils.formatDateAsIso(new Date())
def queryStr = "crafterSite:\"${siteContext.siteName}\" AND content-type:\"/component/event\" AND disabled:\"false\" AND date_dt:[${now} TO *]"
def start = 0
def rows = 1000
def sort = "date_dt asc"
def query = searchService.createQuery()

query.setQuery(queryStr)
query.setStart(start)
query.setRows(rows)
query.addParam("sort", sort)
query.addParam("fl", "localId")

def events = []
def searchResults = searchService.search(query)
if (searchResults.response) {
  searchResults.response.documents.each {
    def event = [:]
    def item = siteItemService.getSiteItem(it.localId)

    event.image = item.image.text
    event.title = item.title_s.text
    event.date = DateUtils.parseModelValue(item.date_dt.text)
    event.summary = item.summary_html.text

    events.add(event)
  }
}

templateModel.events = events

In the above example, you will see that we’re importing a utils.DateUtils class. This class is not part of CrafterCMS, but instead it is a site specific class written in Groovy. The class is/needs to be located at the following path scripts > classes > utils and is placed in a file called DateUtils.groovy, like below:

scripts/classes/utils/DateUtils.groovy

package utils

import java.text.SimpleDateFormat

class DateUtils {

  static def parseModelValue(value){
    def dateFormat = new SimpleDateFormat("MM/dd/yyyy HH:mm:ss")
    dateFormat.setTimeZone(TimeZone.getTimeZone("UTC"))
    return dateFormat.parse(value)
  }

  static def formatDateAsIso(date) {
    def dateFormat = new SimpleDateFormat("yyyy-MM-dd'T'HH:mm:ss'Z'")
    dateFormat.setTimeZone(TimeZone.getTimeZone("UTC"))
    eturn dateFormat.format(date)
  }

}

Filter Scripts

Crafter Engine can handle special Groovy filters that work basically in the same way as Servlet filters. These are scripts very similar to page scripts, and have basically the same variables available (except the templateModel and contentModel variables), but instead of updating the template model, they call filterChain.doFilter (request, response), just like in Java Servlet filters, to continue with the filter chain. You can even stop the request filtering and return the response directly, like in this example:

if (!authentication) {
    response.sendError(400, "You're not a subscriber")
} else {
    filterChain.doFilter(request, response)
}

All this filter scripts should be put under Scripts > filters, and their mappings should be defined in Config > site.xml. The order in which the mappings appear is the order in which the filters will be applied.

<filters>
    <filter>
        <script>/scripts/filters/testFilter1.groovy</script>
        <mapping>
            <include>/**</include>
        </mapping>
    </filter>
    <filter>
        <script>/scripts/filters/testFilter2.groovy</script>
        <mapping>
            <include>/**</include>
        </mapping>
    </filter>
    <filter>
        <script>/scripts/filters/testFilter3.groovy</script>
        <mapping>
            <include>/**</include>
            <exclude>/static-assets/**</exclude>
        </mapping>
    </filter>
</filters>

The following is an example script that adds a display name attribute to the current profile if the attribute doesn’t exist yet. Assume that the script is placed in Scripts > filters > addDisplayName.groovy.

if (profile) {
    def displayName = profile.getAttribute("displayName")
    if (!displayName) {
        def id = profile.id.toString()
        def firstName = profile.getAttribute("firstName")
        def lastName = profile.getAttribute("lastName")
        def newAttributes = [:]

        newAttributes["displayName"] = "${firstName} ${lastName}".toString()

        profileService.updateAttributes(id, newAttributes)

        logger.info("Display name added to profile '${id}'")
    }
}

filterChain.doFilter(request, response)

To enable this filter, we need to configure its mapping in Config > site.xml. The mapping would look as the following.

<?xml version="1.0" encoding="UTF-8"?>
<site>
    <filters>
        <filter>
            <script>/scripts/filters/addDisplayName.groovy</script>
            <mapping>
                <include>/**</include>
            </mapping>
        </filter>
    </filters>
</site>

Scheduled Script Jobs

Scripts can also be scheduled as jobs in Crafter Engine. These scripts only have the common global variables and the logger variable. They don’t need to return any result. Engine allows 3 different ways to configure script jobs:

• By placing the scripts under one of the following folders in Scripts > jobs: hourly, daily, weekly and monthly. As the names imply, scripts under these folders will be scheduled to run every hour (hourly), at 12:00 am every day (daily), at 12:00 am every Monday (weekly), or at 12:00 am every first day of the month (monthly).

• By adding one or more <jobFolder> configuration elements under <jobs> in Config > site.xml. Under <jobFolder> you can specify a <path> and a <cronExpression>, and every script under that folder will be scheduled using the cron expression.

  <jobs>
      <jobFolder>
          <path>/scripts/jobs/morejobs</path>
          <cronExpression>0 0/15 * * * ?</cronExpression>
      </jobFolder>
  </jobs>
  

• By adding one or more <job> configuration elements under <jobs> in Config > site.xml. With the <path> and <cronExpression> elements, you specify the job script path and the cron expression for scheduling.

  <jobs>
      <job>
          <path>/scripts/jobs/testJob.groovy</path>
          <cronExpression>0 0/15 * * * ?</cronExpression>
      </job>
  </jobs>
  

Unit Testing CrafterCMS Groovy Code

For larger sites with complex services implemented in Groovy, it is very helpful to have a way to include unit tests in a way that can be easily integrated with CI/CD systems.

This section details how to create unit tests for CrafterCMS Groovy code with Gradle.

For more information on the classes of the variables that can be mocked for unit testing, see above

Steps for Creating Groovy Unit Test

To create a unit test:

1. Designate a folder for all test related files

2. Write your unit test code

3. Setup your unit test to run with Gradle

4. Execute your unit test

Designate Folder for All Test Related Files

Designate a folder in the site repository to contain all test related files. For example:

CRAFTER_HOME/data/repos/sites/SITENAME/sandbox

/scripts
   /test
     /classes   (all packages & groovy classes for testing)
     /resources (all additional files required for testing)

This structure is the equivalent of the standard folders used for Java/Groovy projects:

/src/test/groovy
/src/test/resources

Write Your Unit Test Code

There are no restrictions or requirements for the unit test code, developers can choose any testing framework supported by the build tool. Examples: spring-test, junit, testng, spock

Remember when writing unit test code, developers will be responsible for:

• Choosing & configuring the testing framework

• Making sure all required dependencies are included (for example external jars)

• Mocking all Crafter Engine classes used by the classes under testing

Setup Your Unit Test to Run With Gradle

To use Gradle the only requirement is to add a build.gradle in the root folder of the site repository and execute the test task. Example:

CRAFTER_HOME/data/repos/sites/SITENAME/sandbox/build.gradle

// Enable Gradle’s Groovy plugin
plugins {
  id 'groovy'
}

sourceSets {
  // Add the site Groovy classes that will be tested
  main {
    groovy {
      srcDir 'scripts/classes'
    }
  }

  // Add the Groovy classes & resources to perform the tests
  test {
    groovy {
      srcDir 'scripts/test/classes'
    }
    resources {
      srcDir 'scripts/test/resources'
    }
  }
}

// Enable the testing framework of choice
test {
  useJUnit()
}

repositories {
  mavenCentral()
}

// Include the required dependencies
dependencies {
  // This dependency is required for two reasons:
  // 1. Make Engine’s classes available for compilation & testing
  // 2. Include the Groovy dependencies required by Gradle
  implementation 'org.craftercms:crafter-engine:4.1.1:classes'

  // Include the chosen testing dependencies
  testImplementation 'junit:junit:4.13.2'
  testImplementation 'org.mockito:mockito-core:4.11.0'
}

Execute Your Unit Test

Given the previous example the tests can be executed using a single command:

gradle test

Example

Let’s take a look at an example of a groovy unit test in a site created using the empty blueprint with a custom groovy script, MyService

CRAFTER_HOME/data/repos/sites/SITENAME/sandbox/scripts/classes/org/company/site/api/MyService.groovy

package org.company.site.api

/*
  Custom service that will be invoked from other controllers like scheduled jobs, page or REST scripts
 */

interface MyService {

    def saveFormSubmission(def title, def author, def message)

    def getPostViews(def postId)

    def getPostsSummary(def date)

}

CRAFTER_HOME/data/repos/sites/SITENAME/sandbox/scripts/classes/org/company/site/api/MySearchService.groovy

package org.company.site.api

/*
  Service that wraps search to hide queries & result mapping from other services
 */

interface MySearchService {

    def getPostsForDate(def date)

}

CRAFTER_HOME/data/repos/sites/SITENAME/sandbox/scripts/classes/org/company/site/api/ExternalApi.groovy

package org.company.site.api

/*
  External service to store & retrieve data, in real life this could be using an external REST API or DB
 */

interface ExternalApi {

    def saveFormSubmission(def formId, def title, def author, def message)

    def getPostViews(def postId)

}

CRAFTER_HOME/data/repos/sites/SITENAME/sandbox/scripts/classes/org/company/site/impl/MyServiceImpl.groovy

package org.company.site.impl

import org.company.site.api.MySearchService
import org.craftercms.core.service.CachingOptions
import org.craftercms.core.util.cache.CacheTemplate
import org.company.site.api.ExternalApi
import org.company.site.api.MyService
import org.craftercms.engine.service.context.SiteContext

/*
  Implementation of the custom service
 */

class MyServiceImpl implements MyService {

    protected ExternalApi externalApi

    protected CacheTemplate cacheTemplate

    protected MySearchService searchService

    protected def formId

    protected def refreshFrequency

    def saveFormSubmission(def title, def author, def message) {
        return externalApi.saveFormSubmission(formId, title, author, message)
    }

    def getPostViews(def postId) {
        def context = SiteContext.current.context
        def options = new CachingOptions()
        options.refreshFrequency = refreshFrequency
        return cacheTemplate.getObject(context, options, { externalApi.getPostViews(postId) }, "post-views-", postId)
    }

    def getPostsSummary(def date) {
        def posts = searchService.getPostsForDate(date)
        return posts.collect { post ->
            [
                    id: post.id,
                    views: getPostViews(post.id)
            ]
        }
    }

}

Let’s begin creating our unit test for MyService

Designate Folder for All Test Related Files

The first thing we need to do is to designate a folder for all test related files. We’ll designate the /scripts/test folder to be used for all test related files.

Write Your Unit Test Code

Next, we’ll write the unit test code.

CRAFTER_HOME/data/repos/sites/SITENAME/sandbox/scripts/test/classes/org/company/impl/MyServiceImplTest.groovy

package org.company.site.impl

import org.company.site.api.ExternalApi
import org.company.site.api.MySearchService
import org.craftercms.core.service.Context
import org.craftercms.core.util.cache.CacheTemplate
import org.craftercms.engine.service.context.SiteContext
import org.junit.Before
import org.junit.Test
import org.junit.runner.RunWith
import org.mockito.InjectMocks
import org.mockito.Mock
import org.mockito.Spy
import org.mockito.junit.MockitoJUnitRunner

import static org.mockito.ArgumentMatchers.any
import static org.mockito.ArgumentMatchers.eq
import static org.mockito.Mockito.verify
import static org.mockito.Mockito.when

/*
  Tests for the custom service
 */

@RunWith(MockitoJUnitRunner)
class MyServiceImplTest {

    static final def FORM_ID = "myFormId"

    static final def POST_ID_1 = "myPostId1"

    static final def POST_ID_2 = "myPostId2"

    static final def POST_VIEWS_1 = 42

    static final def POST_VIEWS_2 = 0

    static final def REFRESH_FREQ = 5

    @Spy
    SiteContext siteContext

    @Mock
    Context context

    @Mock
    CacheTemplate cacheTemplate

    @Mock
    MySearchService searchService

    @Mock
    ExternalApi externalApi

    @InjectMocks
    MyServiceImpl myServiceImpl

    @Before
    void setUp() {
        myServiceImpl.formId = FORM_ID
        myServiceImpl.refreshFrequency = REFRESH_FREQ

        siteContext.context = context
        SiteContext.current = siteContext

        when(externalApi.saveFormSubmission(eq(FORM_ID), any(), any(), any())).thenReturn(true)
        when(externalApi.getPostViews(eq(POST_ID_1))).thenReturn(POST_VIEWS_1)
        when(externalApi.getPostViews(eq(POST_ID_2))).thenReturn(POST_VIEWS_2)

        when(cacheTemplate.getObject(eq(context), any(), any(), any())).then({ i -> i.getArgument(2).execute() })

        when(searchService.getPostsForDate(any())).thenReturn([
                [ id: POST_ID_1 ],
                [ id: POST_ID_2]
        ])
    }

    @Test
    void testFormSubmission() {
        def title = "My New Post"
        def author = "John Doe"
        def message = "Is this working?"

        assert myServiceImpl.saveFormSubmission(title, author, message) == true
        verify(externalApi).saveFormSubmission(eq(FORM_ID), eq(title), eq(author), eq(message))
    }

    @Test
    void testGetPostViews() {
        assert myServiceImpl.getPostViews(POST_ID_1) == 42
    }

    @Test
    void testGetPostsSummary() {
        def result = myServiceImpl.getPostsSummary(new Date())

        assert result.size() == 2
        assert result[0].views == POST_VIEWS_1
        assert result[1].views == POST_VIEWS_2
    }

}

Setup Your Unit Test to Run With Gradle

We’ll now setup our unit test to run with Gradle, by adding a build.gradle file in the root folder of the site repository and execute the test task.

CRAFTER_HOME/data/repos/sites/SITENAME/sandbox/build.gradle

plugins {
    id 'groovy'
}

sourceSets {
    main {
        groovy {
            srcDir 'scripts/classes'
        }
    }

    test {
        groovy {
            srcDir 'scripts/test/classes'
        }

        resources {
            srcDir 'scripts/test/resources'
        }
    }
}

test {
    useJUnit()
}

repositories {
    mavenCentral()
}

dependencies {
    implementation ('org.craftercms:crafter-engine:4.1.1:classes')
    compile 'javax.servlet:servlet-api:4.0.1'

    testImplementation 'junit:junit:4.13.2'
    testImplementation 'org.mockito:mockito-core:4.11.0'
}

Execute Your Unit Test

Finally, we can run our unit test by running gradle test

Output when running unit test

$ gradle test

BUILD SUCCESSFUL in 4s
3 actionable tasks: 3 up-to-date

Let’s take a look at the result of our unit test which can be found here: CRAFTER_HOME/data/repos/sites/SITENAME/sandbox/build/reports/tests/test/index.html

See Also

• Configuration Related to Building Custom Services