Index Blocks

Overview

An index block is a special type of block that returns a listing of assets from the CMS directory structure in the form of XML data. Assets like pages, files, folders, external links, and even other blocks can be returned as XML content. An index block can even return the data content of multiple pages within a directory for use on other pages within the system.

Index blocks may also be used to return a listing of all pages of a particular content type. For example, all news articles found in a particular site may be lumped into a "news articles" index block.

In Cascade CMS, index blocks are typically used for creating dynamic navigation menus, site maps, indices, etc.

Because index blocks can be configured to index an entire site or a specific folder, the way you configure index blocks in your system will vary depending on your needs and specifications. You can choose to create index blocks that are limited by either the number of assets in a given folder, or by the number/depth of folders to index. To ensure dynamic and consistent content across your site, any time content relevant to that index block in the system changes (a page is added, deleted, renamed, moved, etc.), the index block automatically updates, and all pages using the index block are also updated.

Creating an Index Block

To create an index block:

  1. Click Add Content > Default > Block.
  2. Select Index and click Choose.
  3. In the Name field, enter a name for your block.
  4. In the Placement Folder field, choose the folder where the block should be created.
  5. Under Index Block Settings, configure the following options:
    • Folder Index - Choosing this option will generate block contents based on the contents of the specified folder. If you want the block to index nested folders, simply select the highest folder.
      • Rendering Behavior - This field has a great deal of impact on the structure of the rendered XML. It is important to choose a type of rendering behavior that is best suited to the purpose of a particular index block.
        • Render normally, starting at the indexed folder - This is the most common option and allows one to preview the rendered block XML in most cases when viewing the index block itself. This option renders data starting at the "Index Folder", and renders its children forward at a depth specified in the "Depth of Index" field. Subfolders will be included in the render, along with their children, to the extent to which the depth of index will allow.
        • Start at the current page and include its folder hierarchy - One may think of this as a backwards render. This rendering option depends on a current page context. That is, that this option requires that the index block be rendered in a region of a page (it is for this reason that you may not see XML in the "view" of an index block asset in Cascade CMS). The rendering will start at the current page, render it, and then proceed to render each parent folder until the base folder is rendered. These index blocks tend to be rather small, and are well-suited for breadcrumb navigation generation.
        • Start at the current page with folder hierarchy, and also include siblings - This option is like the "Start at the current page and include its folder hierarchy" option, except that for each parent folder asset rendered, it will also render that folder's children as well. For example, when rendering with his option, the renderer will start at the current page and render all of the siblings of that page, including the page itself. It will then render the parent folder and all of its siblings, repeating until the base folder is rendered. Note that this option will not continue to render sibling folders as the parent folder hierarchy is traversed.
        • Start at the current page with folder hierarchy, siblings, and also render forward - This option expands on the "Start at the current page with folder hierarchy, and also include siblings" rendering option, but also includes rendering the siblings of the current page, exactly the same way that the normal rendering option would render the current page's parent folder. This option is in effect, a combination of the "Render normally, starting at the indexed folder" and the "Start at the current page with folder hierarchy, and also include siblings" options.
      • Depth of Index - If you only want one folder indexed, type in 1. If there are nested (or child) folders that you wish to include, type in the number of levels you want. If you are indexing all levels, but aren't sure how many there are, it is ok to overshoot (i.e. 100).
    • Content Type Index - Choosing this option will generate block contents based on pages that share the specified Content Type.
    • Max Rendered Assets - Determine how many assets you wish to be rendered. Limiting this number is useful when you want to return only the most recent pages, for example.
    • Indexed Asset Content - This allows you to determine what information is included in results. These results may be styled or filtered via an accompanying script format.
      • Append Calling Page Data - Appends data from the page which includes this index block.
      • Regular Content - Includes content visible to users when editing.
      • System Metadata - Includes system information such as when the asset was created and last updated, and by whom.
      • User Metadata - Includes metadata the user can change.
      • Tags - Includes tags assigned to the asset.
      • Folder Access Rights - Includes permission information such as user and group names and their level of access.
      • User Information - Includes information about the current user.
      • Workflow Information - Includes the asset's workflow information, if applicable.
    • Indexed Asset Types - This allows you to limit the types of assets. For most navigation features, only pages and links need to be indexed.
    • Page XML - This field controls how page XML is rendered inline during an index block render. Note that Regular Content must be indexed in order to render page XML.
      • Do not render page XML inline - This option will not include any XHTML or Data Definition content for any page that is included in the index block render.
      • Render page XML inline - Default region content will be included for any page that is included in the index block render. For XHTML pages, it will be the XHTML/WYSIWYG content that one typically edits in the page. For pages with a Data Definition, it will be the rendered as XML. Note that for pages with a Data Definition, this XML will not have any XSLT applied to it.
      • Render page XML inline only for current page - This is exactly like the "Render page XML inline" option, but only the current page is rendered in this manner. All other pages that are included in the index block render will not have the default page content included for those pages in the resulting document.
    • Block XML - This field controls how block XML is rendered inline during an index block render. Note that Regular Content must be indexed in order to render block XML.
      • Do not render block XML inline - This is the default and does not render any block content inline.
      • Render XHTML/Data Definition block, XML block, and Text block XML inline - This option will render inline the contents of any block in the overall document.
    • Sort Method - This determines the order in which assets are rendered. "Folder Order" refers to ordering content via the drag-and-drop folder view and can be useful in setting up custom navigation.
    • Sort Order - This determines whether the assets are sorted in ascending or descending order.
  6. Click Preview Draft and Submit.
Note - In general, rendering inline page and block content will increase the size of the index block and will increase the amount of time needed to render the index block. Because this could slow down page load times in Cascade CMS, it's recommended that this option only be used if necessary.

Indexed Asset Content

Regular Content

Regular Content
<path> The path from the root of the site.
<site> The site-link notation of the asset (only available in a site).
<link> The site-link notation of the asset (only available in a site).
<display-name> The "Display Name" metadata field.
<file-size> The size (in bytes) of a file (only available for files). 
<height> The height (in pixels) of an image file (if present). 
<width> The width (in pixels) of an image file (if present). 

System Metadata

Metadata populated by Cascade CMS automatically.

System Metadata
<is-published> Returns "true" if the asset has Include when publishing checked or "false" if the asset does not have Include when publishing checked.
<created-by> The username of the user who created the asset.
<created-on> Timestamp of when the asset was created.
<last-modified-by> The username of the user who last modified the asset.
<last-modified> Timestamp of when the asset was last modified.

User Metadata

Any metadata populated by a user (except Display Name, which is rendered in Regular Content).

User Metadata
<title>  
<summary>  
<author>  
<teaser>  
<keywords>  
<description>  
<start-date> UNIX timestamp of the start-date.
<end-date> UNIX timestamp of the end-date.
<dynamic-metadata> The element that holds <name> and <value> for dynamic metadata fields. 
<name> The name of the dynamic metadata field.  Child element of <dynamic-metadata>.
<value> The value of the dynamic metadata field.  There can be multiple <value> nodes for checkbox field types.

Folder Access Rights

Information about the access rights of the assets.

Folder Access Rights
<access-rights> All the access rights information is contained in this element.
<user> Each user's permissions are in this element. If a user does not have read or write permissions to the asset, the <user> node is not rendered.  <user> has <name> and <permssion> as children elements.
<name> Username
<permission> The values read or write.
<group> Each group's permissions are in this element. If a group does not have read or write permissions to the asset, the <user> node is not rendered.  <group> has <name> and <permssion> as children elements.
<name> The name of the group.
<permission> The values read or write.

User Information

Adds an element after rendering the assets (i.e. towards the bottom of the index block) with information about the user accessing the page inside Cascade CMS. This information can be helpful for generating pages for view inside of Cascade CMS specific to the user.

User Information
<user-information> The element that contains all the user information nodes.
<username> The username of the user currently accessing the index block (i.e. your username when viewing the index block).
<full-name> The current user's full name.
<groups> Contains <group> nodes for each group for the user.
<group> The group's name.

Workflow Information

Contains any workflow information about the asset.

Workflow Information
<workflow> The element that contains all the workflow information.
<initialized> If the workflow has started: true or false are the values.
<name> The name of the workflow.
<owner> The username of the workflow's owner (i.e. the user who started the workflow).
<related-entity-id> The unique Cascade CMS identifier of the asset in workflow.
<related-entity-type> The entity type of the asset in workflow: page, block, file or symlink.
<start-date> The date the workflow began (in the format: MMM DD, YYYY hh:mm a).
<end-date> The date the workflow expires (in the format: MMM DD, YYYY hh:mm a).
<status> The workflow's status: In Progress or Completed.
<current-step> If <status> is In Progress, information about the step the workflow is in currently.
<step> Element that contains all the information about the current step.
<identifier> The step's unique name.
<name> The name of the step.
<type> The type of step: edit, transition, or system.
<owner> The user or group the step is assigned.
<owner-type> Either user or group.
<started-one> The date the step was started (in the format: MMM DD, YYYY hh:mm a).
<actions> Element that contains <action> elements with the information about each action this step contains.
<action> Element that contains information about the action.
<identifier> The action's unique identifier.
<name> The name of the action.
<action-type> The type of action: forward, reverse, or explicit.
<entity-information> Contains additional information about the entity attached to this workflow.
<id> The entity's unique Cascade CMS identifier.
<cache-path> The path of the entity from the root of the site.
<name> The name of the entity.
<type> The entity type: page, file, block or symlink.
<lock-information> Contains information who has the entity locked with the element <lock-owner>.
<lock-owner> The name of the user who has locked the entity.
<steps> Contains <step> elements for each ordered step in the Workflow Definition.  (See <step> above).
<unordered-steps> Contains <step> elements for each unordered step in the Workflow Definition (See <step> above).
<histories> Contains <history> elements for each change in the workflow.
<history> Element that represents an update to the workflow.
<who> Username of who updated the workflow.
<timestamp> The date the update occurred (in the format: MMM DD, YYYY hh:mm a).
<action-name> The name of the action used to update the workflow.
<comments> Any user comments entered after the action was taken.
<source-step-name> The name of the step where this update occurred.
<dest-step-name> The name of the step where the update takes the workflow.

Append Calling Page Data

Adds all information about the current page using this index block.

<calling-page> - Contains all information about the current page in a <system-page> element.

Examples of Index Block XML

The examples below show a portion of an index block for each of the four types of indexed assets: folder, page, file, and external link.

All index blocks begin with the following XML document element:


                <system-index-block name="index-block" type="folder" current-time="1245954924080">

In this example, index-block is the system name of the block asset, and the index block is a folder index block. The current-time attribute is the Cascade CMS server's local time at which the index block was rendered represented as a Unix timestamp in milliseconds.

A Content Type index block would start with the following:


                <system-index-block name="index-block" type="content_type" current-time="1245954924080">

Note that Content Type index blocks do not display folder structure using <system-folder> elements. They inherently only contain <system-page> elements, because Content Types can only be assigned to pages.

The following sections demonstrate index block XML for a page without a Data Definition, a page with a Data Definition, a folder containing a single page, a file, and an external link, an index or feed block, and an XHTML, XML, or text block.

Page without a Data Definition


                <system-page id="ef81d1c90a00016b00659a66bcacb166">  
      <name>page</name>  
      <is-published>true</is-published>  
      <title>Lorem Ipsum Dolor Sit Amet</title>  
      <summary>Lorem ipsum dolor sit amet, consectetur adipiscing elit.</summary>  
      <author>Author Name</author>  
      <teaser>Teaser</teaser>  
      <keywords>Comma, Separated, Keywords</keywords>  
      <description>Description</description>  
      <display-name>Lorem Ipsum</display-name>  
      <path>/index-block-example/page</path>  
      <created-by>admin</created-by>  
      <created-on>1245263810949</created-on>  
      <last-modified-by>admin</last-modified-by>  
      <last-modified>1245954849582</last-modified>  
      <page-xhtml>  
         <p>Lorem ipsum dolor sit amet, consectetur adipiscing elit.</p>  
         <p>Lorem ipsum dolor sit amet, consectetur adipiscing elit.</p>  
         <p>Lorem ipsum dolor sit amet, consectetur adipiscing elit.</p>  
      </page-xhtml>  
   </system-page>

Page with a Data Definition


                <system-page id="ef8c30b10a00016b00659a66495b1501">  
      <name>structured-data-page</name>  
      <is-published>true</is-published>  
      <title>Online Marketing Intern</title>  
      <author>Author Name</author>  
      <teaser>Teaser</teaser>  
      <keywords>Comma, Separated, Keywords</keywords>  
      <description>Description</description>  
      <display-name>Marketing Intern</display-name>  
      <path>/index-block-example/structured-data-page</path>  
      <created-by>admin</created-by>  
      <created-on>1245264490577</created-on>  
      <last-modified-by>admin</last-modified-by>  
      <last-modified>1245954890668</last-modified>  
      <system-data-structure definition-path="Job Posting">  
         <opening>  
            <job-title>Lorem ipsum</job-title>  
            <summary>Lorem ipsum dolor sit amet, consectetur adipiscing elit.</summary>  
         </opening>  
         <responsibilities>  
            <bullet-point>Help manage our search engine optimization (SEO) &amp; pay-per-click (PPC) campaigns</bullet-point>  
            <bullet-point>Help plan annual conference event and customer communications</bullet-point>  
            <bullet-point>Write marketing copy</bullet-point>  
         </responsibilities>  
         <requirements>  
            <bullet-point>Strong interpersonal skills</bullet-point>  
            <bullet-point>Located in the Atlanta metropolitan area</bullet-point>  
         </requirements>  
         <closing>  
            <notes>Lorem ipsum dolor sit amet, consectetur adipiscing elit.</notes>  
            <contact-email>careers@example.com</contact-email>  
         </closing>  
      </system-data-structure>  
   </system-page>

Folder


                <system-folder id="ef85ff080a00016b00659a6696c43ceb">  
      <name>folder</name>  
      <is-published>true</is-published>  
      <title>CHANGE ME</title>  
      <summary>CHANGE ME</summary>  
      <display-name>CHANGE ME</display-name>  
      <path>/index-block-example/folder</path>  
      <created-by>admin</created-by>  
      <created-on>1245264084723</created-on>  
      <last-modified-by>admin</last-modified-by>  
      <last-modified>1245264084723</last-modified>  
      <system-page id="18a659150a00016b01958816fa2e34a7">  
         <name>page</name>  
         <is-published>true</is-published>  
         <title>CHANGE ME</title>  
         <summary>CHANGE ME</summary>  
         <author>Author Name</author>  
         <teaser>Teaser</teaser>  
         <keywords>Comma, Separated, Keywords</keywords>  
         <description>Description</description>  
         <display-name>CHANGE ME</display-name>  
         <path>/index-block-example/folder/page</path>  
         <created-by>admin</created-by>  
         <created-on>1245954070774</created-on>  
         <last-modified-by>admin</last-modified-by>  
         <last-modified>1245954070774</last-modified>  
         <page-xhtml>  
            <p>Lorem ipsum dolor sit amet, consectetur adipiscing elit.</p>  
            <p>Lorem ipsum dolor sit amet, consectetur adipiscing elit.</p>  
            <p>Lorem ipsum dolor sit amet, consectetur adipiscing elit.</p>  
         </page-xhtml>  
      </system-page>  
   </system-folder>

File


                <system-file id="ef8505950a00016b00659a666df25e7d">  
      <name>file.txt</name>  
      <is-published>true</is-published>  
      <path>/index-block-example/file.txt</path>  
      <created-by>admin</created-by>  
      <created-on>1245264020863</created-on>  
      <last-modified-by>admin</last-modified-by>  
      <last-modified>1245954823105</last-modified>  
      <file-size>13</file-size>  
   </system-file>

External Link


                <system-symlink id="ef85a0af0a00016b00659a66a30910aa">  
      <name>external-link</name>  
      <display-name>An External Link</display-name>  
      <path>/index-block-example/external-link</path>  
      <created-by>admin</created-by>  
      <created-on>1245264060581</created-on>  
      <last-modified-by>admin</last-modified-by>  
      <last-modified>1245954788677</last-modified>  
      <link>http://www.hannonhill.com/</link>  
</system-symlink>

Index or Feed Block


                <system-block id="18a828040a00016b01958816156e0c63">  
      <name>index-or-feed-block</name>  
      <path>/index-block-example/index-or-feed-block</path>  
      <created-by>admin</created-by>  
      <created-on>1245954189294</created-on>  
      <last-modified-by>admin</last-modified-by>  
      <last-modified>1245954273235</last-modified>  
   </system-block>

XHTML, XML, or Text Block


                <system-block id="ef826bc40a00016b00659a66c30019d5">  
   <name>xhtml-block</name>  
   <title>CHANGE ME</title>  
   <summary>CHANGE ME</summary>  
   <display-name>CHANGE ME</display-name>  
   <path>/index-block-example/xhtml-block</path>  
   <created-by>admin</created-by>  
   <created-on>1245263850415</created-on>  
   <last-modified-by>admin</last-modified-by>  
   <last-modified>1245263862596</last-modified>  
   <!-- XHTML -->  
   <block-xhtml>  
      <p>Lorem ipsum dolor sit amet, consectetur adipiscing elit.</p>  
      <p>Lorem ipsum dolor sit amet, consectetur adipiscing elit.</p>  
      <p>Lorem ipsum dolor sit amet, consectetur adipiscing elit.</p>  
   </block-xhtml>  
   <!-- XML -->  
   <block-xhtml>  
      <xml>Lorem ipsum dolor sit amet, consectetur adipiscing elit.</xml>  
   </block-xhtml>  
   <!-- Text -->  
   <block-xhtml>Lorem ipsum dolor sit amet, consectetur adipiscing elit.</block-xhtml>  
</system-block>