Views

Views

The view layer is the presentation layer of your application, in charge of displaying data from the model and providing the user with forms to input new data. Views are located inside your application's /app/views/ folder and are chosen based on the incoming request. For example, a request to /product/list would display the view located at /app/views/product/list.cfm.

You can change the view associated with an action by adding an @view annotation to to the function.

Layouts

Layouts allow your application to have a consistent look and feel as well as help keep your views clean and focused. Layouts are simply .cfm files located inside your application's /app/layouts/ folder.

By default, ColdMVC will look for a layout with the same name as your controller. For example, if you were make a request to http://myapp.com/index.cfm/product/list, ColdMVC would look for a layout located at /app/layouts/product.cfm. If it cannot find a product.cfm, it look look for the default layout, located at /app/layouts/index.cfm. This is useful if your application has several controllers but only 1 main layout.

If you want to pass data to your layout, create a LayoutController.cfc inside your application's /app/controllers/ folder. Then create a function inside the LayoutController with the same name as the request's controller. In the previous example, you would create function named product. Inside the function, any data put into the params scope will be automatically copied into the variables scope of the layout. If a product function isn't defined inside the LayoutController, ColdMVC will look for an index method and call that instead.

By default, each controller's corresponding layout is the same name as the controller. You can change this by adding an @layout annotation to your controller. If you would like to change the layout for an individual action within a controller, you can do this by adding an @layout annotation to the function.

If your request uses a layout, your layout is in charge of rendering the view's content. This can be done simply by calling #render()# or <c:render /> inside your layout where you want your view's content to be displayed.

View Helpers

View helpers are custom functions that are available to your views and layouts that help keep your presentation layer clean.

You can expose any function on a singleton bean or a helper as a view helper by adding a @viewHelper {name} annotation to the function.

When you first create an application using ColdMVC, you'll already have access to a standard set of view helpers. The most prominent view helper is the linkTo() method that builds URLs for your views.

While your views and layouts still have access to all of your application's helpers, it is recommended to use view helpers rather than accessing the helpers directly. Even though they will generate the exact same HTML, #linkTo({controller="post", action="list"})# reads a lot better than #$.link.to({controller="post", action="list"})#.

Standard View Helpers

• addBreadcrumb
• assetPath
• capitalize
• escape
• flashKeyExists
• getAction
• getContent
• getController
• getFlash
• getFormat
• getLayout
• getModule
• getParam
• getParams
• getUser
• getView
• hasContent
• hasParam
• humanize
• isAllowed
• isDevelopment
• isMobile
• isSecure
• linkTo
• linkToCSS
• linkToImage
• linkToJS
• pluralize
• propercase
• render
• renderCSS
• renderImage
• renderJS
• setAuthor
• setContent
• setDescription
• setKeywords
• setModule
• setParam
• setTitle
• singularize
• singularOrPlural
• truncate
• urlPath

Tags

Writing views and layouts can be tedious work, especially if you want to ensure you're using consistent HTML markup around your form fields. To make views a little less painful, it's best to use custom tags to generate the HTML for you. That way, you don't have to worry about small things like radio button markup and instead can focus on more important things, like your application's business logic.

A new installation of ColdMVC will already have a standard library of custom tags available to use inside your views, such as <c:input />, <c:select />, and <c:textarea />. These files are all located within /coldmvc/tags.

You can create your own custom tags in a ColdMVC application simply by placing a .cfm file inside your application's /app/tags/ folder. For example, if you created a file located at /app/tags/tony.cfm, you would then have access to that custom tag inside your views and layouts by using <c:tony />.

When ColdMVC first loads, it will load any custom tags located within your application's /app/tags/ folder, then any custom tags inside /coldmvc/tags/ folder that haven't been loaded yet. These custom tags will then be available to all of your views and layouts.

Most of the default custom tags inside ColdMVC simply delegate their functionality to a ColdMVC helper component, so extending the default custom tags can be done by extending the helpers. If you would like to completely override a custom tag that ships with ColdMVC, simply create a custom tag with the same file name inside your application's /app/tags/ folder, and ColdMVC will load your custom tag rather than ColdMVC's custom tag.

In a typical ColdFusion application, you need to import your custom tags into each ColdFusion template using the <cfimport /> tag. However, you do not have to do this inside a ColdMVC application. For each view and layout in your application, ColdMVC will automatically generate a corresponding .cfm file inside your application's /.generated/ folder that contains the content of your template along with the <cfimport /> tag. ColdMVC will import your custom tags using a c prefix.

Most of the templates are generated the first time they are requested, with the exception of files beginning with an underscore, which are considered "private" templates by convention and therefore are generated when the application first loads.

Common Properties

Most of the tags that generate form fields, such as <c:input />, <c:select />, and <c:textarea />, all respond to the following common attributes.

Name	Required	Type	Default	Description
bind	false	string		The key of a param to bind the input field to.
class	false	string		The class for the input field.
disabled	false	boolean	false	If the input field is disabled.
id	false	string	${name}	The id of the input field.
instructions	false	string		The instructions for the input field.
label	false	string	${humanized name}	The label for the input field.
name	true	string		The name of the input field.
placeholder	false	string		The placeholder text for the input field.
readonly	false	boolean	false	If the input field is read only.
style	false	string		The style for the input field.
title	false	string	${label}	The title for the input field.
value	false	string		The value of the input field.
visible	false	boolean	true	If the input field is visible.
wrapper	false	boolean	true	If the input field should be wrapped in a label.

In addition, most tags can also accept any events (onclick, onchange, etc...) and any data attributes (data-*) as optional parameters.

atom

Creates a link to an Atom feed.

Name	Required	Type	Default	Description
title	false	string		The title of the Atom feed.
url	false	string	#linkTo("/atom")#	The URL to the Atom feed.

<c:atom url="#linkTo('/feeds/atom')#" />

bind

Allows you to bind form elements to a param variable.

Name	Required	Type	Default	Description
to	true	string		The name of a param to bind to.

<c:bind to="user">
	<c:input name="firstName" />
	<c:input name="lastName" />
</c:bind>

body

Creates a body tag with event-specific classes. Also outputs any content previously wrapped in the <c:htmlbody> tag.

Name	Required	Type	Default	Description
class	false	string		A class for the body tag.

<html>
	<head>
		<title>This is my page</title>
	</head>
	<c:body>
		<c:render />
	</c:body>
</html>	

button

Creates a button tag.

Name	Required	Type	Default	Description
url	true	string		The URL to redirect to when the button is clicked.

<c:button name="cancel" url="#linkTo({action="list"})#" />

buttons

Creates a div with a class of buttons that can be used to wrap around buttons for easy styling.

<c:buttons>
	<c:submit />
	<c:button name="cancel" url="#linkTo({action="list"})#" />
</c:buttons>

charset

Specifies the character encoding for the page.

Name	Required	Type	Default	Description
charset	false	string	utf-8	The character-encoding for the page.

<c:charset />

checkbox

Creates checkbox input fields.

Parameters

Name	Required	Type	Default	Description
align	false	string		The alignment for the checkboxes, either horizontal or vertical. If more than 2 options are present, the default is vertical, otherwise horizontal.
optionKey	false	string	id	The key for the option option key.
optionKeys	false	any		The option keys.
options	false	any		The options for the select.
optionTitle	false	string		The key for the option title.
optionTitles	false	any		The option titles.
optionValue	false	string	name	The key for the option value.
optionValues	false	any		The option values.

<c:checkbox name="sports" value="Baseball,Football" options="Baseball,Basketball,Football,Hockey,Soccer" />

content_type

Specifies the Internet media type for the page.

Name	Required	Type	Default	Description
content	false	string	text/html; charset=utf-8	The content type for the page.

<c:content_type />

content

Set HTML content into a page section.

Name	Required	Type	Default	Description
key	true	string		The key for the section.

<c:content key="header">
	Hello, World
</c:content>

<c:render key="header" />

date

Creates a date input field.

<c:date name="birthDate" value="7/16/1982" />

doctype

Specifies the Document Type Definition (DTD) for the page.

Name	Required	Type	Default	Description
name	false	string	HTML	The name of the the doctype declaration.

<c:doctype name="XHTML 1.0 Strict" />

each

Generic iterator for looping over elements in a specified object.

Name	Required	Type	Default	Description
bind	false	string		The name of a param to bind the loop to.
class	false	string		The variable name to set for the iterating class value ("first", "last").
count	false	string		The variable name to set for total number of items in the collection.
delimiter	false	string	,	The delimiter to use when iterating over a list.
do	false	string	it	The variable name to set for the current item in the collection.
end	false	numeric		The index position to end at when iterating the collection.
in	true	any		The collection to iterate.
index	false	string		The variable name to set for the current index in the collection.
key	false	string		The variable name to set for the current key in the collection.
max	false	numeric		The maximum number of items to iterate in the collection.
start	false	numeric	1	The index position to start at when iterating the collection.

<cfset sports = [ "Baseball", "Basketball", "Football", "Hockey" ] />

<c:each in="#sports#" do="sport" index="i">
	#i#) #sport# <br />
</c:each>

<cfset athletes = {
	king = {
		firstName = "LeBron",
		lastName = "James"
	},
	dwade = {
		firstName = "Dwyane",
		lastName = "Wade"
	},
	air = {
		firstName = "Michael",
		lastName = "Jordan"
	}

} />

<c:each in="#athletes#" do="athlete" index="i" key="key">
	#i#) #athlete.firstName# #athlete.lastName# (#key#)<br />
</c:each>

email

Creates an email input field.

<c:email name="emailAddress" value="joe@example.com" />

favicon

Creates a link to a favicon.

Name	Required	Type	Default	Description
url	false	string	#linkToImage("favicon.ico")#	The URL of the favicon.

<c:favicon />

field

Creates a wrapper for form elements.

<c:field name="address">
	<c:input name="street" value="123 Main St" wrapper="false" /> <br />
	<c:input name="city" value="Burnsville" wrapper="false" />
	<c:input name="state" value="MN" wrapper="false" />
	<c:input name="zip" value="55337" wrapper="false" />
</c:field>

fieldset

Creates a fieldset tag.

Name	Required	Type	Default	Description
label	false	string	${humanized name}	The label for the fieldset. Will be placed inside a <legend> tag.
name	false	string		The name of the fieldset. Only used to generate a possible label.

<c:fieldset label="Personal Information">
	<c:text name="firstName" value="Tony" />
	<c:text name="lastName" value="Nelson" />
</c:fieldset>

flash

Shortcut for displaying values set inside the flash scope.

Name	Required	Type	Default	Description
class	false	string	flash	The class of the wrapping div.
id	false	string		The id of the wrapping div.
key	false	string	message	The key of the param to look for.

<c:flash key="info" />

form

Creates a form tag.

Name	Required	Type	Default	Description
method	false	string	post	The method of the form ("post", "get").
url	false	string		The URL for the form.

<c:form url="#linkTo({controller="user", action="save"})#" bind="user">
	<c:hidden name="id" />
	<c:input name="firstName" />
	<c:input name="lastName" />
</c:form>

head

Renders a head tag with sensible defaults.

<c:head />

hidden

Creates a hidden input field.

<c:hidden name="id" value="3" />

html

Creates an html tag.

Name	Required	Type	Default	Description
lang	false	string	en	Specifies a language code for the content.

<c:html />

htmlbody

Stores wrapped content into the request to be displayed right before the closing <c:body> tag.

<c:htmlbody>
	<script>
		$('#foo').hide();
	</script>
</c:htmlbody>

image

Creates an image tag.

Name	Required	Type	Default	Description
alt	false	string		The alternate text of the image.
name	true	string		The name of the image.
title	false	string		The title of the image.

<c:image name="logo.gif" />

include

Facade for the cfinclude tag.

Name	Required	Type	Default	Description
directory	false	string	views	The directory of the template ("views", "layouts").
template	true	string		The name of the template to include.

<c:include template="post/sidebar.cfm" />

input

Creates a text input field.

<c:input name="firstName" value="Tony" />

meta

Specify a meta tag for the page.

<c:meta author="Tony Nelson" />

number

Creates a number input field.

Name	Required	Type	Default	Description
max	false	numeric		The maximum acceptable value for the field.
min	false	numeric		The minimum acceptable value for the field.
step	false	numeric		Combined with the min and max, defines the acceptable numbers in the range for the field.

<c:number name="amount" value="5" />

pagination

Renders pagination links for a paginator.

Name	Required	Type	Default	Description
paginator	false	coldmvc.pagination.Paginator	params.paginator	A paginator.

<c:pagination />

partial

Renders a private partial template.

Name	Required	Type	Default	Description
directory	false	string	views	The directory of the template ("views", "layouts").
template	true	string		The name of the template to include.

<c:partial template="post/sidebar.cfm" posts="#posts#" />

password

Creates a password input field.

<c:password name="password" value="" />

phone

Creates a phone input field.

<c:phone name="cellPhone" value="555-123-4567" />

radio

Creates radio button input fields.

Name	Required	Type	Default	Description
align	false	string		The alignment for the radio buttons, either horizontal or vertical. If more than 2 options are present, the default is vertical, otherwise horizontal.
optionKey	false	string		The key for the option option key.
optionKeys	false	any		The option keys.
options	false	any		The options for the select.
optionTitle	false	string		The key for the option title.
optionTitles	false	any		The option titles.
optionValue	false	string		The key for the option value.
optionValues	false	any		The option values.

<c:radio name="gender" value="Male" options="Male,Female" />

range

Creates a range input field.

Name	Required	Type	Default	Description
max	false	numeric		The maximum acceptable value for the field.
min	false	numeric		The minimum acceptable value for the field.
step	false	numeric		Combined with the min and max, defines the acceptable numbers in the range for the field.

<c:range name="quantity" value="3" min="1" max="5" step="1" />

render

Renders a section of HTML content.

Name	Required	Type	Default	Description
name	false	string	body	The name of the section to render.

<c:render />

rss

Creates a link to an RSS feed.

Name	Required	Type	Default	Description
title	false	string		The title of the RSS feed.
url	false	string	#linkTo("/rss")#	The URL of the RSS feed.

<c:rss url="#linkTo('/feeds/rss')#" />

script

Creates a script tag.

Name	Required	Type	Default	Description
condition	false	string		A conditional comment to wrap around the script tag.
name	false	string		The name of the script file.

<c:script name="jquery-1.5.1.min.js" />

Creates a search input field.

<c:search name="q" value="foo" />

select

Creates a select input field.

Name	Required	Type	Default	Description
blank	false	boolean	true	If the select should display a blank option.
blankKey	false	string		The key of the blank option.
blankTitle	false	string	${title}	The title of the blank option.
blankValue	false	string	- ${title} -	The text of the blank option.
optionKey	false	string		The key for the option option key.
optionKeys	false	any		The option keys.
options	false	any		The options for the select.
optionTitle	false	string		The key for the option title.
optionTitles	false	any		The option titles.
optionValue	false	string		The key for the option value.
optionValues	false	any		The option values.

<c:select name="color" value="Blue" options="Red,White,Blue" />

string

Displays a string with line feed characters replaced with <br /> tags.

Name	Required	Type	Default	Description
default	false	string		The default value to be displayed for empty strings.
value	false	string		The value of the string to be display.

<c:string value="" default="Unknown" />

style

Creates a style tag.

Name	Required	Type	Default	Description
condition	false	string		A conditional comment to wrap around the style tag.
media	false	string	all	The media type for the stylesheet.
name	false	string		The name of the stylesheet.

<c:style name="main.css" />

submit

Creates a submit tag.

<c:submit name="continue" />

table

Creates a table tag.

Name	Required	Type	Default	Description
cellspacing	false	numeric	0	The cell spacing of the table.
class	false	string	list	The class for the table.
label	false	string		The label to be displayed above the table.
width	false	string	100%	The width of the table.

<cfset names = "Foo,Bar,Baz" />

<c:table>
	<tr>
		<td>Name</td>
	</tr>
	<c:each in="#names#" do="name" index="i">
		<c:tr index="#i#">
			<td>#name#</td>
		</c:tr>
	</c:each>
</c:table>

text

Displays plain text inside a wrapper.

<c:text name="firstName" value="Tony" />

textarea

Creates a textarea input field.

Name	Required	Type	Default	Description
cols	false	numeric		The number of columns for the textarea.
rows	false	numeric		The number of rows for the textarea.

<c:textarea name="message" value="Hello, world" />

time

Creates a time input field.

<c:time name="startTime" value="8:30 am" />

title

Creates a title tag.

<c:title />

tr

Creates a tr tag with an index attribute for easy styling.

Name	Required	Type	Default	Description
index	false	numeric	1	The current index of the row.

<cfset names = "Foo,Bar,Baz" />

<c:table>
	<tr>
		<td>Name</td>
	</tr>
	<c:each in="#names#" do="name" index="i">
		<c:tr index="#i#">
			<td>#name#</td>
		</c:tr>
	</c:each>
</c:table>

upload

Creates an file upload input field.

<c:upload name="photo" instructions="Select a photo to upload to your profile" />

url

Creates a url input field.

<c:url name="website" value="http://www.coldmvc.com/" />

version

Display the current application version and framework version within HTML comments. Useful for quickly checking the versions on a production environment.

<c:version />

viewport

Specifies the desired screen size for the page.

Name	Required	Type	Default	Description
viewport	false	string	width=device-width, initial-scale=1.0	The desired screen size for the page.

<c:viewport />

Assets

ColdMVC provides an easy way to work with your application's public assets, including images, CSS files, and JavaScript files.

Images

Images will be located inside your application's /public/images/ directory.

There are a few ways to render images. The easiest way is to use the image tag:

<c:image name="logo.gif" />

Another method is to use the renderImage view helper:

#renderImage("logo.gif")#

Finally, you can also use the linkToImage view helper to display just the URL to the image.

<img src="#linkToImage("logo.gif")# alt="" />

The previous three examples all output equivalent HTML.

JavaScript

JavaScript files will be located inside your application's /public/js/ directory.

There are a few ways to render links to JavaScript files. The easiest way is to use the script tag:

<c:script name="jquery.js" />

Another method is to use the renderJS view helper:

#renderJS("jquery.js")#

Finally, you can also use the linkToJS view helper to display just the URL to the JavaScript file.

<script src="#linkToJS("jquery.js")#" type="text/javascript"></script>

The previous three examples all output equivalent HTML.

CSS

Cascading stylesheets, or CSS files, will be located inside your application's /public/css/ directory.

There are a few ways to render links to CSS files. The easiest way is to use the style tag:

<c:style name="style.css" />

Another method is to use the renderCSS view helper:

#renderCSS("style.css")#

Finally, you can also use the linkToCSS view helper to display just the URL to the CSS file.

<link href="#linkToCSS("style.css")#" type="text/css" rel="stylesheet" />

The previous three examples all output equivalent HTML.

Debug

When working in development mode, your views will automatically be appended with additional debug information. This includes general request information, such as the controller, action, view, layout, format, and current route.

The debug information also provides helpful insight into otherwise hidden information, such as the HQL queries that were executed, the available tags, helpers, and view helpers, any events that were dispatched during the request, all config settings, and all of the registered beans, models, and templates.