Formats

Formats are used to transform XML data into XHTML, XML, text, or other meaningful markup formats.

Overview

Content in Cascade CMS is stored as XML data such as structured data from Data Definitions or XML from Index Blocks. In order to style that data for display on the web, it must be transformed into useful markup, and we use formats for this purpose.

You may choose between two templating languages to create Formats in Cascade CMS:

  • Velocity - Apache's Velocity Templating Language
  • XSLT - eXtensible Stylesheet Language Transformations
Formats of both types can be used in separate regions on the same page, but syntax from the two cannot be merged within the same script.

As a language, Velocity is procedural in nature. It takes several cues from Java, even employing several Java-based tools for string manipulation. String literals and variables in Velocity are derived directly from Java objects. The DateTool, for example, uses the same date formatting as in Java. Velocity users familiar with JavaScript and PHP may note some similarities in how code is written.

As a declarative language, XSLT formats are capable of transforming entire pages at once, given their close ties to XML. Prior users of XSLT should find immediate comfort in using XML data in Cascade CMS.

Uses for Formats

Formats can be applied along with blocks to a specific region in a page. Applying both the block and the format together ensures that the format will style the block’s XML content appropriately for that page before the block is assigned to a page region. Using formats with blocks also makes blocks reusable as one block can be styled in many different ways to output the same content with different looks and feels.

Formats can also be assigned to the default region of a page. In this case, the format styles the user-supplied structured data in a way that is meaningful for that page.

It's important to note that existing XSLT formats cannot be converted into Velocity formats directly. Pasting Velocity Templating Language (VTL) code into an existing XSLT format will result in an XML validation error upon submission.  A new format must be created in order to utilize VTL.

Creating a Format

To create a format:

  1. Click Add Content > Default > Format.
  2. Select Velocity or XSLT and click Choose.
  3. Enter a name for your format and select a Placement Folder.
  4. Enter your format content in the code editor.
  5. Click Preview Draft to preview the format and then click Submit to save your format.

Testing a Format

You can test your format on block or page content before the format is submitted by using the Test Format feature in the format editing area. This saves time and prevents you from having to make numerous small edits to incrementally test formats against assets to which the formats will be assigned. It also reduces the number of versions being generated for the asset because only final, tested changes need to be saved.

new ui in cascade 8

To test a format:

  1. Click Preview Options.
  2. Under Select an asset type, select one of the following options:
    1. Block & Context Page - Select any block in the system to be rendered in the preview area. For blocks that can make use of a context page (for example index blocks with no folder selected), a page can be selected to be used as the context page for the block so that a format can be written as if it were being applied to a page region with an implicit index block assigned.
    2. Context Page - Select any page in the system to be rendered in the preview area. WYSIWYG pages will have their WYSIWYG content rendered in the preview area, and Data Definition pages will have their structured data rendered in the preview area. That is unless the default region of the page being previewed has a block assigned to it in which case the block content will be rendered. Note that any format assigned to the page's default region will be ignored so that the format currently being edited can be applied to the raw page content.
  3. Click Test Format.

The results rendered when the format in the editor is applied to the chosen XML will be displayed in the bottom pane.

Assigning Formats

Both Velocity and XSLT formats can be assigned to individual regions at the page, Configuration, or Template level. However, only XSLT formats be applied to the entire page at the page, Configuration, or Template level.

A format assigned to a region will transform the content of the block assigned to that region. In the case of the default region, it's possible to assign a format without a block. In this case, the page's Structured Data XML or the raw WYSIWYG HTML will be used as the content to which the format is applied.

An XSLT format assigned to a page will transform the complete assembled content of that page after all the region level formats have been applied.

Inheritance of Format Assignments

Configurations inherit and can optionally override the format assignments of its associated Template. Pages inherit and can optionally override the format assignments of its associated Configuration.

The page level is the most specific level in the block/format assignment hierarchy in that changes to block/format assignments will only affect a single page. In contrast, changing a block/format assignment on a configuration will affect any page using that configuration. Assignments at the page level will place a page icon next to the particular region that was overridden when viewing the Configurations tab of the page.

Example: Your site map uses a specific index block and a unique format. Rather than setting up a new Configuration that will only be used for one page, you can override the block/format assignment on the actual page.

Current Versions

Velocity 1.7 is the current version used as of Cascade CMS 8.0. Versions of Cascade CMS earlier than 6.10 support Velocity 1.5.

XSLT version 1.0 is supported in Cascade CMS 8.0 and previous releases.