Blog

Gavin Pickin

July 20, 2016

Spread the word


Share your thoughts

Modules are one of the key components of everything ContentBox. Adding a module into ContentBox is fairly simple, we have a few blog posts already outlining some of the different ways you can create them, but we have left out one very important piece so far ( we actually had a few questions about it on the CFML Slack Channel ), how do we theme our custom module output? Theming your custom module, so it uses the same theme/layout as the rest of your ContentBox site is now a reality. This is vital if you are going to be extending your site with your own modules, and you would hate for your module to be tightly coupled to the current theme, making it harder to change themes. This could be difficult, but luckily for you, its simple.

 

Don't let your Custom Module look like this screenshot

 

Step 1 : CBHelper Class

To use a theme, requires a lot of different pieces behind the scenes. Usually in the process of displaying a ContentBox blog post, or page, the UI Module that handles the process, prepares the UI Request, setting up the settings, themes etc. This has been made available to you through the ContentBox CB Helper class. The first step is to get an injection or request the ContentBox helper object via its injection DSL: CBHelper@cb. You most likely will do this in your custom module handlers:

component{

    property name="cbHelper" inject="CBHelper@cb";

}

Step 2 : prepareUIRequest()

The helper sports the prepareUIRequest() method which you will use to tell ColdBox to leverage the ContentBox module theme instead of a traditional ColdBox layout. Here is the method signature:

/**
* Prepare a ContentBox UI request. This sets ups settings, theme, etc. This method is usualy called
* automatically for you on the UI module. However, you can use it a-la-carte if you are building
* ajax or module extensions
* @layout An optional layout to set for you in the request, taken from the chosen theme
*/
CBHelper function prepareUIRequest( string layout );

This method accepts one argument called layout which by default is the pages layout from the chosen theme. If the ContentBox selected theme has more than 1 rendering layout, then you can even chose it here.

function listData( event, rc, prc ){
    // get some data
    prc.data = myservice.getData();
    
    // Tell ColdBox to use the ContentBox theme
    prepareUIRequest();
    
    // set view to render
    event.setView( "genera/data" );
}

The string for the name of the layout allows you to pick and choose the layout inside the theme. Pages is a common one, but you could have specifically designed layouts for different parts of your modules, or prefer the blog layout for example. Here is a link to the documentation on PrepareUIRequest: http://apidocs.ortussolutions.com/contentbox/3.0.0-rc/contentbox/models/system/CBHelper.html#prepareUIRequest()

Step 3 : Build Cool Stuff

We tried hard to make this as simple as possible, so you can drop a module in and have it using the theme in seconds.Try it out and go build cool stuff!

Add Your Comment

Recent Entries

Ortus Monthly Digest: June 2025

Ortus Monthly Digest: June 2025

June was a transformative month at Ortus Solutions as we crossed the halfway point of the year. With major product updates, powerful community engagements, and continued improvements across the BoxLang ecosystem, our mission to modernize development and empower engineers took center stage. Whether you're a longtime member of the Ortus community or just joining us, here's everything we accomplished in June packed with announcements, tools, and opportunities to grow.

Victor Campos
Victor Campos
July 08, 2025
Ortus Solutions Shines at the 10th América Digital Congress Mexico 2025

Ortus Solutions Shines at the 10th América Digital Congress Mexico 2025

Ortus Solutions had the honor of participating in the prestigious 10th América Digital Congress Mexico 2025, one of the most important technology events in Latin America. Invited by INVEST in El Salvador as part of the official national delegation, our team proudly represented El Salvador’s growing tech sector while showcasing our cutting-edge innovations and bold technological vision for the region.

Connecting with Latin America's Di...

Cristobal Escobar
Cristobal Escobar
July 07, 2025
BoxLang TextMate Bundle Has Landed

BoxLang TextMate Bundle Has Landed

We're excited to announce the release of the BoxLang TextMate Bundle — a comprehensive development toolkit that brings world-class IDE support to BoxLang developers using TextMate, VS Code, Sublime Text, and other TextMate-compatible editors. With BoxLang 1.0 now stable and rapidly gaining momentum in the JVM ecosystem, professional tooling has never been more critical. This bundle delivers exactly that, providing everything you need to build modern, dynamic applications with BoxLang's powerful multi-runtime capabilities.

Luis Majano
Luis Majano
July 07, 2025