$article.metadata.title
$article.metadata.description
$subtitle
## shows PREVIOUS item's subtitle if current item has none #end ``` The fix is to reset the variable before each assignment: ```velocity ## CORRECT: reset before each #set to avoid stale data #foreach ($item in $items) #set ($subtitle = "") #set ($subtitle = $item.getChild("subtitle").textValue) #if ($_PropertyTool.isNotEmpty($subtitle))$subtitle
#end #end ``` > **Tip** > > For a deeper discussion of variable scoping, the reset-before-set idiom, and how `#set` behaves inside macros, see the [Variable Scope](https://www.hannonhill.com/cascadecms/latest/articles/developing-in-cascade/script-formats/velocity-variable-scope.html) article. ## #if / #elseif / #else Conditional directives control which portions of the template are rendered based on boolean expressions. ```velocity #if ($condition) ## rendered when $condition is true #elseif ($otherCondition) ## rendered when $otherCondition is true #else ## rendered when none of the above are true #end ``` 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. ```velocity ## $_PropertyTool.isNotEmpty() — true when value is not null AND not empty #set ($title = $currentPage.metadata.title) #if ($_PropertyTool.isNotEmpty($title))No news articles found.
#end ``` > **Note** > > In Velocity, `#if ($var)` evaluates to false when `$var` is null or boolean false, but its behavior with empty strings can be inconsistent. Using `$_PropertyTool.isEmpty()` and `$_PropertyTool.isNotEmpty()` removes that ambiguity. If your value is being assigned inside a loop, see the [#set](#velocity-directives-set) section for the reset-before-set pattern. ### Comparison operators | Operator | Meaning | Example | | --- | --- | --- | | `==` | Equal to | `#if ($status == "published")` | | `!=` | Not equal to | `#if ($type != "hidden")` | | `>` | Greater than | `#if ($count > 0)` | | `<` | Less than | `#if ($count < 10)` | | `>=` | Greater than or equal | `#if ($count >= 1)` | | `<=` | Less than or equal | `#if ($count <= 100)` | | `&&` | Logical AND | `#if ($a && $b)` | | `\|\|` | Logical OR | `#if ($a \|\| $b)` | | `!` | Logical NOT | `#if (!$isHidden)` | ## #foreach The `#foreach` directive iterates over a collection (list, array, map, or query result set) and repeats its body for each element. ```velocity #foreach ($item in $collection) ## loop body — $item changes on each iteration #end ``` Velocity provides a built-in `$foreach` object with useful properties inside any `#foreach` loop: | Property | Description | Example value (3 items) | | --- | --- | --- | | `$foreach.index` | Zero-based index of the current iteration | 0, 1, 2 | | `$foreach.count` | One-based count of the current iteration | 1, 2, 3 | | `$foreach.hasNext` | True if there are more items after this one | true, true, false | | `$foreach.first` | True on the first iteration only | true, false, false | | `$foreach.last` | True on the last iteration only | false, false, true | ```velocity #set ($news = $_.query().byContentType("news-article").sortBy("startDate").sortDirection("desc").maxResults(10).execute()) #foreach ($article in $news)$article.metadata.description
| $cell.textValue | #end
$featured.metadata.description
No items configured yet.
#stop #end ## The rest of the template only runs when $items has content` dump to inspect what variables contain at that point in the template, without rendering any output below it. ```velocity ## Temporarily stop execution to inspect variables at this pointtitle: $currentPage.metadata.title results count: $results.size()#stop ## Everything below is skipped during debugging ``` > **Tip** > > Place `#stop` after a `` block that dumps variable values to create a quick-and-dirty debugging checkpoint. Remember to remove it before publishing. ## #macro The `#macro` directive defines a reusable block of Velocity code that can accept parameters. Macros help you avoid duplicating template logic across your Formats. ### Defining and calling macros ```velocity ## Define a macro #macro (renderCard $page $extraClass) #set ($rc_title = "") #set ($rc_title = $page.metadata.title) #set ($rc_desc = "") #set ($rc_desc = $page.metadata.description)#end ## Call the macro #set ($results = $_.query().byContentType("page").maxResults(6).execute()) #foreach ($item in $results) #renderCard($item "card--featured") #end ``` ### Scope leaking Variables set with `#set` inside a macro are **not** scoped to that macro. They write directly to the same namespace as the calling Format, which means they can silently overwrite variables in the outer context. ```velocity ## BUG: macro overwrites the outer $title #macro (renderHeading $page) #set ($title = $page.metadata.title)$rc_title
#if ($_PropertyTool.isNotEmpty($rc_desc))$rc_desc
#end$title
#end #set ($title = "My Page Title")$title
## "My Page Title" #renderHeading($someOtherPage)$title
## now shows the OTHER page's title! ``` The fix is to prefix all variables inside macros with a unique identifier to avoid collisions: ```velocity ## CORRECT: prefix macro variables to avoid collisions #macro (renderHeading $page) #set ($rh_title = $page.metadata.title)$rh_title
#end #set ($title = "My Page Title")$title
## "My Page Title" #renderHeading($someOtherPage)$title
## still "My Page Title" ``` > **Important** > > Velocity macros do not have their own scope. Every `#set` inside a macro writes to the calling template’s namespace. Use a naming prefix (e.g. `$rc_`, `$nav_`) for macro-internal variables. See the [Variable Scope](https://www.hannonhill.com/cascadecms/latest/articles/developing-in-cascade/script-formats/velocity-variable-scope.html) article for more details. ## #import The `#import` directive includes the contents of another Velocity Format from the CMS into the current template. This is how you share macros, utility functions, and common template fragments across multiple Formats. ### Syntax ```velocity ## Import a shared macro library #import ("_cms/formats/shared/macros/utility") ``` The path is relative to the root of the site in Cascade CMS. After importing, all macros and variables defined in the imported Format are available in the current template. ### Common pattern: shared macro library ```velocity ## In _cms/formats/shared/macros/utility (the imported Format): #macro (truncate $text $maxLength) #if ($_PropertyTool.isEmpty($text)) #elseif ($text.length() > $maxLength) ${text.substring(0, $maxLength)}... #else $text #end #end ## $date is a java.util.Date (metadata date fields already return one) #macro (formatDate $date $pattern) #if ($date)$_DateTool.format($pattern, $date)#end #end ``` ```velocity ## In the main Format: #import ("_cms/formats/shared/macros/utility") ## Now you can use the macros#truncate($currentPage.metadata.description, 150)
``` > **Performance** > > Each `#import` directive requires a round trip to the database to fetch the Format’s contents. Consolidate related macros into fewer Formats to minimize the number of `#import` calls. See the [Best Practices for Performance](https://www.hannonhill.com/cascadecms/latest/articles/developing-in-cascade/script-formats/velocity-best-practices.html) article for detailed guidance. ## #evaluate `#evaluate` takes a string and processes it as Velocity code at runtime. The most common use in Cascade is calling a macro whose name is stored in a variable: you build the directive call as a string, then evaluate it. This lets a single dispatcher macro route to any named macro without a chain of `#if`/`#elseif` branches. ### Syntax ```velocity #evaluate($stringContainingVelocityCode) ``` ### Examples A dispatcher macro that calls any named macro by building the call string at runtime. The `$"+"data"` split prevents Velocity from trying to resolve `$data` inside the string literal before `#evaluate` runs. ```velocity ## Dispatcher: call any macro by name #macro(runMacro $name $data $origin) #set ($macroBuild = "#" + $name + "($" + "data $" + "origin)") #evaluate($macroBuild) #end ## Usage — $name is resolved at call time #runMacro("heroBlock" $pageData "default") ``` If the macro lives in another Format, `#import` that Format by path first, then dispatch with `#runMacro`. Use a `site://` path for a Format in another site. ```velocity ## Import the Format that defines the macro (path string, not an API object) #import ("site://Global/_components/hero") ## Now dispatch to the macro by variable name #set ($macroName = "heroBlock") #runMacro($macroName $pageData "default") ``` 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. ```velocity #set ($snippet = "") #set ($snippet = $currentPage.getStructuredDataNode("velocity-snippet").textValue) #if ($_PropertyTool.isNotEmpty($snippet)) #evaluate($snippet) #end ``` > **Use sparingly** > > `#evaluate` executes code that isn’t visible in the Format, which makes templates harder to read and debug. Only evaluate strings you control. When the set of possible values is small and known, `#if`/`#elseif` branching or `#macro` parameters are usually clearer. ## #define `#define` captures a block of Velocity code that is **not** evaluated immediately. Instead, the block is evaluated each time the variable is referenced. This makes it behave like a reusable template fragment that always reflects the current state of your variables. ### Syntax ```velocity #define ($blockName) ## template content here — evaluated later, not now #end ``` ### How it differs from #set `#set` evaluates the right-hand side immediately and stores the result as a fixed value. `#define` stores the block as unevaluated code and re-evaluates it every time the variable is referenced. This distinction matters whenever the variables inside the block change between the point of definition and the point of use. ```velocity ## #set evaluates immediately (snapshot) #set ($count = 0) #set ($message = "Count is $count") #set ($count = 5) $message ## outputs: Count is 0 ## #define evaluates lazily (live feed) #set ($count = 0) #define ($message)Count is $count#end #set ($count = 5) $message ## outputs: Count is 5 ``` ### Examples The most common use for `#define` is a template fragment re-evaluated inside a loop. Because the block evaluates fresh each iteration, it picks up the current loop variable. ```velocity ## Define a card template once, reuse it in the loop #define ($card)#end #set ($results = $_.query().byContentType("page").execute()) #foreach ($item in $results) $card ## re-evaluates each iteration with the current $item #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. ```velocity ## Define a sidebar block that always reflects the latest $sidebarItems #define ($sidebar) #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. ```velocity #define ($badge) Item $foreach.count of $items.size() #end #set ($items = $_.query().byContentType("news").execute()) #foreach ($item in $items) $badge $item.metadata.title #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. ```velocity #define ($readMore) Read more → #end #foreach ($item in $featured)$item.metadata.title
$item.metadata.description
#end ``` ### #define vs #macro Both `#define` and `#macro` let you reuse template blocks, but they work differently: | Feature | #define | #macro | | --- | --- | --- | | Parameters | None — relies on variables already in scope | Accepts explicit parameters | | Evaluation | Lazy — re-evaluated each time the variable is referenced | Evaluated when called | | Scope | Reads from the current scope at evaluation time | Shares the caller’s scope (no isolation) | | Reuse across Formats | No — local to the current template | Yes — can be imported via `#import` | | Best for | Template fragments reused within one Format | Utility functions shared across Formats | > **Tip** > > Think of `#set` as taking a photo (captured once) and `#define` as a live camera feed (always shows the current state when viewed). Use `#define` when you want a reusable template block that adapts to changing variables. Use `#set` when you want a fixed snapshot. See the [Variable Scope](https://www.hannonhill.com/cascadecms/latest/articles/developing-in-cascade/script-formats/velocity-variable-scope.html) article for more examples. ## #parse The `#parse` directive includes and evaluates another Velocity template inline. The parsed template shares the same variable context as the calling template—variables set before `#parse` are available inside the parsed Format, and variables set inside the parsed Format are visible in the caller after the call. ### Syntax ```velocity #parse ("_cms/formats/shared/header-fragment") ``` The path is relative to the root of the site in Cascade CMS, just like `#import`. ### Differences from #import | Feature | #import | #parse | | --- | --- | --- | | Primary use | Loading macro definitions | Including template fragments that produce output | | Variable sharing | Macros become available; variable side effects may occur | Full variable context is shared both ways | | Output | Typically produces no direct output (macro definitions only) | Output is rendered inline at the point of the `#parse` call | | Database cost | One round trip per call | One round trip per call | ### Examples Since `#parse` shares the caller’s variable context, set variables before the call to control how the parsed template behaves. This is how you pass “parameters” to a parsed Format. ```velocity ## Main Format: set variables, then parse the fragment #set ($navStyle = "horizontal") #set ($showSearch = true) #parse ("_cms/formats/shared/navigation") ``` ```velocity ## Inside _cms/formats/shared/navigation: ## $navStyle and $showSearch are available here from the caller ``` 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. ```velocity ## Main page Format #import ("_cms/formats/shared/macros/utility") $item.metadata.title
$item.metadata.description
$readMore$currentPage.metadata.title #parse ("_cms/formats/shared/head-assets") #parse ("_cms/formats/shared/site-header")## Page-specific content here $currentPage.getStructuredDataNode("body").textValue #parse ("_cms/formats/shared/site-footer") ``` Variables set inside a `#parse`d 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. ```velocity ## Inside _cms/formats/shared/head-assets: #set ($siteName = "My University") #set ($cssVersion = "3.2.1") ``` ```velocity ## Back in the main Format, after the #parse call: #parse ("_cms/formats/shared/head-assets") ## $siteName and $cssVersion are now available here$currentPage.metadata.title | $siteName ``` > **Performance** > > Like `#import`, each `#parse` call requires a database round trip. Use naming prefixes in parsed Formats to avoid variable collisions with the caller, just as you would with macros.