Locator Tool

Features

Cascade v7.4+

Locator Tool is available only on versions 7.4 and higher. If you're not on 7.4 or higher, you're missing out!

Native to Cascade CMS

The Locator Tool was created by the makers of Cascade CMS and is native to Cascade.

Dynamically Locates Assets

Dynamically locates assets and return Cascade API objects, not XML elements.

No XML

Locator Tool works with API objects and do not need an XML file to access data.

No Index Blocks

No XML data, so no index block is needed.

Methods Can Be Used w/ Query Tool Results

Works with API objects so it can be used on results fetched with the Query Tool.

XPath Tool Vs Locator Tool

The XPath Tool traverses XML nodes, which means:

To access data, it requires an XML document.
To produce an XML document, it requires an index block.
Works with XML elements only, not API objects.
Cannot access object methods and attributes.

Variables and Directives

The Locator Tool is a Velocity feature; therefore, it uses Velocity syntax. Variables and directives are syntactically the same.

Example: Setting a Variable

    #set($variable = "string value")

Example: If-Else Statements

    #if(conditional)
       // code section
    #elseif(conditional)
       // code section
    #end

Syntax: Invoking Methods

Velocity tools are typically invoked by its name preceded by the $_ denoter. For tools that handle API objects, the denoter also contains a dot at the end. Here are some examples of the more commonly used locator tool methods:

$_.locatePage()

$_.locateBlock()

$_.locateFolder()

$_.locateSymlink()

The locator tool can also be invoked for the following asset types: template, reference, linkable, symlink, and format.

Implicit Method:

Takes in TWO parameters to locate the asset.

$_.locatePage(PATH, SITENAME)

Explicit Method:

Takes in THREE parameters to determine which type of asset to find and where to find it.

$_.locate(PATH, TYPE, SITENAME)

Parameters

Implicit Method is More Common

Example: Locate this specific page (Locator Tool) from this specific site (Advanced Velocity 2019 - Master).

#set($currPage = $_.locatePage('adv-velocity-1/_training-pages/locator-tool', 'Advanced Velocity 2019 - Master'))

The second parameter is optional. If a site name argument is not passed in, it will be defaulted to the current site.

Example:

#set ($currPage = $_.locatePage('adv-velocity-1/_training-pages/locator-tool'))

This will return the same result as the above as long as the page the call from is within this site (Advanced Velocity 2019 - Master).

If this this call was made from a different site, then the site name argument should be passed in as a parameter as shown in the first example.

Arbitrary Parameters

Passing in Variables to the Locator Tool

Variables representing a string for the path or site name can be passed in as follows:

#set($path      = 'index')
#set($site      = $currentPage.site.name)
#set($indexPage = $_.locatePage($path, $site))

Concatenation of Parameters is not possible. For instance, when trying to access the Web Services landing page, the following will not work.

#set($site       = 'Advanced Velocity 2019 - Master')
#set($folderPath = 'adv-velocity-1/profiles')
#set($indexPath  = $_.locatePage($folderPath + '/index', $site))

Instead, use the Velocity code delimiter (curly brackets) to denote the Velocity variable and be sure to use double quotes instead of single quotes.

Example:

#set($site       = 'Advanced Velocity 2019 - Master')
#set($folderPath = 'adv-velocity-1/profiles')
#set($indexPath  = $_.locatePage("${folderPath}/index", $site))

This will return the landing page for the Web Services section of this workshop.

Built-in Variables

$currentPage [v7.10 +]
Returns an object.

$currentPagePath [ v7.4+ ]
Returns a string.

$currentPageSiteName [ v7.4+ ]
Returns a string.

Consider the examples to the right. Results shown are specific to the built-in variables being called from this page.

Example: $currentPage

com.hannonhill.cascade.api.adapters.PageAPIAdapter@241936b6

Example: $currentPagePath

adv-velocity-1/_training-pages/locator-tool

Example: $currentPageSiteName

Advanced Velocity 2019 - Master

Example: Application

Return the same results as $currentPage

$_.locatePage($currentPagePath, $currentPageSiteName)

$_.locatePage($currentPagePath)

Practice

Locator Tool Exercises # 1 - 3

Get Started

Extra Practice (Take Home)

Locator Tool Exercise # 4