Aldrich: Creating custom widgets and layouts

Need to create a custom widget or layout that isn’t available in the templates? Here’s how.

Step 1: create your Data Definition

The only requirement here is the presence of a text field with identifier block-type. The value of this field must be set to name of the widget or layout, and that name must end with either Widget or Layout. I recommend using a single-item radio button type text field so that the value cannot be easily or accidentally changed.

<text identifier="block-type" type="radiobutton" default="myCustomWidget">
  <radio-item value="myCustomWidget"/>
</text>

The templates will use the value of block-type to match this widget with its corresponding Velocity macro (step 4).

→ More: Data Definitions on the Hannon Hill Knowledge Base

Step 2: create your widget / layout block

Start with a basic XHTML block and associate your Data Definition with it. You can find the Data Definition chooser in the block’s Properties tab.

Step 3: add your widget / layout block to a page

Just like you would any other widget or layout. Edit your block and provide some dummy data to test the functionality of the format you’re about to create.

Step 4: create your widget / layout format

Create a new Velocity format.

You can name it whatever you want, so long as it’s meaningful to you. The content of the format must contain a macro named the same as the value of block-type in your Data Definition. The macro must have a single parameter $block.

#macro(myCustomWidget $block)
	## macro code goes here
#end

Use getStructuredDataNode() or getStructuredDataNodes() to access the topmost data nodes in your block data structure and use getChild() or getChildren() to access any descendant nodes from there.

Save the format according to the path set in your site settings. The default path is /_site/formats.

Step 5: test, fix, repeat

The internal Cascade API is woefully undocumented, but there are a couple resource you may find helpful…

→ More: Internal Cascade API on the Cascade CMS Knowledge Base

→ More: Velocity Tools on the Cascade CMS Knowledge Base