Using Monklets

by Luke Simpson, Justin Bodeutsch | Last edited: 12/11/2019

What is a Monklet?

A Monklet is a macro-like block of code which can be called from a page to return dynamic web-based content. It consists of a set of parameters which determine what content is shown. Monklets are analogous to getContent() calls, but the difference is that they are created and modified in the control panel, rather than hard-coded into a template.

Monklets are managed from the backend under Content > Monklets.

If, for example, you wanted to display a list of Blogs on your site with links to each, you could create the following Monklet:


tag="blog"
display="list"
groupby="category"
show_postlist="<h3><a href='__blogtitlelink__'>__blogposttitle__</a></h3>"

This is analogous to the following getContent:

<? getContent(
"blog",
"display:list",
"groupby:category",
"show_postlist:<h3><a href='__blogtitlelink__'>__blogposttitle__</a></h3>"
?>To call this Monklet on a page, your page content (entered into the Page Editor, not a template) would reference the Monklet name, surrounded by curly brackets, as follows (assuming your Monklet was named "Blog List"):

Select a blog:

Monklet code can also be inserted directly into the Page Editor.

Passing inline parameters to Monklets

When calling a Monklet on a page, you can optionally pass parameters to that Monklet. This allows you to use that same Monklet in different contexts, producing varying output, rather than writing multiple Monklets to do almost the exact same thing.

If you pass a parameter to a Monklet, and that parameter already exists in the Monklet, the value for the pre-existing parameter in the Monklet will be replaced with the value you specify.

Suppose you wanted to display a list of blogs on your site using the example Monklet mentioned earlier, but then suppose you wanted to group by something other than category--for instance, by author. You could override the default groupby setting by attaching a parameter to the Monklet call in your page content, as follows:

In another example, we can use an inline parameter to limit the results of an events monklet to a specific category:

The list of accepted parameters is as follows (* denotes a wildcard):

  • find*
  • groupby*

Naming Monklets

A Monklet cannot function properly if given the following reserved names. Please consider this when naming your Monklets. 

  • The name of a content module ("Galleries", "Pages", "Blog Posts").
  • The name of a currently existing Blog.
  • The name of a currently existing Product Family.

It may be helpful for your development to use the term "Monklet" at the end of each Monklet title in order to avoid confusion with other modular shortcodes, especially since Sections can also be called within WYSIWYG editors using the same syntax. 

Calling Monklets

There are a couple ways to access Monklets:

  • From within any content area in the CMS:
  • From within any template file on the client website: <? getContent("monklet-slug")?>

Global Monklets

Certain modules are automatically driven entirely by monklets. Blogs for example will by default use the global monklet 'All Blogs'. It is recommended that you copy this monklet and create a specific one for your site in case the global monklet is changed at some point. 

You can change at any time which monklet is the default monklet for the site simply by editing the monklet and designating it as the default from the dropdown at the bottom of that page.

You can also select each blog (or product family, etc) to use a different monklet than the default one.