So what if I want to render a view outside of my application without using the setting explained above? Well, you use the renderExternalView() method.

<cfoutput>#renderExternalView(view='/myViewsMapping/tags/footer')#</cfoutput>

We have now seen how to set views to be rendered from our handlers. However, we can use some cool methods to render views and layouts on-demand. These methods exist in the Renderer and several facade methods exist in the super type so you can call it from any handler, interceptor, view or layout.

1. renderView()

2. renderExternalView()

3. renderLayout()

Check out the latest API Docs for the latest arguments:

<cfoutput>
// render inline
#renderView( 'tags/metadata' )#

// render from a module
#renderView( view="security/user", module="security" )#

// render and cache
#renderView(
    view="tags/longRendering", 
    cache=true, 
    cacheTimeout=5, 
    cacheProvider="couchbase"
)#

// render a view from the handler action
function showData(event,rc,prc){
    // data here
    return renderView( "general/showData" );    
}

// render an email body content in an email template layout
body = renderlayout( layout='email',view='templates/email_generic' );
</cfoutput>

Model Rendering

If you need rendering capabilities in your model layer, we suggest using the following injection DSL:

property name="renderer" inject="provider:coldbox:renderer";

This will inject a provider of a Renderer into your model objects. Remember that renderers are transient objects so you cannot treat them as singletons. The provider is a proxy to the transient object, but you can use it just like the normal object:

function sendEmail(){
    
    // code here.
    var body = renderer.renderView( "templates/email" );

}

You have a few arguments in the renderView() method that deal with collection rendering. Meaning you can pass any array or query and the Renderer will iterate over that collection and render out the view as many times as the records in the colleciton.

• collection : A data collection that can be a query or an array of objects, structs or whatever

• collectionAs : The name of the variable in the variables scope that will hold the collection pivot.

• collectionStartRow : Defaults to 1 or your offset row for the collection rendering

• collectionMaxRows : Defaults to show all rows or you can cap the rendering display

• collectionDelim : An optional delimiter to use to separate the collection renderings. By default it is empty.

Once you call renderView() with a collection, the renderer will render the view once for each member in the collection. The views have access to the collection via arguments.collection or the member currently iterating. The name of the member being iterated as is by convention the same name as the view. So if we do this in any layout or simple view:

#renderView(view='tags/comment',collection=rc.comments)#

Then the tags/comment will be rendered as many times as the collection rc.comments has members on it and by convention the name of the variable is comment the same as the view name.

<h1>Title: #comment.Title# (#_counter# of #_items#</h1>
<p>Author: #comment.Author#</p>
#comment.Comment#
<hr/>

If you don't like that, then use the collectionAs argument:

#renderView(view='tags/comment',collection=rc.comments,collectionAs='MyComment')#

So let's see the collection view now:

<h1>Title: #MyComment.Title# (#_counter# of #_items#</h1>
<p>Author: #MyComment.Author#</p>
#MyComment.Comment#
<hr/>

You can see that I just call methods on the member as if I was looping (which we are for you). But you will also see two little variables here:

• _counter : A variable created for you that tells you in which record we are currently looping on

• _items : A variable created for you that tells you how many records exist in the collection

This will then render that specific dynamic HTML view as many times as their are records in the rc.comments array and concatenate them all for you. In my case, I separate each iteration with a simple but you can get fancy and creative.

#renderView(view="home/news", collection=prc.news, collectionStartRow=11, collectionMaxRows=20)#

Views are HTML content that can be rendered inside of a layout or by themselves. They can be either rendered on demand or by being set by an event handler. Views can also produce any type of content apart from HTML like JSON/XML/WDDX via our view renderer that we will discover also. So get ready for some rendering goodness!

Setting Views For Rendering

Usually, event handlers are the objects in charge of setting views for rendering. However, ANY object that has access to the request context object can do this also. This is done by using the setView() method in the request context object.

component
{

    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.setView( "general/index" );

    }

}

We use the setView() method to set the view views/general/index.cfm to be rendered. Now the cool thing about this, is that we can override the view to be rendered anytime during the flow of the request. So the last process to execute the setView() method is the one that counts. Also notice a few things:

• No .cfm extension is needed.

• You can traverse directories by using / like normal cfinclude notation.

• The view can exist in the conventions directory views or in your configured external locations

• You did not specify a layout for the view, so the application's default layout (main.cfm) will be used.

Let's look at the view code:

<cfoutput>
<h1>My Cool Data</h1>
#html.table( data=prc.myQuery, class="table table-striped table-hover" )#

</cfoutput>

I am using our cool HTML Helper class that is smart enough to render tables, data, HTML 5 elements etc and even bind to ColdFusion ORM entities.

Views With No Layout

So what happens if I DO NOT want the view to be rendered within a layout? Am I doomed? Of course not, just use the same method with the noLayout argument or event.noLayout() method:

component{

    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.setView( view="general/index", noLayout=true );
    }

    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.setView( "general/index" ).noLayout();
    }
}

Views With Layouts

If you need the view to be rendered in a specific layout, then use the layout argument or the setLayout() method:

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.setView( view="general/index", layout="Ajax" );
    }

    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.setView( "general/index" ).setLayout( "Ajax" );
    }

}

Views From Modules

If you need the set a view to be rendered from a specific ColdBox Module then use the module argument alongside any other argument combination:

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.setView( view="general/index", module="shared-views" );

    }

}

Render Nothing

You can also tell the renderer to not render back anything to the user by using the event.noRender() method. Maybe you just took some input and need to gracefully shutdown the request into the infamous white screen of death.

component name="general"{

    function saveData(event,rc,prc){
        // do your work here …..

        // set for no render
        event.noRender();
    }

}

Implicit Views

You can also omit the explicit event.setView() if you want, ColdBox will then look for the view according to the executing event's syntax by convention. So if the incoming event is called general.index and no view is explicitly defined in your handler, ColdBox will look for a view in the general folder called index.cfm. That is why we recommend trying to match event resolution to view resolution even if you use or not implicit views.

component name="general"{

    function index(event,rc,prc){
        // call some model for data and put into the request collection
        prc.myQuery = getInstance('MyService').getData();    
    }

}

Disabling Implicit Views

You can also disable implicit views by using the coldbox.implicitViews configuration setting in your config/ColdBox.cfc. This is useful as implicit lookups are time-consuming.

coldbox.implicitViews = false;

Case Sensitivity

The ColdBox rendering engine can also be tweaked to use case-insensitive or sensitive implicit views by using the coldbox.caseSensitiveImplicitViews directive in your config/ColdBox.cfc. The default is to turn all implicit views to lower case, so the value is always false.

coldbox.caseSensitiveImplicitViews = true;

You can pass localized arguments to the renderView() and renderLayout() methods in order to encapsulate the rendering via the args struct argument. Much like how you make method calls with arguments. Inside of your layouts and views you will receive the same args struct reference as well.

This gives you great DRYness (yes that is a word) when building new and edit forms or views as you can pass distinct arguments to distinguish them and keep structure intact.

Universal Form

<h1>#args.type# User</h1>
<form method="post" action="#args.action#">
...
</form>

New Form

#renderView(view='forms/universal',args={type='new',action='user.create'})#

Edit Form

#renderView(view='forms/universal',args={type='edit',action='user.update'})#

This is a nifty little feature that enables you to create nice helper templates on a per-view, per-folder and per-application basis. If the framework detects the helper, it will inject it into the rendering view 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 view in the following location:

/views
  /general
    +home.cfm

Then we can create the following templates

• homeHelper.cfm : Helper for the home.cfm view.

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

/views
  /general
    +home.cfm
    +homeHelper.cfm
    +generalHelper.cfm

homeHelper.cfm

<cfscript>
// facade to get i18n resource
function $r(){ return getResource(argumentCollection=arguments); }
// cool formatted date function
function today(){ return dateFormat(now(),"full"); }
</cfscript>

That's it. Just append Helper to the view or folder name and there you go, the framework will use it as a helper for that view specifically. What can you put in these helper templates:

• NO BUSINESS CODE

• UI logic functions or properties

• Helper functions or properties

• Dynamic JavaScript or CSS

Hint External views can also use our helper conventions

Application wide helpers

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

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

You can also pass in the caching arguments below and your view will be rendered once and then cached for further renderings. Every ColdBox application has two active cache regions: default and template. All view and event caching renderings go into the template cache.

component name="general"{

    function index(event,rc,prc){

        // call some model for data and put into the request collection
        prc.myQuery = getInstance('MyService').getData();    
        // view with caching parameters
        event.setView(
            view="general/index",
            cache=true,
            cacheTimeout=60,
            cacheLastAccessTimeout=15,
            cacheSuffix=getfwLocale()
        );
    }

}

Purging Views

So now that our views are cached, how do I purge them programmatically? Well, you need to talk to the template cache provider and use the clearing methods:

// get a reference to the template cache
cache = cachebox.getCache( 'template' );
// or via shortcut notation
cache = getCache( "template" );
// or injection
property name="cache" inject="cachebox:template";

Then we can perform several operations on views:

• clearView(string viewSnippet): Used to clear a view from the cache by using a snippet matched according to name + cache suffix.

• clearMultiView(any viewSnippets): Clear using a list or array of view snippets.

• clearAllViews([boolean async=true]) : Can clear ALL cached views in one shot and can be run asynchronously.

cachebox.getCache( 'template' ).clearView('general/index');
cachebox.getCache( 'template' ).clearAllViews(async=true);
cachebox.getCache( 'template' ).clearMultiView('general/index','index','home');

Disable View Caching

To turn off view caching for your entire application, set the viewCaching setting to false in your config/Coldbox.cfc config file.

coldbox = {
// Activate view caching
viewCaching = false
}

All rendered views have associated events that are announced whenever the view is rendered via ColdBox Interceptors. These are great ways for you to be able to intercept when views 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 view events on a per-rendering basis by passing the prePostExempt argument as true when calling renderView() methods.

Sample Interceptor

Here is a sample interceptor that trims any content before it is renderer:

component{

    function postViewRender(event,interceptData){
        interceptData.renderedView = trim( interceptData.renderedView );
    }
}

Of course, I am pretty sure you will be more creative than that!