Use the Velocity page and block parser in the IU Web Framework

On this page:

Overview
Import the parser
Parse page content
Parse block content
Access page and block data
Example use
Get help

Overview

The IU Web Framework allows website developers writing Velocity formats to parse page and block XML into a plain Java object, enabling them to write clearer and more concise code.

The following instructions explain how a website's developer can use the parser when writing Velocity formats for use with the IU Web Framework, including Velocity formats for custom sections.

Important:

The following assumes you are familiar with creating Velocity formats.

To learn more, see Hannon Hill's documentation on creating Velocity formats.

Import the parser

You can import the parser into your Velocity format using the #include directive exactly as it appears below:

#import("site://IU-FRAME-WEBS.common/velocity/1.2.x/Parser")

Parse page content

You can parse a page's XML content with the #___ParsePage macro. Replace $path and $siteName with whichever variables hold the path to your page (for example, /about/index) and the site name (for example, BL-UNIT-NAME.siteName), respectively:

#set($nil = "#___ParsePage($path, $siteName)")

Calling this macro creates a $___Page variable containing your page's parsed XML content (see below).

Parse block content

Likewise, you can parse an XHTML/Data Definition block's content with the #___ParseBlock macro.

#set($nil = "#___ParseBlock($path, $siteName)")

Calling this macro creates a $___Block variable containing your page's parsed XML content (see below).

Access page and block data

Parsing a page or block converts its content into a plain Java object, allowing you to access content using dot (.) notation instead of .getChild(), .getChildren(), or the $_XPathTool.

The parser preserves the overall structure of your page or block XML. However, some fields, such as metadata or datepickers, have their content transformed to make them easier for you to work with.

Node type	Parser behavior	Example access
Built-in metadata	Parsed into a top-level property `metadata` with the following child properties: `displayName` `title` `summary` `description` `author` `keywords` `teaser` `startDate` `endDate` `reviewDate`	`$___Page.metadata.title`
Custom metadata	Parsed into a top-level properties`customMetadata`, with child properties as described in the following rows	See following rows
Custom metadata: text field	Parsed into an object property with a key equal to the field's`identifier` and a value equal to the field's text value	`$___Page.customMetadata.textFieldIdentifier`
Custom metadata: multiselect	Parsed into an object property with a key equal to the field's`identifier` and a value equal to an array of all selected values	`$___Page.customMetadata.multiselectFieldIdentifier`
Custom metadata: checkbox	Parsed into an object property with a key equal to the field's`identifier` and a value equal to the checkbox's label if checked, or `null` if unchecked	`$___Page.customMetadata.checkboxFieldIdentifier`
Custom metadata: radio buttons	Parsed into an object property with a key equal to the field's `identifier` and a value equal to the label of the selected radio button	`$___Page.customMetadata.radioButtonFieldIdentifier`
Custom metadata: dropdown	Parsed into an object property with a key equal to the field's `identifier` and a value equal to the selected drop-down value	`$___Page.customMetadata.dropdownFieldIdentifier`
Group nodes*	Parsed into an object property with a key equal to the field's `identifier`, with child properties made up of parsed child nodes (see below)	`$___Page.groupNodeIdentifier[0]` `$___Page.groupNodeIdentifer[0].childNodeIdentifier[0]`
WYSIWYG nodes*	Parsed into an object property with a key equal to the field's `identifier` and a value equal to the WYSIWYG field's serialized HTML content	`$___Page.wysiwygNodeIdentifier[0]`
Asset nodes*	Parsed into an object property with a key equal to the field's `identifier` and child properties equal to the asset's properties: `path` `metadata` `customMetadata`	`$___Page.assetNodeIdentifier[0].path`
Calendar nodes*	Parsed into an object property with a key equal to the field's `identifier` and the following child properties representing variations of the field's value: `prettyDate.full` `prettyDate.abbr` `stamp` `value`	`$___Page.calendarNodeIdentifier[0].prettyDate`
Datetime nodes*	Parsed into an object property with a key equal to the field's `identifier` and a value equal to the raw timestamp	`$___Page.datetimeNodeIdentifier[0]`
Multiselect nodes*	Parsed into an object property with a key equal to the field's `identifier` and a value equal to an array of all selected values	`$___Page.multiselectIdentifier[0]`
Checkbox nodes*	Parsed into an object property with a key equal to the field's `identifier` and a value equal to the checkbox's label if checked, or `null` if unchecked	`$___Page.checkboxIdentifier[0]`
Radio button nodes*	Parsed into an object property with a key equal to the field's `identifier` and a value equal to the label of the selected radio button	`$___Page.radioButtonIdentifier[0]`
Dropdown nodes*	Parsed into an object property with a key equal to the field's `identifier` and a value equal to the selected drop-down value	`$___Page.dropdownIdentifier[0]`

Important:

Due to the way the Cascade CMS adapter APIs represent pages and blocks, parsed nodes marked with an asterisk (*) must always be referenced with array indexing (such as [0]), even if there is only a single node of its type.

When referencing a collection of nodes in a #foreach statement, you don't need to use array indexing for the collection or for the individual items in the collection (see example below).

Child properties of asset and calendar nodes, such as .path or .prettyDate, never require array indexing.

Example use

If you had an XHTML/Data Definition block with a Data Definition structured like this:

<system-data-structure>
  <group identifier="name">
    <text identifier="first"/>
    <text identifier="last"/>
  </group>
  <text identifier="email"/>
  <text identifier="title" multiple="true"/>
  <text identifier="birthday" type="calendar"/>
  <group identifier="interests">
    <text identifier="interest" multiple="true"/>
  </group>
  <asset identifier="picture" type="file"/>
</system-data-structure>

You could access the field values like this:

#import("site://IU-FRAME-WEBS.common/velocity/1.2.x/Parser")
#set($nil = "#___ParseBlock($path, $siteName)")

#set($email = $___Block.email[0])
#set($firstName = $___Block.name[0].first[0])
#set($birthday = $___Block.birthday[0].prettyDate)
#set($picture = $___Block.picture[0].path)

#foreach($title in $___Block.title)
  $title
#end

#foreach($interest in $___Block.interests[0].interest)
  $interest
#end

Get help

If you need help using the parser, see Get Help From The Pros.

You can also ask for help from the IU Web Community of Practice.