Cascade Server for Developers Vince Ruppert College of Liberal Arts BoilerWeb 2011

Purpose Help those of you who have not yet started to fully develop web sites in Cascade Server Share experiences and helpful tips with those who are currently developing sites in Cascade

Outline Overview of the system Main building blocks: Templates, Blocks, Formats – Most development time will be spent working with blocks and formats Examples from current sites developed in Cascade

Overview of the system Main areas are similar to Serena Collage – Actions across the top – Site navigation on left – “Current view” area on the right Developers will be using Administration area

When creating a new site The first thing you should do is upload static template-related elements such as images, CSS files, JavaScript, or anything else referenced in your HTML template Do not put CSS/image files inside the _internal folder as this folder is not set to publish

CSS files CSS files should use Cascade’s method of internally linking to images using the [system-asset] tags. Example: #mainbox { background-image:url("[system-asset]/images/body-top.jpg[/system-asset]"); } Make sure you enable link re-writing!

Templates, Blocks, Formats A Template is a file which contains the basic HTML structure of your website along with regions defined in place of dynamic content A Block is either an editable piece of content (XHTML or Data Definition) or an Index Block which dynamically grabs data A Format parses the data in a Block and translates it to HTML

Templates Template files should only contain static HTML that you are certain will never change Anything dynamic should be replaced with a region using the tag: – Must have at least one region named “default”. Each region defines a location in the HTML where a Block will be placed

Template example FISP : Fédération Internationale des Sociétés de Philosophie Fédération Internationale des Sociétés de Philosophie Copyright © 2011 Fédération Internationale des Sociétés de Philosophie

Templates Unlike for CSS files, you do not need to use [system-asset] tags when linking to files in a Template. Template must remain valid (well-formed) XHTML after addition of regions. – Can’t have this:

Templates After the template has been added, the next step is usually adding a configuration set and a content type. Now you can assign the template to a page. If no Data Definition is selected, a WYSIWYG field is used for the Default region Even with a data definition, the default region shouldn’t have a block assigned to it. Eventually you should create a format for the default region

Blocks and Formats All content not in your static HTML Template file will come from Blocks Blocks are assigned to Template regions XHTML Blocks are like “content includes” Index Blocks generate XML, so you should assign a Format to an index block to convert the XML to HTML

Regions, Blocks, and Formats example

Index Blocks Index Blocks will contain a lot more data than you will use Goal is to create index blocks which contain just enough information you need to display without being too broad It’s the job of a Format to parse through all of the XML data and show only information you want to display

Current Page Index Block The most common Index Block is one that simply grabs all the current page’s data for use in a particular region Useful for outputting: – Page headlines – Metadata or using metadata values as logic – Page content outside the Default region

Current Page Index Block

Might produce something like this: index College Resources /resources/index CLA Main site://CLA Main/resources/index banner_size Large Resources in the College (Main Content)

Index Block for folder navigation Either points to an absolute folder (top level) or relative to current page Can restrict how many levels deep the index block will look Whenever possible, try to avoid rendering XML inline

Index Block for folder navigation

Might produce something like this: index /index site://FISP/index What is FISP? Lots of page content olympiad /olympiad site://FISP/olympiad Olympiad Lots of page content

Formats Now that we have the information we want to use in an Index Block, we need to assign a Format to parse the information and display HTML There are two types of Formats you can use in Cascade: XSLT or “Script” (Velocity) Covered in this presentation are Script Formats due to their similarity to a structured programming language

Formats Script Formats in Cascade Server use a combination of 3 other languages: Apache Velocity, JDOM, and XPath A bit confusing because you could use all 3 languages in a single line of code but you will commonly only use a couple commands from each language

Apache Velocity Syntax often starts with a pound (hash) sign: # Commonly used commands are #set, #if, #foreach and #end, along with the variable notation with dollar signs such as $variable Used in conjuncture with JDOM

XPath XPath is what it used to traverse and parse the XML contained in a Block Lots of documentation available online with examples Also use XPath with XSLT Formats

JDOM A much larger specification than Velocity Common methods used with variables: getChild(‘child’), getAttribute(‘attribute’), getParent(), and isEmpty() Common methods used with XPath in Cascade: selectNodes(), selectSingleNode()

Example: Get and display headline index College Resources /resources/index CLA Main site://CLA Main/resources/index banner_size Large Resources (Main Content) #set($sds = $_XPathTool.selectSingleNode($contentRoot, ”/system-index-block/calling-page/system- page/system-data-structure”)) #set($headline = $sds.getChild(‘headline’)) ${headline.value} OR, a bit less code: #set($headline = $_XPathTool.selectSingleNode($contentRoot, ”//system-data-structure/headline”)) $headline.value

Example: Display navigation index /index site://FISP/index What is FISP? Content olympiad /olympiad site://FISP/olympiad Olympiad Content #set($pages = $_XPathTool.selectNodes($contentRoot, ”/system-index-block/system-page”)) #foreach($page in $pages) $page.getChild(‘system- data-structure’).getChild(‘pagetitle’).value #end OR, want the index page to be displayed differently? #set($pages = $_XPathTool.selectNodes($contentRoot,”//system-page”)) #foreach($page in $pages) #if($page.getChild(‘name’).value == ‘index’) $page.getChild(‘system- data-structure’).getChild(‘pagetitle’).value #else $page.getChild(‘system- data-structure’).getChild(‘pagetitle’).value #end

Advanced examples The following creates a breadcrumb trail of index pages, starting at the current page = ‘true’) and then finding system-folder ancestors and their respective index pages. #set($breadcrumbs = $_XPathTool.selectNodes($contentRoot,"//system- = 'index']")) The following grabs pages that should appear on the left navigation for the current page. First we grab all pages which are not index pages in the current folder and all index pages in sub-folders and merge these results together (by use of the pipe symbol which means “or”). Then we also filter out any page where the ‘hide’ metadata option is set to ‘Left sidebar’. #set($siblings = $_XPathTool.selectNodes($starting_folder,"(system- page[name!='index'] | system-folder/system-page[name='index'])[dynamic- metadata[name='hide'][value!='Left sidebar']]"))

Asset Factories Asset Factories make it easy to create new pages with an automatically assigned content type After you have everything working with your configuration set and content type, create a blank page and copy it into the “/_internal/base assets” folder Now you can create an asset factory using this base asset

Migrating from Serena Collage AssetQuery, NavBar now handled by Index Blocks and XPath Select now handled by Velocity’s #if statements Ampersands do not work in non-WYSIWYG fields (use & if you must use one) Ampersands and parentheses do not work in filenames

Resources Script Formats: Formats/ Formats/ – Velocity: 1.5/user-guide.html 1.5/user-guide.html – JDOM: ml ml – XPath: us/library/ms aspxhttp://msdn.microsoft.com/en- us/library/ms aspx Cascade Support Forum: ITaP Cascade Wiki: e+Documentation e+Documentation