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

On this page:


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 propertiescustomMetadata, 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'sidentifier 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'sidentifier 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'sidentifier 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 dropdown 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 dropdown value
$___Page.dropdownIdentifier[0]

Important:

Due to the way the Cascade Server 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.

This is document atwe in the Knowledge Base.
Last modified on 2019-07-02 11:05:01.

Contact us

For help or to comment, email the UITS Support Center.