A layout is simply an HTML file that acts as your shell where views can be rendered in and exists in the layouts folder of your application. The layouts can be composed of multiple views and one main view. The main view is the view that gets set in the request collection during a request via event.setView() usually in your handlers or interceptors.

You can have as many layouts as you need in your application and they are super easy to override or assign to different parts of your application. Imagine switching content from a normal HTML layout to a PDF or mobile layout with one line of code. How cool would that be? Well, it's that cool with ColdBox. Another big benefit of layouts, is that you can see the whole picture of the layout, not the usual cfmodule calls where tables are broken, or divs are left open as the module wraps itself around content. The layout is a complete html document and you basically describe where views will be rendered. Much easier to build and simpler to maintain.

Info Another important aspect of layouts is that they can also consume other layouts as well. So you can create nested layouts very easily via the renderLayout() method.

Just like views, layouts can also have helpers on a per-layout, per-layout-folder or per-application basis. If the framework detects the helper, it will inject it into the rendering layout so you can use methods, properties or whatever. All you need to do is follow a set of conventions. Let's say we have a layout in the following location:

/layouts
  /general
    +main.cfm

Then we can create the following templates

• mainHelper.cfm : Helper for the main.cfm layout.

• generalHelper.cfm : Helper for any layout in the general folder.

/layouts
  /general
    +main.cfm
    +mainHelper.cfm
    +generalHelper.cfm

That's it. Just append Helper to the layout or folder name and there you go, the framework will use it as a helper for that layout specifically.

Caution Please note that layout helpers will be inheritenly available to any view rendered inside of the layout.

Application wide helpers

You can also use the coldbox.viewsHelper directive to tell the framework what helper file to use for ALL layouts rendered:

coldbox.viewsHelper = "includes/helpers/viewsHelper.cfm;

If you need the set layout to be rendered from a specific module then use the module argument from the setLayout() or renderLayout() methods:

component name="general"{

    function index(event,rc,prc){

        // call some model for data and put into the request collection
        prc.myQuery = getInstance('MyService').getData();
        // set the view for rendering
        event.setLayout( name="admin", module="contentbox" );

    }

}

You can also wrap layouts within other layouts and get incredible reusability. This is accomplished by using the renderLayout() method in the Renderer. As always, refer to the CFC API for the latest method arguments and capabilities.

renderLayout([any layout], [any module=''], [any view=''], [struct args={}], [any viewModule=''], [boolean prePostExempt='false'])

So if I wanted to wrap my basic layout in a PDF wrapper layout (pdf.cfm) I could do the following:

<cfdocument pagetype="letter" format="pdf">

    <!---  Header --->
    <cfdocumentitem type="header">
    <cfoutput>
    <div>
    #dateformat(now(),"MMM DD, YYYY")# at #timeFormat(now(),"full")#
    </div>
    </cfoutput>
    </cfdocumentitem>

    <!---  Footer --->
    <cfdocumentitem type="footer">
    <cfoutput>
    <div>
    Page #cfdocument.currentpagenumber# of #cfdocument.totalpagecount#
    </div>
    </cfoutput>
    </cfdocumentitem>

    <!---  Main Content via nested layout --->
    <cfoutput>
    #renderLayout(layout="basic")#
    </cfoutput>

</cfdocument>

That's it! The renderLayout() method is extremely power as it can allow you to not only nest layouts but actually render a-la-carte layout/view combinations also.

Ok, now that we have started to get funky, let's keep going. How can I change the layout on the fly for a specific view? Very easily, using yet another new method from the event object, called setLayout() or the layout argument to the setView() method.

event.setLayout( name );
event.setView( view="", layout=name );

This is great, so we can change the way views are rendered on the fly programmatically. We can switch the content to a PDF in an instant. So let's do that

function home(event,rc,prc){

    if( event.valueExists('print') ){
        event.setLayout('layout.PDF');
    }

    // logic here

    // set view
    event.setView('general/home');

}

Default Layout

The default layout in a ColdBox application is layouts/main.cfm by convention. You can change this by using the layoutSettings in your Coldbox.cfc.

//Layout Settings
layoutSettings = {
    defaultLayout = "basic.cfm"
}

Default View

There is no default view in ColdBox, but you can configure one by using the same layoutSettings configuration directive and the defaultView directive:

//Layout Settings
layoutSettings = {
    defaultLayout = "basic.cfm",
    defaultView   = "noview.cfm"
}

This means that if no view is set in the request context, ColdBox will fallback to this view for rendering.

All rendered layouts have associated events that are announced whenever the layout is rendered via ColdBox Interceptors. These are great ways for you to be able to intercept when layouts are rendered and transform them, append to them, or even remove content from them in a completely decoupled approach. The way to listen for events in ColdBox is to write Interceptors, which are essential simple CFC's that by convention have a method that is the same name as the event they would like to listen to. Each event has the capability to receive a structure of information wich you can alter, append or remove from. Once you write these Interceptors you can either register them in your Configuration File or programmatically.

Caution You can disable the layout events on a per-rendering basis by passing the prePostExempt argument as true when calling renderLayout() methods.