Velocity Directives

Cascade CMS provides the $_PropertyTool which offers reliable methods for checking whether a value is null, empty, or blank. This is the recommended approach over manual null/empty checks.

## $_PropertyTool.isNotEmpty() — true when value is not null AND not empty
#set ($title = $currentPage.metadata.title)
#if ($_PropertyTool.isNotEmpty($title))
  <h1>$title</h1>
#end

## $_PropertyTool.isEmpty() — true when value is null or empty
#if ($_PropertyTool.isEmpty($currentPage.metadata.description))
  <meta name="description" content="Default description" />
#else
  <meta name="description" content="$currentPage.metadata.description" />
#end

## Negate with ! for "has a value" checks
#if (!$_PropertyTool.isEmpty($currentPage.metadata.title))
  <title>$currentPage.metadata.title</title>
#else
  <title>Untitled</title>
#end

## Check if a structured data field exists and has content
#set ($heroImage = "")
#set ($heroImage = $currentPage.getStructuredDataNode("hero-image"))
#if ($_PropertyTool.isNotEmpty($heroImage) && $heroImage.asset)
  <img src="$heroImage.asset.link" alt="$currentPage.metadata.title" />
#end

## Conditionally render based on metadata
#set ($pageType = "")
#set ($pageType = $currentPage.metadata.getDynamicField("page-type").value)
#if ($pageType == "landing")
  ## render landing page layout
#elseif ($pageType == "detail")
  ## render detail page layout
#else
  ## render default layout
#end

## Check if a collection has results
#set ($results = $_query.byContentType("news").execute())
#if ($_PropertyTool.isNotEmpty($results))
  ## render results
#else
  <p>No news articles found.</p>
#end

Velocity provides a built-in $foreach object with useful properties inside any #foreach loop:

#set ($news = $_query.byContentType("news-article").sortBy("startDate").sortDirection("desc").maxResults(10).execute())
#foreach ($article in $news)
  <article>
    <h2><a href="$article.link">$article.metadata.title</a></h2>
    <p>$article.metadata.description</p>
  </article>
#end

#set ($slides = $currentPage.getStructuredDataNodes("slide"))
#foreach ($slide in $slides)
  #set ($heading = "")
  #set ($heading = $slide.getChild("heading").value)
  #set ($caption = "")
  #set ($caption = $slide.getChild("caption").value)
  <div class="slide #if($foreach.first)slide--active#end">
    #if ($_PropertyTool.isNotEmpty($heading))
      <h2>$heading</h2>
    #end
    #if ($_PropertyTool.isNotEmpty($caption))
      <p>$caption</p>
    #end
  </div>
#end

## Build a comma-separated tag list
#set ($tags = $currentPage.metadata.getDynamicField("tags").values)
#foreach ($tag in $tags)${tag}#if($foreach.hasNext), #end#end
## Output: News, Featured, Campus Life

## Render a table from structured data with rows and columns
#set ($rows = $currentPage.getStructuredDataNodes("row"))
<table>
#foreach ($row in $rows)
  <tr>
    #set ($cells = $row.getChildren("cell"))
    #foreach ($cell in $cells)
      <td>$cell.value</td>
    #end
  </tr>
#end
</table>

## Find the first featured news article
#set ($featured = false)
#set ($results = $_query.byContentType("news").execute())
#foreach ($article in $results)
  #set ($isFeatured = "")
  #set ($isFeatured = $article.metadata.getDynamicField("featured").value)
  #if ($isFeatured == "Yes")
    #set ($featured = $article)
    #break
  #end
#end

#if ($featured)
  <div class="featured-article">
    <h2>$featured.metadata.title</h2>
    <p>$featured.metadata.description</p>
  </div>
#end

## Show only the first 3 visible items from a structured data group
#set ($items = $currentPage.getStructuredDataNodes("item"))
#set ($shown = 0)
#foreach ($item in $items)
  #set ($isVisible = "")
  #set ($isVisible = $item.getChild("visible").value)
  #if ($isVisible == "Yes")
    <div class="item">$item.getChild("title").value</div>
    #set ($shown = $shown + 1)
    #if ($shown >= 3)
      #break
    #end
  #end
#end

## Guard clause: stop if the page has no content type assigned
#set ($contentType = "")
#set ($contentType = $currentPage.metadata.getDynamicField("content-type").value)
#if ($_PropertyTool.isEmpty($contentType))
  <!-- Error: no content type configured for this page -->
  #stop
#end

## Rest of the template only runs if $contentType is set
<div class="$contentType">
  ## ...
</div>

Render a friendly empty state and stop, so the rest of the template (which assumes items exist) doesn’t try to iterate or render headings.

#set ($items = $currentPage.getStructuredDataNodes("item"))
#if ($items.isEmpty())
  <p class="empty-state">No items configured yet.</p>
  #stop
#end

## The rest of the template only runs when $items has content
<ul>
  #foreach ($item in $items)
    <li>$item.getChild("title").value</li>
  #end
</ul>

## Temporarily stop execution to inspect variables at this point
<pre>
  title: $currentPage.metadata.title
  results count: $results.size()
</pre>
#stop
## Everything below is skipped during debugging

Evaluate a Velocity snippet stored in a structured data field. Use this only when you control what goes into that field — never evaluate untrusted user input.

#set ($snippet = "")
#set ($snippet = $currentPage.getStructuredDataNode("velocity-snippet").value)
#if ($_PropertyTool.isNotEmpty($snippet))
  #evaluate($snippet)
#end

Use #define to prepare layout sections that adapt to context. The same block can appear in different places, picking up whatever data the surrounding code has set.

## Define a sidebar block that always reflects the latest $sidebarItems
#define ($sidebar)
  <aside class="sidebar">
    #foreach ($link in $sidebarItems)
      <a href="$link.link">$link.metadata.title</a>
    #end
  </aside>
#end

## Use it with different data sets on the same page
#set ($sidebarItems = $_query.byContentType("quick-link").maxResults(5).execute())
$sidebar  ## renders quick links

#set ($sidebarItems = $_query.byContentType("related-resource").maxResults(5).execute())
$sidebar  ## renders related resources with the same markup

Define a small badge once, reuse it inside a loop. Each reference re-evaluates $foreach.count and $items.size() against the current loop state.

#define ($badge)
  <span class="badge">Item $foreach.count of $items.size()</span>
#end

#set ($items = $_query.byContentType("news").execute())
#foreach ($item in $items)
  $badge <a href="$item.link">$item.metadata.title</a>
#end

Define the link markup once, reuse it after each card. The $item reference resolves lazily at render time, so each call picks up the current loop item.

#define ($readMore)
  <a href="$item.link" class="read-more">Read more →</a>
#end

#foreach ($item in $featured)
  <article>
    <h3>$item.metadata.title</h3>
    <p>$item.metadata.description</p>
    $readMore
  </article>
#end

A common Cascade CMS pattern is to use #parse to assemble a page layout from multiple shared Formats, each handling a different section of the page.

## Main page Format
#import ("_cms/formats/shared/macros/utility")
<!DOCTYPE html>
<html lang="en">
<head>
  <title>$currentPage.metadata.title</title>
  #parse ("_cms/formats/shared/head-assets")
</head>
<body>
  #parse ("_cms/formats/shared/site-header")

  <main>
    ## Page-specific content here
    $currentPage.getStructuredDataNode("body").value
  </main>

  #parse ("_cms/formats/shared/site-footer")
</body>
</html>

Variables set inside a #parsed Format remain in scope after the call returns. This can be useful (the parsed template can compute values for the caller), but it can also cause unexpected collisions.

## Inside _cms/formats/shared/head-assets:
#set ($siteName = "My University")
#set ($cssVersion = "3.2.1")
<link rel="stylesheet" href="/css/main.css?v=$cssVersion" />

## Back in the main Format, after the #parse call:
#parse ("_cms/formats/shared/head-assets")
## $siteName and $cssVersion are now available here
<title>$currentPage.metadata.title | $siteName</title>