Design in Cascade concept

Templates, Configuration Sets, and Outputs: How a Page Gets Built

A published page in Cascade CMS is the result of several distinct asset types working together. Each layer has a specific job, and they build on each other from structure outward to content. Once you can name the layers and understand what belongs to each one, it becomes much easier to know where to look when something is wrong.

Quick decision guide

Use this table when deciding which asset type to inspect or modify.
If you need to change	Start with	Why
The overall page layout or region structure	Template	The template defines the shell and named regions a page can use.
How content is rendered inside a region	Format	The format transforms content into markup or another output.
Shared content reused across many pages	Block	Blocks centralize reusable content or data sources.
A different published representation such as XML or JSON	Output	Outputs let the same page publish in more than one form.

The asset layers

The assets involved in building a page fall into six layers. Each layer depends on the one before it.

Template

A Cascade asset that defines the structural skeleton of a page: the HTML shell and the named regions (header, main, sidebar, footer) that content fills. Templates live in the site asset tree alongside pages and blocks. A template defines where content goes — not what it says or how it is formatted.

Configuration Set

A managed asset that requires a template. It wraps that template and defines one or more Outputs (HTML, XML, JSON, etc.), each producing a different published file from the same page. Region assignments (which Format or Block fills which region) are configured per Output inside the Configuration Set. One page can publish in multiple forms from a single Configuration Set.

Data Definition and Metadata Set

Also managed assets, configured separately from the Configuration Set. The Data Definition defines the structured content fields editors fill in when editing a page (headline, body, author, etc.). The Metadata Set defines metadata fields (title, keywords, summary). Both get bundled into the Content Type in the next layer.

Content Type

Ties the Configuration Set, Data Definition, and Metadata Set into a single reusable package. Found under Manage Site > Content Types. When an editor creates a page using a Content Type, they get the right layout, the right fields, and all configured outputs in one step.

Page

An instance created from a Content Type. Lives in the site asset tree. Stores the actual content entered by editors. On publish, it produces every Output defined in the Configuration Set. The same page data can generate an HTML page and an XML feed in a single publish action.

Blocks and Formats

The content-filling layer. Formats (usually Velocity scripts) render content into markup. Blocks provide shared or dynamic content: an Index Block might pull the latest news items; a text block might hold a site-wide disclaimer. Both are assigned per-region per-output inside the Configuration Set, so two Outputs of the same page can use different Formats and pull from different Blocks.

Where to find each asset type in Cascade CMS.
Asset	Primary job	Where to find it
Template	Defines the HTML shell and named regions	Site asset tree
Configuration Set	Wraps a template with Outputs and region assignments	Manage Site > Configuration Sets
Data Definition	Defines the structured content fields on a page	Manage Site > Data Definitions
Metadata Set	Defines metadata fields (title, keywords, etc.)	Manage Site > Metadata Sets
Content Type	Bundles Configuration Set, Data Definition, and Metadata Set	Manage Site > Content Types
Page	Stores the actual content; publishes via the Content Type's outputs	Site asset tree
Format	Renders content into markup (usually Velocity)	Manage Site > Formats
Block	Provides shared or dynamic content to a region	Site asset tree (often in a `/_blocks/` folder)

End-to-end example

A news article page might be set up like this:

The Template defines a main region for the story body and a sidebar region for related links.
The Configuration Set wraps that template with two Outputs: an HTML output for the web page and an XML output for a news feed. Each output has its own region assignments.
The Data Definition defines the headline, body, author, and publish date fields. The Metadata Set covers the page title and keywords.
The Content Type bundles all of the above. Editors pick "News Article" when creating a page and get the right fields and outputs automatically.
The Page itself stores the article content. On publish, it produces both the HTML page and the XML feed entry from the same data.
In the HTML Output, the main region's Velocity Format reads the structured fields and renders the article. The sidebar region uses an Index Block and a Format to pull in related stories.
In the XML Output, a separate Format reads the same page fields and produces the feed-friendly structure. The sidebar region may be left unassigned.

If the article body looks wrong, check the page data and the Format for the main region in the HTML Output. If the sidebar is wrong, inspect the Block or query logic feeding that region. If the HTML is fine but the feed is wrong, check the XML Output and its Format in the Configuration Set.

Tip

When you are unsure which Region controls a piece of output, use Show Regions on the page preview first. It highlights each Region and tells you what Format and Block are assigned to it. This is usually faster than opening random Templates and Formats until you find the right one.

How to troubleshoot the wrong asset

Most design confusion comes from editing the right idea in the wrong place. Use this sequence when a page is not behaving the way you expect:

Identify the exact region where the issue appears. Use Show Regions on the page preview to highlight each region and see what Format and Block are assigned to it.
Confirm which Output you are looking at. The HTML preview and the live XML feed may render the same page through entirely different Formats. Make sure you are inspecting the right output before changing anything.
Check the Configuration Set for that Output. Open Manage Site > Configuration Sets and find the Output causing the issue. The region assignments there tell you exactly which Format and Block are in play.
Determine whether the problem is data, rendering, or structure. If the field value is wrong, the issue is in the page or data definition. If the value is correct but displays wrong, the issue is in the Format. If the region itself is missing, the issue is in the Template.
Confirm the Content Type is pointing to the right Configuration Set. A page created from the wrong Content Type will not have the expected outputs or fields, no matter how the template and formats are set up.

This sequence keeps you from changing a template when the real problem is in a format, or editing a page when the content actually comes from a block.

Common mistakes

Treating a Page as if it contains all the content visible on screen. Much of what appears on a page comes from Blocks, Formats, or Index Blocks.
Editing a Template when the bug is really in a Format's Velocity rendering logic.
Editing a shared Block without realizing it will affect every page that uses it.
Forgetting that alternate Outputs may use entirely different Formats with different rendering rules.
Confusing a Content Type with a Template. The Content Type bundles a Configuration Set, Data Definition, and Metadata Set, but it is not the layout itself. The Template sits one layer below, inside the Configuration Set.
Ignoring the Data Definition when troubleshooting missing fields. If a field is not in the Data Definition, it won't appear on the page editing form.

Common architecture trap

If every change requires editing templates, your implementation is probably putting too much page-specific content into layout assets. Templates should define structure. Page and shared content assets should carry the content itself.