Aldrich: Creating custom widgets and layouts

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

Only site admins have the access necessary to take the below steps.

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 template will use the value of block-type to match this widget with its corresponding Velocity macro (step 4).

→ More: Data Definitions on the Cascade CMS 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.

velocity formats folder path data definition field

Step 5: test, fix, repeat

Need help with development? We’ve curated Hannon Hill’s most useful reasources.

→ More: Cascade CMS development resources