layouts-views

<< Back to Dashboard

Layouts & Views Guide

Introduction

ColdBox provides you with a very simple but flexible and powerful layout manager and content renderer. You no longer need to create module tags or convoluted broken up HTML anymore. You can concentrate on the big picture and create as many layouts as your application needs. Then you can programmatically change rendering schemas (or skinning) and also create composite views. In this guide we will explore the different rendering mechanisms that ColdBox offers and also how to utilize them. As you know, event handlers are our controller layer in ColdBox and we will explore how these objects can interact with the user in order to render content, whether HTML, JSON, XML or any type of rendering data.

Response Types

The event handlers will be the objects in question that will be responding to user requests and they have a few choices when it comes down to rendering content back:

• Set a view to be rendered back to the user (with or without a layout)
• Render data in multiple view formats: JSON, XML, WDDX, HTML, TEXT or CUSTOM
• Render nothing
• Do an HTTP redirect to another event (part of our event handler guide via setNextEvent())

Conventions

Let's do a recap of our conventions for layouts and view locations:

+ application
  + layouts
  + views
 

All your layouts will go in the layouts folder and all your views will go in the views folder.

ColdBox Renderer

It is imperative to know who does the rendering in ColdBox and that is the Renderer core plugin that you can see from our diagram above. As you can tell from the diagram, it includes your layouts and/or views into itself in order to render out content. So by this association and inheritance all layouts and views have some variables and methods at their disposal since they get absorbed into the plugin. You can visit the API docs to learn about all the Renderer Plugin methods. All of the following property members exist in all layouts and views rendered by the Renderer:

As you can see, all views and layouts have direct reference to the request collections so it makes it incredibly easy to get and put data into it. Also, remember that the Renderer inherits from the base ColdBox Plugin class which in turn inherits from the FrameworkSuperType class. So all methods are at your disposal if needed.

Rendering Views

Views are HTML/XML 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. Let's see the signature of this magnificent method:

setView([string view], [boolean nolayout='false'], [boolean cache='false'], [string cacheTimeout=''], [string cacheLastAccessTimeout=''], [string cacheSuffix=''], [string layout], [string module])

Handler Code:

component name="general"{

	function index(event,rc,prc){
	
		// call some model for data and put into the request collection
		prc.myQuery = getModel('MyService').getData();
		// set the view for rendering
		event.setView(view="general/index");
	
	}

}

View Location (view="general/index"):

/application
  /views
    /general
      +index.cfm

That's it, we use the setView() method to set the view 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 event 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 will be used, we will cover this later on.

Let's look at the view code:

<cfoutput>
<h1>My Cool Data</h1>
#html.table(data=prc.myQuery)#
</cfoutput>

I am using our cool HTML Helper plugin that is smart enough to render tables, data, HTML 5 elements etc and even bind to ColdFusion ORM entities. All layouts/views have access to the HTML helper.

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. 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. This feature is more for conventions purists than anything else. However, we do recommend as best practice to use explicitly declare the view to be rendered when working with team environments. Below is the change in code to use implicit views, basically remove the setView() method call.

component name="general"{

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

}

Case Sensitivity

The ColdBox rendering engine can also be tweaked to use case-insensitive or sensitive implicit views by creating a setting called: caseSensitiveImplicitViews in your configuration file. The default is to turn all implicit views to lower case, so the value is always false.

settings = {
	caseSensitiveImplicitViews = true
};

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 some extra parameters or event.noLayout():

component name="general"{

	function index(event,rc,prc){
	
		// call some model for data and put into the request collection
		prc.myQuery = getModel('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 = getModel('MyService').getData();
		// set the view for rendering
		event.setView(view="general/index").noLayout();
	
	}

}

That's it folks! You use the noLayout=true argument or the noLayout() method.

Views With Specific Layout

If you need the view to be rendered in a specific layout, then use the layout argument:

component name="general"{

	function index(event,rc,prc){
	
		// call some model for data and put into the request collection
		prc.myQuery = getModel('MyService').getData();
		// set the view for rendering
		event.setView(view="general/index",layout="Ajax");
	
	}

}

The view will now be rendered into the Ajax layout instead of the default one.

Views From A Module

If you need the set 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 = getModel('MyService').getData();
		// set the view for rendering
		event.setView(view="general/index",module="shared-views");
	
	}

}

By using the module argument, you are explicitely telling the ColdBox renderer to look for the view inside of the passed module name.

View Caching

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 by default: 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 = getModel('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.

// get a reference to the template cache
cache = cachebox.getCache('template');
// or
cache = getColdBoxOCM('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');

Handler Return Rendering

Handlers can also return content by simply returning a simple string from the action method. How that string is built is up to you, it can be a simple string, a call from a model CFC, or inline rendering that we will see below.

component name="general"{

	function index(event,rc,prc){
		return "<h1>Hello from my handler today at :#now()#</h1>";
	}

}

That's it, just return the simple content and it will sent to the output buffer. This technique is great for producing viewlets/widgets or self-sustainable events, where you can call and render events from within anywhere in ColdBox via the runEvent() method. Please refer to the viewlets section in this guide.

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.

component name="general"{

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

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

}

Inline Rendering

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

renderView()

Render inline views from the parent application or from specific modules according to arguments:

renderExternalView()

Render inline views from anywhere in the server according to arguments:

renderLayout()

Render nested layouts or view/layout combinations:

Some Examples

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

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

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

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

Let's explore all the things we can do with inline renderings.

Content Variable Views

A content variable is a variable that contains HTML/XML or any kind of visual content that can easily be rendered anywhere. You can easily do this by leveraging inline rendering and placing the content into a variable, usually in an event handler:

function home(event,rc,prc){

	// render some content variables with funky arguments
	prc.sideColumn = renderView(view='tags/sideColumn',cache=true,cacheTimeout=10);

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

So how do I render it?

<div id="content">
  <div id="leftColumn">
  <cfoutput>#prc.sideColumn#</cfoutput>
  </div>

  <div id="mainView">
  <cfoutput>#renderView()#</cfoutput>
  </div>
</div>

Another example, is what if we do not know if the content variable will actually exist? How can we do this? Well, we use the event object for this and its magic getValue() method.

<div id="content">
  <div id="leftColumn">
  <cfoutput>#event.getValue(name='sideColumn',default='',private=true)#</cfoutput>
  </div>

  <div id="mainView">
  <cfoutput>#renderView()#</cfoutput>
  </div>
</div>

So now, if no content variable exists, an empty string will be rendered.

Rendering External Views

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.

renderExternalView(string view, [boolean cache='false'], [string cacheTimeout=''], [string cacheLastAccessTimeout=''], [string cacheSuffix=''], [any args])

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

Rendering With Local Variables

Passing local variables to layouts and views: renderView(args), renderLayout(args) now get the args argument which can be a structure of data that will be specifically passed to views/layouts for rendering ONLY there. 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'})#

Rendering Collections

You have a few arguments in the renderView() method that deal with collection rendering:

• 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

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. 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: #comment.getTitle()# (#_counter# of #_items#</h1>
<p>Author: #comment.getAuthor()#</p>
#comment.getComment()#
<hr/>

You can see tha charge to prepare and render the viewlet.

1. Create the portable event for the viewlet like any other normal event with one exception.
2. The event will return a rendered view or content

Layout Code (Where I place my viewlet call)

<div id="leftbar">
#runEvent(event='viewlets.userinfo',prepostExempt=true)#
</div>

This code just renders out the results of a runEvent() method call. I would suggest you look at the API docs to discover all paramters to the runEvent() method call. The prePostExempt argument makes the execution of the event faster as it skips any preEvent/postEvent interception calls.

Event Code (viewlets.userinfo)

function userinfo(event,rc,prc){

	// place data in prc and prefix it to avoid collisions
	prc.userinfo_qData = userService.getUserInfo();

	// render out content 
	return renderView("viewlets/userinfo");
}

This handler code is where the magic happens. I talk to a service layer and place some data on the private request collection my viewlet will use. I then return the results of a renderView() call that will render out the exact viewlet I want. You can be more creative and do things like:

• render a layout + view combo
• render data
• return your own custom strings
• etc.

Viewlet Code (viewlets/userinfo.cfm)

<cfoutput>
	<div>User Info Panel</div>
	<div>Username: #prc.userinfo_qData.username#</div>
	<div>Last Login: #prc.userinfo_qData.lastLogin#</div>
</cfoutput>

My view is a normal standard view, it doesn't even know it is a viewlet, remember, views are DUMB!

Funky Viewlets

ColdBox also allows you to have Funky Viewlets and yes that is a real technical term. Funky viewlets allows you to pass arguments to the runEvent() method calls so you can simulate normal method calls and pass extra arguments to the events. So let's make our previous viewlet into a funky viewlet:

function userinfo(event,rc,prc,boolean widget=false){

	// place data in prc and prefix it to avoid collisions
	prc.userinfo_qData = userService.getUserInfo();

	// render out content as widget or normal procedures
	if( arguments.widget ){
		return renderView("viewlets/userinfo");
	}
	event.setView('viewelts/userinfo');
}

What have I done? I have added a custom argument to my action signature: bolean widget=false. Then I split the rendering depending on this incoming argument. WOW! So how do I call my funky viewlet?

<div id="leftbar">
#runEvent(event='viewlets.userinfo',prepostExempt=true,eventArguments={widget=true})#
</div>

That easy! Just add another argument called eventArguments and now you can pass extra arguments to your event actions and cook up some funky viewlets!

Tips And Tricks

Some of the methods below will help you when dealing with views and their renderings.

I don't want to render anything

What if I don't want to render anything, just process. Then use the noRender() method, no need to abort or anything. This tells the framework to stop gracefully.

<cfset event.noRender()>

I don't want a coldbox debugging panel attached to this view

<cfset event.showdebugpanel("false")>

Is this a ColdBox proxy request

<cfset event.isProxyRequest()>

Am I in an ses application

<cfset event.isSES()>

Am I in an ajax call

<cfset event.isAjax()>

Render an event as a viewlet

<cfoutput>#runEvent(event="nav:main.leftnav",prepostExempt=true)</cfoutput>

What is the current layout?

<cfset event.getCurrentLayout()>

What is the current view

<cfset event.getCurrentView()>