Blog

Gavin Pickin

May 24, 2016

Spread the word


Share your thoughts

In our last post on Extending ContentBox 3 with your own Custom Modules we learned that you could build a custom ColdBox Modile with amazingly, just 2 files. You could paste in your legacy spaghetti code right into your default view, and it would work. Of course, we probably want to dress it up a little more, and add some more functionality, so lets look at the layout first.

Or custom module we were created just had a simple line of code.
<h1>My Custom Module</h1>

If we view the source, you'll see there is more than just the h1 tag we added.

Where is all of that coming from? Layouts

This is another convention. In ColdBox, the default layout for a view is "main", so ColdBox is looking for a main layout for the view. It looks in the module first, in the layouts folder ( which doesn't exist yet ) and there is no /modules_app/customModule/layouts/main.cfm so then it looks in the parent... the main app. Inside of the ContentBox App root, there is a layouts folder, and inside of there, is a Main.cfm. That is found by ColdBox and that is what generates the small amount of layout code wrapping our H1.

<cfoutput>
#html.doctype()#
<html lang ="en" >
<head>
        <meta charset= "utf-8">
        <title>Welcome to ContentBox!</title>
        <meta name= "description" content ="ContentBox Application Template" >
    <meta name="author" content= "Ortus Solutions, Corp">
       <!---Base URL --->
        <base href= "#getSetting( "HTMLBaseURL" )#" />
</head>
<body data -spy ="scroll" >
       #renderView()#
</body>
</html>
</cfoutput>

Creating our own Module layout file

Now, what if we want to use a different layout that the Apps layout? We can use conventions, and create the module layouts folder, and add a main.cfm. Lets do that.
Main.cfm - https://gist.github.com/gpickin/5026d1ce091ec7f708534ab56d3c1f78

<cfoutput>
#html.doctype()#
<html lang ="en" >
<head>
        <meta charset= "utf-8">
        <title>Custom Module Layout</title>
        <meta name= "description" content ="ContentBox Application Template" >
    <meta name="author" content= "Ortus Solutions, Corp">
       <!---Base URL --->
        <base href= "#getSetting( "HTMLBaseURL" )#" />
</head>
<body data -spy ="scroll" >
       
        <h3>My custom Module Layout</h3>
       #renderView()#
</body>
</html>
</cfoutput>

Refresh the page, and you'll see our H3 from the layout showing through.

Overriding the convention for default layout

What if I do not want my layout called main.cfm, or maybe i want to switch my layouts for different seasons... we'll make a new layout called main2.cfm.
First, lets update the moduleConfig default layout, this is where you can override the default layout for the module.

Update the layout settings in the ModuleConfig.cfc from

// Layout Settings
layoutSettings = {
    defaultLayout = ""
};

to

// Layout Settings
layoutSettings = {
    defaultLayout = "main2"
};


Refresh the page, and see what happens. Nothing!

All module settings are only read on initialization... so you need to re-init your app

http://127.0.0.1:51291/customModule?fwreinit=1

Now, we get this error, because we changed the default layout, but we haven't created the file yet.
Lets create main2.cfm and then copy paste main.cfm and then just add something different, so you can see it has changed.

Great, so now I can build my own layouts for my module. This module is being built for my ContentBox Website, so I want the module to match the rest of the website, how do I do that? We'll save that for our next blog post on ContentBox modules.

Hope this helped demystify ColdBox modules and some of the conventions.

Add Your Comment

Recent Entries

Introducing numeric placeholders in BoxLang source!

Introducing numeric placeholders in BoxLang source!

Introducing Numeric Placeholders in BoxLang

We're excited to announce a new addition to our BoxLang parser—a feature that draws inspiration from several other languages but fits naturally within BoxLang. The conversation around which features from other languages m...

Maria Jose Herrera
Maria Jose Herrera
September 18, 2024
BoxLang 1.0.0 Beta 14 Launched

BoxLang 1.0.0 Beta 14 Launched

In this release, we are excited to introduce several new features and enhancements aimed at improving functionality and user experience. These updates include the creation of immutable query types, new server keys to aid on CLI tooling, and methods to identify runtime initiation modes.

Additionally, we've added an event announcement for dump rendering to enable better integration with external listeners. Read on to learn more about these features and how they can benefit your workflow.

Code Strong!

Luis Majano
Luis Majano
September 13, 2024
Are you attending Adobe CFSummit 2024?

Are you attending Adobe CFSummit 2024?

If you are attending the Adobe ColdFusion Summit 2024, this is what you need to know: As always, Ortus Solutions will be sponsoring this years event as Silver Sponsors, we are excited to meet all the new attendees and old friends of the community of Coldfusion developers

Maria Jose Herrera
Maria Jose Herrera
September 10, 2024