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 Parameters

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.

Parameters

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.

Example

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

bind

Allows you to bind form elements to a param variable.

Parameters

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

Example

<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.

Parameters

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

Example

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

button

Creates a button tag.

Parameters

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

Example

<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.

Example

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

charset

Specifies the character encoding for the page.

Parameters

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

Example

<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.

Example

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

content

Set HTML content into a page section.

Parameters

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

Example

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

<c:render key="header" />

content_type

Specifies the Internet media type for the page.

Parameters

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

Example

<c:content_type />

date

Creates a date input field.

Example

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

doctype

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

Parameters

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

Example

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

each

Generic iterator for looping over elements in a specified object.

Parameters

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.

Example

<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.

Example

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

favicon

Creates a link to a favicon.

Parameters

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

Example

<c:favicon />

field

Creates a wrapper for form elements.

Example

<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.

Parameters

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.

Example

<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.

Parameters

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.

Example

<c:flash key="info" />

form

Creates a form tag.

Parameters

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

Example

<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.

Example

<c:head />

hidden

Creates a hidden input field.

Example

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

html

Creates an html tag.

Parameters

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

Example

<c:html />

htmlbody

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

Example

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

image

Creates an image tag.

Parameters

Name	Required	Type	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.

Example

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

include

Facade for the cfinclude tag.

Parameters

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.

Example

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

input

Creates a text input field.

Example

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

number

Creates a number input field.

Parameters

Name	Required	Type	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.

Example

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

pagination

Renders pagination links for a paginator.

Parameters

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

Example

<c:pagination />

partial

Renders a private partial template.

Parameters

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.

Example

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

password

Creates a password input field.

Example

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

phone

Creates a phone input field.

Example

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

radio

Creates radio button input fields.

Parameters

Name	Required	Type	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.

Example

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

range

Creates a range input field.

Parameters

Name	Required	Type	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.

Example

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

render

Renders a section of HTML content.

Parameters

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

Example

<c:render />

rss

Creates a link to an RSS feed.

Parameters

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.

Example

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

script

Creates a script tag.

Parameters

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.

Example

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

search

Creates a search input field.

Parameters

Name	Required	Type	Default	Description
bind	false	string		The key of a param to bind the search field to.
class	false	string		The class for the search field.
disabled	false	boolean	false	If the search field is disabled.
id	false	string	${name}	The id of the search field.
instructions	false	string		The instructions for the search field.
label	false	string	${humanized name}	The label for the search field.
name	true	string		The name of the search field.
onblur	false	string		The onblur event for the search field.
onchange	false	string		The onchange event for the search field.
onclick	false	string		The onclick event for the search field.
ondblclick	false	string		The ondblclick event for the search field.
onfocus	false	string		The onfocus event for the search field.
onkeydown	false	string		The onkeydown event for the search field.
onkeypress	false	string		The onkeypress event for the search field.
onkeyup	false	string		The onkeyup event for the search field.
onsubmit	false	string		The onsubmit event for the search field.
placeholder	false	string		The placeholder text for the search field.
readonly	false	boolean	false	If the search field is read only.
style	false	string		The style for the search field.
title	false	string	${label}	The title for the search field.
value	false	string		The value of the search field.
visible	false	boolean	true	If the search field is visible.
wrapper	false	boolean	true	If the search field should be wrapped in a label.

Example

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

select

Creates a select input field.

Parameters

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.

Example

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

string

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

Parameters

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.

Example

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

style

Creates a style tag.

Parameters

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.

Example

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

submit

Creates a submit tag.

Example

<c:submit name="continue" />

table

Creates a table tag.

Parameters

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.

Example

<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.

Example

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

textarea

Creates a textarea input field.

Parameters

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.

Example

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

time

Creates a time input field.

Example

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

title

Creates a title tag.

Example

<c:title />

tr

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

Parameters

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

Example

<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.

Example

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

url

Creates a url input field.

Example

<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.

Example

<c:version />

viewport

Specifies the desired screen size for the page.

Parameters

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

Example

<c:viewport />

Common Parameters

atom

Parameters

Example

bind

Parameters

Example

body

Parameters

Example

button

Parameters

Example

buttons

Example

charset

Parameters

Example

checkbox

Parameters

Example

content

Parameters

Example

content_type

Parameters

Example

date

Example

doctype

Parameters

Example

each

Parameters

Example

email

Example

favicon

Parameters

Example

field

Example

fieldset

Parameters

Example

flash

Parameters

Example

form

Parameters

Example

head

Example

hidden

Example

html

Parameters

Example

htmlbody

Example

image

Parameters

Example

include

Parameters

Example

input

Example

meta

Example

number

Parameters

Example

pagination

Parameters

Example

partial

Parameters

Example