Need to create a custom widget or layout that isn’t available in the templates? Here’s how.
| Note |
|---|
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.
| Code Block |
|---|
<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.
| Code 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
Also, if you’re looking for a Javadoc reference for the API, you can download it here:
| View file | ||
|---|---|---|
|