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

Unveiling the Future of CFML Development - 3rd Round of Sessions

Unveiling the Future of CFML Development - 3rd Round of Sessions

Welcome back to our journey into the future of CFML development! As excitement continues to build for Into the Box 2024, we're thrilled to bring you the latest updates on what promises to be a transformative event. Continuing our blog post series, let's delve deeper into the third wave of session releases and discover the key surprises awaiting attendees. Learn More

Maria Jose Herrera
Maria Jose Herrera
March 01, 2024
Elevate Your ColdBox Experience and Skills

Elevate Your ColdBox Experience and Skills

We're thrilled to announce a significant overhaul of our ColdBox training experience to ensure it's nothing short of extraordinary! We've listened closely to your feedback and made significant improvements geared towards transforming you into a ColdBox superhero. Learn What's New!

Maria Jose Herrera
Maria Jose Herrera
February 20, 2024
Ortus Redis Extension v3.3.0 Released!

Ortus Redis Extension v3.3.0 Released!

We are very excited to bring you another release for our Redis Lucee Extension. The most significant feature in this release is the addition of the `` and `redisLock{}` tag, which allows you perform a lock across all instances in a cluster.

Ortus Redis Extension v3.3.0 gives you greater control over concurrent modifications in a distributed environment, utilizing your distributed cache to prevent overlaps!

Jon Clausen
Jon Clausen
February 16, 2024