Formats

Accessing page data in Velocity

Overview

When you write a Velocity Format in Cascade, most of what you do boils down to one question: how do I get at the data on the page? This guide covers the basics: the global variables Cascade provides for free, the built-in and custom metadata fields available on every page, and the page properties you'll use most often. Almost everything starts with $currentPage, so that's where we'll begin.

Global variables

Cascade exposes a handful of global variables in every Velocity Format. You don't need to #set them or import anything. They're just there.

Global variables available in Velocity Formats.
Variable	Output Type	Description
`$contentRoot`	Element	Returns a JDOM Element containing the XML supplied for the current region.
`$currentPage`	PageAPIAdapter	Returns the current page as an API object.
`$currentPagePath`	String	Returns the path of the current page.
`$currentPageSiteName`	String	Returns the name of the current page's site.
`$enabledCustomDirectives`	ArrayList	Returns all available custom directives in the CMS environment.

Of these, $currentPage is the most important, and the one you'll use most. Unlike the others, which return a single value, $currentPage hands you the entire page as an object you can dig into: its metadata, structured data, path, parent folder, tags, and more.

Here's what each variable looks like when you print it directly:

$currentPage
## com.hannonhill.cascade.api.adapters.PageAPIAdapter@3fc3692

$currentPagePath
## /path/to/index

$currentPageSiteName
## My Site

$currentPage prints as an object reference because it is an object. You need to ask it for something specific (its title, its path, a structured data node) to get a value out. The other two are already strings, so they print as-is.

Pro tip: Don't reuse these names as your own variables. If you write #set ($currentPage = ...), you've just shadowed the original, and there's no way to get it back in that scope.

For the full list of Velocity Tools and global variables, see Velocity Tools.

Accessing built-in metadata

Every page has a Metadata Set attached to it, and the built-in fields from that set are reachable through the metadata property on $currentPage:

$currentPage.metadata

That returns the metadata object on its own, which isn't much use yet. Chain a field name onto it to read a specific value:

$currentPage.metadata.title
## Accessing Page Data in Velocity

$currentPage.metadata.displayName
## Accessing Page Data

$currentPage.metadata.description
## A short summary of the page.

$currentPage.metadata.startDate
## Wed Feb 18 00:34:00 EST 2026

Notice the format of startDate. That's the default Date object's toString() output. To control how it's displayed, use the Date Tool's formatting methods. See Date Tool Essentials for the patterns.

The other built-in fields follow the same pattern:

$currentPage.metadata.summary
$currentPage.metadata.teaser
$currentPage.metadata.keywords
$currentPage.metadata.author
$currentPage.metadata.endDate
$currentPage.metadata.reviewDate

Pro tip: Notice the pattern: each . takes you one level deeper into the asset's data. This is called dot notation, and you'll see it everywhere in Cascade Velocity. The more properties you chain together, the more specific the data you can access (when available).

Accessing dynamic (custom) metadata

Custom metadata fields (the ones defined on the Metadata Set beyond the built-ins) work a little differently. Instead of being available as a direct property, they're accessed through a method:

$currentPage.metadata.getDynamicField("example-name")
## com.hannonhill.cascade.api.adapters.DynamicMetadataFieldImpl@1357674b

The string you pass in is the field's Name value from the Metadata Set (not its label). What you get back is the field node. To get the actual value, chain the value property onto it:

$currentPage.metadata.getDynamicField("example-name").value
## example value

Pro tip: Notice the difference between a property and a method. A property is accessed with just .name, while a method uses parentheses and can accept arguments, like .name(args). Both patterns appear throughout Cascade Velocity.

For details on configuring custom metadata in the Cascade UI, see Metadata Fields.

Commonly used page properties

$currentPage exposes far more than just metadata. Here are the properties you'll reach for most often:

#set ($label = $currentPage.label)
#set ($url = $currentPage.link)
#set ($path = $currentPage.path)
#set ($parentFolderPath = $currentPage.parentFolder.path)
#set ($siteName = $currentPage.site)
#set ($dataDefinitionName = $currentPage.dataDefinition.name)
#set ($assetType = $currentPage.assetType)
#set ($systemName = $currentPage.name)
#set ($systemTags = $currentPage.tags)

A note on .label: .label uses Display Name first, then falls back to Title if Display Name is empty, then to System Name if both are empty. That makes it a safe choice when you want a human-readable label for the page without writing fallback logic yourself.

Discovering what's available with the Property Tool

How do you know what properties and methods $currentPage (or any other object) supports? Use the Property Tool. Its outputProperties() method lists everything an object exposes, along with the type of data each one returns:

$_PropertyTool.outputProperties($currentPage)

The output looks something like this (trimmed for readability):

Object type: com.hannonhill.cascade.api.adapters.PageAPIAdapter
Properties:
 - assetType: String
 - contentType: ContentType
 - dataDefinition: StructuredDataDefinition
 - getStructuredDataNode(String): StructuredDataNode
 - label: String
 - link: String
 - metadata: Metadata
 - name: String
 - parentFolder: Folder
 - path: String
 - site: Site
 - structuredData: StructuredDataNode[]
 - tags: List

The Property Tool is the fastest way to answer "what can I do with this object?". Point it at anything (a page, a folder, a structured data node, a chooser asset) and it will tell you.

Heads up: The Property Tool lists possible properties based on the object's type, not what's actually populated. For example, it will show .value as a property when called on a group structured data node, but groups don't have a value of their own (their data lives in their children), so the result is empty. Treat the output as a map of what's reachable, not a guarantee of what's there.

For the full Property Tool reference, see Velocity Tools.

See Accessing data definition nodes in Velocity for the full walkthrough.

↑