Cascade Server Technical Primer

Introduction

Welcome to Cascade Server!

This introduction is the perfect place to start for users that are experiencing Cascade Server for the first time. In presenting the basics of Cascade, we will walk you through a step-by-step process for creating and publishing a very simple website from scratch. After the initial learning curve has been mastered, creating and managing content in Cascade Server is a breeze.

Prerequisites

Before we begin, make sure you have all of the following:

  • A running instance of Cascade Server (a non-production instance is recommended)
  • A fresh copy of the Default Database provided by Hannon Hill
  • A Global Administrator level user account.
  • A text editor of your choice (Notepad, TextEdit, Coda, Eclipse, etc)
  • A basic knowledge of XHTML
  • About 2 hours of time -- Because you're reading and creating for the first time

Login to Cascade Server

We will begin by logging into Cascade Server. In your browser, navigate to the login screen for your instance using your favorite browser, supply valid credentials, and click Login In.

Cascade Server is supported by the all major browsers -- Internet Explorer 7+, Firefox 2-10, Safari 3+, and Chrome.

Login Screen

After logging in to Cascade Server, you will be directed to your Dashboard. This dashboard is personalized for each user and provides easy access to a Starting Page, New Content Wizards, the Recycle Bin, outstanding Workflows, Messages, Locked Assets, Drafts, and a recent history. The Dashboard is different for each Site that you have access to and will list assets and links relative to the Site that you are currently in.

Create a New Site

We will first start by creating a new Site into which we will begin uploading and creating our assets. Sites in Cascade Server are containers for organizing all Home and Administration area assets for a website. They allow for segmenting content in the system and provide a way to allow a user to have different Roles and access rights depending on what Site they are in.

Note that when Site is capitalized in documentation, reference is being made to the Cascade Server notion of a Site; when site is lowercase, reference is being made to the more generic idea of a website.

  • Navigate to System → Site Management using the Menu Bar Navigating to the Site Management Area
  • Click Create a new Site Create a new Site
  • For the Name field type Introduction
  • For the URL field type http://www.example.edu
  • Click Submit to create the new Site

After submitting, you should see the new Site appearing in both the list of Sites on the left as well as the Sites drop-down at the top of the Cascade Server interface. Select the Introduction Site from the drop-down to enter the new Site. Once inside the Site you will be presented with your customized Dashboard relative to the new Site and an empty Asset Tree on the left side.

Organizing Site Assets

To follow best practices, it is recommended to organize assets in the Asset Tree in folders respective to the asset types, but this is by no means required. The folder structure used in the Asset Tree should be built to fit the individual needs and preferences of each organization. If used as recommended, these folders will only contain assets used internally by Cascade Server and never published out to a web server.

Each new Site comes with a Container for creating generic assets inside a Site. You can find these Default Asset Factories on the menu bar under New → Default. There are 7 Default Asset Factories for creating Blocks, Links, Files, Folders, Formats, Pages, or Templates.

Create New Folder

Create the following folder structure in the Asset Tree:

  • _cascade
    • base-assets
    • blocks
      • index
      • xhtml
    • formats
    • templates
  • _files
    • css
    • images

It is recommended that the _cascade folder is not checked for publishing or indexing. This setting will ensure that the internal assets are not published to the web server or mistakingly indexed as Site content. It is also recommended that the _files folder is not checked for indexing to ensure that the supplemental assets are not mistakingly indexed as Site content.

This folder structure reflects an organized method for storing and managing the internal assets that can be used across multiple Sites and Pages within the application.

Prepare a Site Template

We will create a simple Template which will serve as the framework for all of our future Page assets. Templates contain one or more regions that specify areas where content can be applied. We will create a simple Template in a text editor and then import it into Cascade Server. Templates can also be manually created inside Cascade Server, but more often than not implementations begin by importing an existing Template, so we'll show off how this can be accomplished.

To create a new Template:

  • Open your favorite text editor and type the following XHTML structure (shout out to HTML5 support):
    <!DOCTYPE html>
    <html lang="en-US" xml:lang="en-US" xmlns="http://www.w3.org/1999/xhtml">
    <head>
    <meta charset="utf-8" />
    <title><system-page-title/></title>
    </head>
    <body>
    <header>
        <system-region name="HEADER"/>
    </header>
    <nav>
        <system-region name="NAVIGATION"/>
    </nav>
    <div id="content">
        <system-region name="DEFAULT"/>
    </div>
    <footer>
        <system-region name="FOOTER"/>
    </footer>
    </body>
    </html>
    
  • Save this file to your local machine as an HTML file (e.g. template.html)

The <system-region> tag is the most basic and essential system tag that Cascade Server provides. This tag defines regions within a Template where content can be inserted. In our example, we have created a region named DEFAULT which we will dynamically populate with page content. All Templates should include a DEFAULT region, which serves as the primary editable region of a page.

Once you have created the Template and stored it on your local machine, it is time to import it into Cascade Server.

  • Navigate to the BaseFolder → _cascade → templates directory in the Asset Tree
  • Use the Menu Bar to create a New → Default → Template Create New Template
  • For the System Name field type Basic
  • To import the Template you can either copy/paste the XHTML code into the XML window or use the File Upload dialog
  • Click Submit

This Template will serve as the structure for your Cascade Server Pages. It will provide the design around your content and allow you to create many different Pages, with potentially different styles, that use the same Page structure and design.

The Template is the first of five assets that is created in order for Page assets to be used.

Creating a Configuration Set

When creating Pages inside Cascade Server, Configuration Sets are just one of the assets with the CMS that help with the separation of content from design. Configuration Sets help users manage and edit a large number of Pages that share common characteristics. Template regions can also be utilized at the Configuration Set level to allow for design flexibility. Pages that differ in content can share a Template and allow for regions to be used in different ways.

To create a new Configuration Set:

  • Navigate to Administration → Configuration Sets using the Menu Bar
  • Select New Configuration Set in the Configuration Set Asset Tree Create New Configuration Set
  • For the Name field type Simple Page
  • Click Submit

The initial creation screen for a new Configuration Set will automatically create a single Configuration. It will be completely blank and even have the name of (unnamed).

On the initial Configuration:

  • For the Name field type Standard
  • For the Template field choose the Basic Template in the /_cascade/templates folder
  • For the Publishable field check the box that reads Configuration can be published
  • For the Output File Extension field type .html
  • Click Submit

The Configuration Set is the second of five assets that is created in order for Page assets to be used.

Creating a Metadata Set

Metadata is data within the CMS that describes an asset. Common fields such as title, summary, or keywords provide quick information about the content contained inside of a particular asset. These Metadata Sets can be applied to all Home Area assets inside the CMS. A Metadata Set is simply a custom combination of the available fields and options for an asset type.

We will create a Metadata Set for our Simple Page so that we can manage how Metadata is captured without having an impact on other Pages.

To create a new Metadata Set:

  • Navigate to Administration → Metadata Sets using the Menu Bar
  • Select New Metadata Set in the Metadata Set Asset Tree
  • For the Name field type Simple Page
  • Toggle the Title field to Inline
  • Toggle all other fields to Hidden
  • Click Submit

It is recommended that fields not being used are hidden to ensure that other users don't interact with fields that might change the way the asset is published and indexed around the system.

Note that we did not select to make any of these fields required.

The Metadata Set is the third of five assets that is created in order for Page assets to be used.

Creating a Data Definition

A Data Definition allows for Cascade Server users that have little or no knowledge of web formatting standards to enter content via simple form fields. That content can then be output into a structured page that already fits the overall website look and feel. The Data Definitions are attached to a Page type for a structured method of capturing and displaying content.

To create a new Data Definition:

  • Navigate to Administration → Data Definition using the Menu Bar
  • Select New Data Definition in the Data Definition Asset Tree
  • For the Name field type Simple Page
  • Click Submit

The Data Definition Builder is a drag and drop interface that can create 14 different types of content capturing fields. Each field has options for identifiers, labels, values, and advanced options.

Create New Data Definition

Data Definitions can also be authored through XML. Click the XML Pane just below the Create Tab and paste in the following XML:

<system-data-structure>
  <text identifier="body-title" label="Body Title"/>
  <text wysiwyg="true" identifier="body-content" label="Body Content"/>
</system-data-structure>

The Data Definition is the fourth of five assets that is created in order for Page assets to be used.

Creating a Content Type

Content Types provide a way for formally aggregating Configuration Sets, Metadata Sets, and Data Definitions into a single administrative component that is applied to a Page. Content Types provide a logical way for users to identify the proper type to associate a Page with by grouping together the necessary settings and content fields.

To create a new Content Type:

  • Navigate to Administration → Content Type using the Menu Bar
  • Select New Content Type in the Content Type Asset Tree
  • For the Name field type Simple Page
  • For the Configuration Set field to search/browse the Simple Page Configuration Set
  • For the Metadata Set field to search/browse the Simple Page Metadata Set
  • For the Data Definition field to search/browse for the Simple Page Data Definition
  • Click Submit

The Content Type is the fifth asset that is created in order for Page assets to be used.

Creating Static Content Blocks

Managing content from a single asset and having that content be reused in multiple locations, and potentially in multiple Sites, is a huge differentiator for Cascade Server. Static XHTML Blocks are one of the many ways to manage a piece of content and use it in several different locations.

We will create basic XHTML Blocks that are used in the HEADER and FOOTER regions of our Template.

Header Block

  • Visit http://www.hannonhill.com/downloads/logo_hannonhill.png and download the Hannon Hill logo locally
  • Navigate to the BaseFolder → _files → images directory in the Asset Tree
  • Use the menu bar to create a New → Default → File Create New File
  • Use the File Upload dialog below the File Contents editor to browse for the image on your local machine
  • Click Submit

Now that the image has been uploaded into the system, we can create an XHTML Block . To create an XHTML Block:

  • Navigate to the BaseFolder → _cascade → blocks → xhtml directory in the Asset Tree
  • Use the menu bar to create a New → Default → Block
  • For the Block Type ** select **XHTML/Data Definition Block
  • For the System Name field type site logo
  • In the WYSIWYG editor click the Insert/edit image toolbar button
  • Use the Image Chooser combo box to search/browse for logo_hannonhill.png
  • For the Alternate Text field type Hannon Hill Logo
  • Click Insert
  • Click Submit

Footer Block

  • Navigate to the BaseFolder → _cascade → blocks → xhtml directory in the Asset Tree
  • Use the menu bar to create a New → Default → Block
  • For the Block Type ** select **XHTML/Data Definition Block
  • For the System Name field type site footer
  • In the WYSIWYG editor click the Edit HTML source toolbar button and enter the following code
    <p>Copyright Hannon Hill. All rights reserved.</p>
    
  • Click Update
  • Click Submit

Assigning Static XHTML to Page Regions

With our static blocks of code for our HEADER and FOOTER regions created, it is time to assign those Blocks to Template regions. The reason we will be assigning these Blocks directly to the Template is because they will be inherited into the Page regions on a large scale. All Page assets that make use of a particular Template will inherit Block and Format information into the regions that have assignments.

To assign the Blocks to the Template:

  • Navigate to the BaseFolder → _cascade → templates directory in the Asset Tree
  • Click the Basic Template and then click to Edit
  • Toggle to the Regions Pane of the Template
  • Find the HEADER and FOOTER regions
  • Use the Block Chooser combo boxes to search/browse for the respective Blocks Template Region Assignment

Creating a Page asset

How that we have gone through the process of creating a Template (with assigned Blocks), Configuration Set, Metadata Set, Data Definition, and Content Type, we can create a Page asset. We still have a few more steps in order for our Page to be fully functional, but we will go ahead and create the Page. We do this in order to take advantage of the XML output. This raw XML data set will be beneficial for writing our Format as it points out in plain text the XML nodes that we must reference for accessing our content for display purposes.

The initial Page that we create we will use as the basis for other Pages that can be created quickly and effectively. We will use this first Page as the "Base Asset" for an Asset Factory (also known as a Content Wizard).

To create the Page:

  • Navigate to the BaseFolder → _cascade → base-assets directory in the Asset Tree
  • Use the menu bar to create a New → Default → Page
  • For the System Name field type simple-page
  • Toggle to the System Pane of the new Page
  • Use the Content Type Chooser combo box to search/browse for the Simple Page Content Type
  • Click Submit

Note that we left all fields blank and submitted the form. It is usually recommended that "base assets" are left completely empty so that when an end user interacts with the Asset Factory, a blank version of the page is present to them for filling in their own, original content.

Dynamic Content Blocks

With the "base asset" in place, we can start working on a way to have the Page content dynamically placed into the Page. As each Page is loaded, they may share the same Template code and possible content regions. We want the content to change as we move from Page to Page. One of the major benefits of Cascade Server is the separation of content from design. The content is stored as XML in the back-end database and it inserted into Page regions (which are defined in the Template) through the use of static and/or dynamic Index Blocks.

The first dynamic Index Block that we will create will serve the purpose of loading the Page content into the DEFAULT region of Template. As a user clicks to view different Pages, the underlying Template code will remain the same as the body content in the DEFAULT region changes based on the Index Block's rendering. This Index Block is called a calling page Block.

Format Transformations

Paired with an Index Block, a Format in Cascade Server parses XML and helps transform raw data into another format. XML data can accessed and then wrapped inside of XHTML tags, PDF FO tags, or even RSS tags. Again, the system separates content from design by storing asset information as XML. This leads to greater flexibility when it is time to output the information. Page fields that have no style information (text inputs, drop-down menus, etc) store just the core content while allowing you to define the style aesthetics every time that piece of information should be output into the Template design.

The Format uses the XML structure of the paired Index Block for accessing the XML data. Each Index Block can have a different XML structure, so it is important to understand how Formats process the XML node structure.

For this example, the Index Block we just created has a core structure as follows:

<system-index-block current-time="1337619570322" name="current page" type="folder">
    <calling-page>
        <system-page current="true" id="36d151ae7f000001006c8343adff4a59">
            <name>page-name</name>
            <!-- Metadata Set fields listed here as XML nodes -->
            <path>/path/to/page-name</path>
            <site>site name</site>
            <link>site://site name/path/to/page-name</link>
            <system-data-structure definition-path="Simple Page">
                <!-- Custom Data Definition fields listed here as XML nodes -->
            </system-data-structure>
        </system-page>
    </calling-page>
</system-index-block>
Our Format needs to traverse this specific XML node structure for accessing node data and using it to output XHTML. As you create more Index Blocks for other purposes, knowing the XML data structure is important as it will dictate how you will create the Format. It is also worth noting that a single Index Block can be used multiple times across different Page types and have a different Format paired with it each time. The same single source of content can be repurposed in different ways depending on the Page type and region.

There are two languages that are supported within Cascade Server for doing XML data transformations: XSLT and Velocity.

Let me be clear that you are NOT locked in to using only one language or the other. Both languages can be used throughout the system. You can even use both Format types on the same Page. Information that disputes this statement is false.

To create a Format:

  • Navigate to the **BaseFolder → _cascade → formats ** directory in the Asset Tree
  • Use the menu bar to create a New → Default → Format
  • For the Format Type ** select **XSLT or Script
  • For the System Name field type simple page content
  • If you chose Script, in the Content field paste the following Velocity:
    ## Velocity transformation
    ## Reference to the system-page XML node
    ## Reference to the system-data-structure XML node
    #set ( $page = $_XPathTool.selectSingleNode($contentRoot, "/system-index-block/calling-page/system-page") )
    #set ( $data = $page.getChild("system-data-structure") )
    ## Reference to the body-title XML node
    ## Reference to the body-content XML node
    #set ( $title = $data.getChild("body-title") )
    #set ( $content = $data.getChild("body-content") )
    ## XHTML code for the system-region
    <h1>$_EscapeTool.xml($title.value)</h1>
    $_SerializerTool.serialize($content, true)
    
  • If you chose XSLT, in the Content field paste the following XSLT:
    <xsl:stylesheet version="1.0" xmlns:xsl="http://www.w3.org/1999/XSL/Transform">
    <!-- XSLT transformation -->
    <!-- Match on the root system-index-block XML node -->
    <xsl:template match="/system-index-block">
        <!-- Apply available template to the system-page XML node -->
        <xsl:apply-templates select="calling-page/system-page"/>
    </xsl:template>
    <!-- Match on the system-page XML node -->
    <xsl:template match="system-page">
        <!-- Apply available template to the system-data-structure XML node -->
        <xsl:apply-templates select="system-data-structure"/>
    </xsl:template>
    <!-- Match on the system-data-structure XML node -->
    <xsl:template match="system-data-structure">
        <!-- XHTML code for the region -->
        <h1><xsl:value-of select="body-title"/></h1>
        <xsl:copy-of select="body-content/node()"/>
    </xsl:template>
    </xsl:stylesheet>
    
  • Click Submit

Assigning Block and Format for Structured Page Content

Pages with Data Definitions require Block and Format assignments for accessing and displaying the content. We have create a Block and Format for gathering and displaying the content for our Simple Page. We will assign the Block and Format as a pair to the DEFAULT region of the Page. We will assign these two assets at the Configuration Set level so that only Pages using the Simple Page Configuration Set are affected. This means that as new Page types are created, they can share the same Template asset but choose to using the Template regions in a different way.

To assign a Block and Format to a Configuration Set:

  • Navigate to Administration → Configuration Set using the Menu Bar
  • Click the Simple Page Configuration Set and then click to Edit
  • Click the Standard Configuration
  • Find the DEFAULT region
  • Use the Block Chooser combo box to search/browse for the calling page Block
  • Use the Format Chooser combo box to search/browse for the simple page content Format
  • Click Submit

Creating an Asset Factory

Asset Factories provide a framework which allows users to create new assets with all of the necessary options, configuration, and content fields already in place. An end-user does not need to worry about the Template being assigned or the Data Definition fields, Administrators have created a blueprint asset that already contains all of the important assignments that an end-user will need. Users will select from a pre-determined list of Asset Factories for which asset type they would like to create.

To create an Asset Factory:

  • Navigate to Administration → Asset Factories using the Menu Bar
  • Select New Asset Factory in the Asset Factory Asset Tree
  • For the Asset Factory Type field select Page
  • For the Name field type Simple Page
  • For the Base Asset Field field use the Chooser combo box to search/browse for simple-page in the /_cascade/base-assets directory
  • Toggle to the Plugins Pane of the Asset Factory
  • In the Add Plugin drop-down menu select Title to System Name Plugin and click the green plus icon to the right
  • Click Submit

We have now created a custom Asset Factory (or Content Wizard) for users to interact with. You should now see your custom Asset Factory listed as a selectable menu item in the New drop-down on the Menu Bar. When users select this option, a new Page will be initialized for them that already has the appropriate Content Type attached.

Note that we still have all optional fields in our new Asset Factory asset. This is because we created a "base asset" earlier that needed to remain blank. At this point you should now revisit the Metadata Set and Data Definition for marking certain, important fields required.

With a custom Asset Factory available, you should be able to create basic Pages in the Asset Tree to build out a basic, example Site. Once we have completed a Site, albeit a rather small one, our next step is to publish it out to a web server. Next, we will setup the components needed for publishing and then publish out the entire Site.

Publishing a Site

You'll need the following pieces of information for setting up publishing:

  • The publishing URL, i.e. where on the web will this Site be viewed
  • Login credentials to a web server, i.e. username/password for writing/removing files through (S)FTP

The first piece of information is publishing URL. Earlier in the process, when we created a new Site object, we provided a URL for the Site (http://www.example.edu). We need to update this piece of information, which will allow Cascade Server to know exactly what URL should be used during the publish process for creating the links/path to each asset.

To update the Site URL:

  • Navigate to System → Site Management using the Menu Bar
  • Click the Introduction Site and click Edit
  • Update the URL field Update Site URL
  • Click Submit

Note that you should make sure you are still within you Site. Double-check the Site drop-down menu above the Menu Bar for your location being the Site called Introduction. If it is not, select that site from the Site drop-down menu.

The login credentials to the web server you want to publish to are attached to an asset we call the Transport. The Transport is how you connect to where you want to publish. The other half of the publishing asset is called the Destination. The Destination is where on the web server (which directory) you want to publish the files in. Separating these two assets can be beneficial when you are managing multiple Sites that are stored on the same web server. One Transport can be used by multiple Destinations for publishing three or four Sites into different directories on the same server.

To create a Transport:

  • Navigate to Administration → Transport using the Menu Bar
  • Select New Transport in the Transport Asset Tree
  • For the Transport Type field select FTP and SFTP
  • Fill in the required fields and provide the appropriate information for connecting to your web server Example Transport
  • Click Submit

To create a Destination:

  • Navigate to Administration → Transport using the Menu Bar
  • Select New Destination in the Destination Asset Tree
  • For the Transport field use the Chooser combo box to search/browse for your Transport
  • For the Activation field make sure that Enable destination is checked
  • For the Web URL type the same publishing URL used in the Site Management area Example Destination
  • Click Submit

We will now publish out the Site to the web server. To publish out the Site:

  • Click Home using the Menu Bar
  • Navigate to Base Folder using the Asset Tree
  • Click on the Publish Tab
  • Verify that your Destination is checked
  • Click Submit

You can check the progress of your publish job in real time by navigating to System → Publisher → Active Jobs from the Menu Bar. Check your (S)FTP server and verify that all of the assets published out correctly. When the publish job is complete, you should also receive a Message in your Home Dashboard detailing the publish job.

Wrapping Up

Congratulations!

You have created a Site entirely from scratch and published that Site out to a web server. Hopefully this Technical Primer laid a foundation for understanding Cascade Server and increased your confidence and abilities.