Developing in Cascade

Accessing data definition nodes in Velocity

How to read structured data from a page's Data Definition with getStructuredDataNode() and getChild(): root-level nodes, nested children, multi-value variants, path syntax, and how to verify your access is working.

Accessing page data in Velocity

A beginner's walkthrough of reading page data inside Cascade Velocity Formats: global variables, built-in metadata, dynamic metadata fields, and the most common page asset properties.

Best practices for performance

When working with choosers, it is important to save repeated .asset calls to a variable and then access that variable's methods directly. Failure to do so will result in multiple r

Code sections

Cascade CMS currently supports the use of two types of code sections in the system: Passthrough code sections and protect code sections.

Configuring a robots meta tag

A worked example: a Metadata Set checkbox field plus a Velocity Format that outputs a robots meta tag with noindex and nofollow values.

Creating a sitemap

A sitemap helps search engines crawl your site more efficiently. It provides a structured list of pages, improving SEO and ensuring updates are picked up faster. Sitemaps are especially important for large sites or those with complex folder structures.

CSS and Front-End Assets

Getting stylesheets into your pages, exposing classes to WYSIWYG editors, and making CSS-referenced images resolve to managed assets.

Date Tool essentials

Retrieve, parse, format, and compare dates in Velocity with the Date Tool, including how to handle the millisecond timestamps Cascade CMS stores.

Filtering queries based on multi-value fields

The Query API cannot filter on checkbox or multi-select fields directly, so run the broader query and test each result with hasTextValue.

Formats

Formats transform the XML behind a Cascade CMS page into the markup you publish. How Velocity and XSLT differ, when to use each, and how to create and apply a Format.

Getting started with REST

Worked read-then-edit examples against the REST API in jQuery, fetch, async/await, and PHP.

Hashmaps and arrays

Build and read hashmaps and arrays in Velocity — literal syntax, adding and retrieving entries, iterating them, and the type pitfalls that catch people out.

How can I redesign a site using our existing content?

Add a second Output using your new Templates and publish it to a test Destination, then swap the default Output when the design goes live.

How can I set up canonical tags?

Two worked examples: a self-referencing canonical tag, and a Shared Field group that lets editors point a page at an alternative canonical URL.

How do I access a chooser field's chosen asset?

Check that an asset is actually chosen before reading its properties, using the API's asset property or an XPath test on the path element.

How do I add a "title" tag to my page?

Place the system-page-title tag inside your Template's title element so Cascade renders each page's metadata Title.

How do I add a code snippet to my content?

Deciding where a snippet belongs — tag manager, Template, Configuration, or single page — and how to add it without tripping XML validation.

How do I apply CSS?

Upload a CSS file, link to it from an XML Block, and attach that Block to a Template region at the Template, Configuration, or Page level.

How do I create an XML output for a page?

Add a non-publishable XML Output to a Configuration so you can view the system-generated XML for any page using it.

How do I include a page's ID in its contents?

Output the currentPage identifier from a Format attached to a head region, useful for deep linking from Siteimprove, DubBot, and similar tools.

How do I include Open Graph or Twitter card meta tags in my page?

Add a system region to your Template's head and attach a Format that generates social meta tags from the current page's metadata and structured data.

How do I make an XML sitemap?

A complete recipe for a sitemap page: the Velocity Format, Template, Index Block, Configuration, and Content Type it needs.

How do I make CSS classes available in the WYSIWYG formats drop-down menu?

Choose a CSS file on a WYSIWYG Editor Configuration, then use Custom Styles to limit which classes editors can pick.

How do I sort on a Calendar field?

Calendar values are MM-dd-yyyy strings, so build a lookup table of numeric timestamps and sort on that instead.

How do I view sample XML when editing a Format?

Use the Preview Options dropdown when editing a Format to render sample XML from a Block, or a Block plus a context page.

How to update deprecated Velocity code

Replacements for the reflection-based patterns that no longer work, mapped to their modern Velocity Tool equivalents.

Implementation Strategy

Approaches to common build problems — sitemaps, code snippets, shared includes, and redesigning a site against existing content.

Internal Cascade API

The internal Cascade API exposes a set of operations to developers for code run within Cascade CMS in Formats, Publish Triggers, Asset Factory Plugins, and other types of plugins.

Internal Cascade API changelog

New methods added to existing Cascade API objects New com.hannonhill.cascade.apl.asset.common.PermissionLevel enum added with values NONE, READ and WRITE New methods added to com.hannonhill.cascade.apl.asset.home.PermissionsCapableAsset getAllPermissionLevel() - returns the PermissionLevel&#160

JSON schema for a page

Build reusable page-level JSON-LD in Cascade CMS using Velocity, with region vs head-format patterns, #import usage, and metadata-first fallback/null-safe logic.

Output content as JSON

Combine a skip-tag Template, a Format using SerializerTool.toJson inside a protect code section, and a JSON Output to publish content as a .json file.

Publish Triggers

Publish Triggers are plug-ins that can be utilized during the publishing process. They allow developers to execute custom logic each time an asset (page, file, or other content item) is published.

Query Tool directives

Introduced in Cascade CMS 8.26, Query Directives are an alternative to the .execute() method on the Query API. They process results one asset at a time instead of loading

REST API

Cascade CMS REST API is a lightweight API for interfacing with Cascade's Web Services.

REST API operations

Reference for every operation in the Cascade CMS REST API — read, edit, create, publish, workflow, message, and preference calls, each with its endpoint and a sample response.

REST API placeholders

The placeholders that stand in for values in Cascade CMS REST API endpoint documentation — {auth} for credentials, {identifier} for the asset being addressed, and {wsdl} for the operation's message body.

Retrieving image dimensions

Learn how to access an image's width and height in Cascade CMS using the Cascade API (via structured data node or locateFile) or an Index Block with Velocity.

SEO and Page Metadata

Outputting the tags search engines and social platforms read — title, robots, canonical, Open Graph — and building an XML sitemap.

SOAP Web Services

Web services provide Cascade CMS users with a powerful way to work with the system by providing a powerful back-end interface with which to interact.

SOAP Web Services changelog

Release-by-release changes to the Cascade CMS SOAP Web Services API — new operations, new and modified fields, and behaviour changes.

SOAP Web Services operations

When looking through the WSDL, you can find all of the operations available along with their responses at the top.

System pseudo-tags

System pseudo-tags are special system tags that instruct Cascade CMS to act on the content contained within them.

Testing for an empty WYSIWYG field

A WYSIWYG field can hold plain text or HTML elements, so test both the element's value and whether it has children.

The {auth} placeholder

{auth} Either: The user's API Key can be provided within the request's Authorization header as a Bearer token.Example: Authorization: Bearer 27c03f58-7c79-45d1-aa8f-76d697bbb10d The user's username and password can be provided within the request's Authorization header using a Basic authent

The {identifier} placeholder

How to address an asset in a Cascade CMS REST API call — by site name and path, or by the asset's id — and when each form is the right one.

The {wsdl} placeholder

{wsdl} JSON structure defined in Cascade instance's WSDL file, which can be viewed by appending /ws/services/AssetOperationService?wsdl to Cascade's URL in the web browser.

Variable scope in Velocity

Understand how variable scope works in Velocity, including the difference between global and loop-scoped variables, common pitfalls with #set and null values, macro scope leaking, and when to use #define vs #set.

Velocity directives

Reference for the core Velocity directives used in Cascade CMS, including #set, #if, #foreach, #break, #stop, #macro, #import, #evaluate, #define, and #parse, with practical examples and common pitfalls.

Velocity Tools

Cascade CMS's Velocity Tools are a collection of functions that can be used to retrieve and manipulate content in conjunction with Apache Velocity Template Language.

Why am I seeing system-region tags around my published content?

Cascade adds system region tags when rendered content isn't valid XML. Wrap the region in a dummy tag inside a cascade-skip code section.

Why aren't my CSS background images being displayed?

Background image paths need system-asset tags and the Rewrite asset links in file option so Cascade can resolve them to managed assets.

Working with a collection of assets

There are many scenarios where you'll need to be able to iterate over a collection of assets within the CMS.

Working with namespaces in Velocity

Three ways to reach a namespaced XML element: addNamespace, an XPath prefix, or XPath local-name() for hidden namespaces.

Working with Server Side Includes

Publish an HTML snippet as its own page, then pull it into other pages with an SSI directive so a change needs one publish instead of a full site publish.