Create a custom section for the IU Web Framework

On this page:

Get started
Custom section overview
Create a custom section
Get help

Get started

The IU Web Framework allows website developers to create custom sections that can be embedded on pages created with IU's Web Content Management System (WCMS).

The following instructions explain how a website's developer can create their own custom sections for use with the IU Web Framework.

Important:

The below assumes you are familiar with creating Data Definitions, Velocity formats, and Asset Factories in Cascade CMS.

To learn more, see Hannon Hill's documentation on creating Data Definitions, creating Velocity formats, and creating Asset Factories.

Custom section overview

Custom sections are intended to allow developers to add special interactive content to their website without altering the IU Web Framework itself or creating site-specific copies of the framework's code.

A custom section is made up of three parts:

A Data Definition containing the path to your custom section's Velocity format, the name of the macro in that format that should be executed to render your custom section, and any fields you want to make available to content managers
A Velocity format defining how your custom section should be rendered
An XHTML/Data Definition block with your custom section's Data Definition attached

Create a custom section

1. Download the custom section boilerplate

The IU Web Framework custom section boilerplate is a collection of starter files intended to help developers create custom sections.

The custom section boilerplate contains:

A starter XML file you can use to create your custom section's Data Definition (step 2)
A starter Velocity format you can use to define how your custom section's content should be displayed on a web page (step 3)
A starter README file you can use to document how your custom section works (step 5)

2. Create your custom section's Data Definition

Using the starter Data Definition XML file included in the custom section boilerplate, create a Data Definition for your custom section. This Data Definition will be attached to an XHTML/Data Definition block that gets embedded into an IU Web Framework page.

Save this Data Definition in a container called "Custom Sections".

Required fields

A custom section's Data Definition requires two text fields:

format: This value of this field's default attribute must be set to the fully-qualified path to your custom section's Velocity format (step 3). The value of the restrict-to-groups attribute should be set to HIDDEN to prevent content creators from seeing or editing this path.
entryPoint: The value of this field's default attribute must be set to the name of the macro in your Velocity format you'd like executed when the custom section is rendered. The value of this field's restrict-to-groups attribute should also be set to HIDDEN.

Both required fields are included in the starter Data Definition XML file.

3. Create your custom section's Velocity format

Using the starter Velocity format file included in the custom section boilerplate, create a Velocity format for your custom section.

This format can contain any Velocity code needed to render your custom section, provided it includes the entry point macro named in your custom section's Data Definition (step 2).

The name of this entry point macro should be the name of your custom section in PascalCase, plus some unit-specific prefix of your own choosing (for example, UXOCustomSectionName).

Note:

Custom section Velocity formats take advantage of a new feature in the IU Web Framework that parses block XML into a Java object. Once parsed into a Java object, you can access Data Definition fields using dot (.) notation instead of .getChild(), .getChildren(), and the $_XPathTool.

Examples are provided in the starter Velocity format file. You can also learn more about the parser.

Save this format to /_internal/velocity/custom-sections.

4. Create an Asset Factory for your custom section

Creating an Asset Factory that allows content managers to easily create the required XHTML/Data Definition block with your custom section's Data Definition already attached.

5. Document your custom section

Using the starter README file included in the custom section boilerplate, write documentation describing how your custom section works.

If a developer needs to do anything beyond the normal process for adding custom sections, explain the steps they need to take.

Provide instructions for content contributors who are creating or editing pages that use this custom section. Be sure to explain each Data Definition field your custom section includes.

You can learn more about writing effective documentation on the User Experience Office website.

6. Add your custom section to a page

Learn more about adding a custom section to an IU Web Framework page.

Get help

If you need help creating a custom section for the IU Web Framework, see Get Help From The Pros.

You can also watch a presentation about custom sections given by Jay Mercer, Developer Specialist.

Finally, you can ask for help from the IU Web Community of Practice.