A major headache that many developers experience when coding their Mach-II views is the fact that they end up writing and re-writing the same (or similar) complex code in order to output simple elements like anchor tags or alternating row colors in a list or table.

Luckily, since version 1.8, Mach-II offers the view tag library to not only help reduce the amount of code required in each view, but make the code easier to read and look cleaner.

Mach-II View Tag Library

Initializing the View Tag Library

The view tag library is essentially a collection of CFML custom tags. It’s extremely easy to provide access within your application, simply use cfimport:

<cfimport prefix="view" taglib="/MachII/customtags/view" />

Once the cfimport tag is invoked, the custom tags may be accessed via the view prefix.

The Anchor (a) Tag

Since release 1.5, Mach-II has provided methods to generate URL strings based on events, modules, and query parameters. Some times these methods can get overly complex, especially when many query parameters are required. To simplify this, the anchor custom tag has been provided for your use.

For example, the “old” way of using BuildUrlToModule could be as follows:

<p>To check out my latest blog entry, <a href="#BuildUrlToModule('blog', 'showEntry', 'entryID=1234')#">click here</a>!</p>

But utilizing the view tag library, this could be re-written as either of the following (they’re both the same):

<p>To check out my latest blog entry, <view:a module="blog" event="showEntry" p="entryID=1234">click here</view:a>!</p>
<p>To check out my latest blog entry, <view:a module="blog" event="showEntry" p="entryID=1234" label="click here" />!</p>

Mach-II URL Management Features
Mach-II SES Routes

The Flip Tag

Another common process that most developers go through when outputting views is the act of candy- or zebra-striping. This is where rows of a table are provided different classes (typically based on a number and the MOD operator) which provide a look of alternating colors.

The flip tag provided by the view library makes this much easier, and also allows the ability to cycle through more than 2 classes easily. Example table with 3 different classes:

<table>
	<tr>
		<th>Name</th>
		<th>Team</th>
	</tr>
	<cfloop query="hockeyQuery">
		<tr class="<view:flip value="#hockeyQuery.CurrentRow#" items="light,medium,dark" />">
			<td>#hockeyQuery.name#</td>
			<td>#hockeyQuery.team#</td>
		</tr>
	</cfloop>
</table>

Would translate to:

<table>
	<tr>
		<th>Name</th>
		<th>Team</th>
	</tr>
	<tr class="light">
		<td>Patrice Bergeron</td>
		<td>Boston Bruins</td>
	</tr>
	<tr class="medium">
		<td>Sidney Crosby</td>
		<td>Pittsburgh Penguins</td>
	</tr>
	<tr class="dark">
		<td>Ryan Getzlaf</td>
		<td>Anaheim Ducks</td>
	</tr>
	<tr class="light">
		<td>Dany Heatley</td>
		<td>San Jose Sharks</td>
	</tr>
</table>

Below is the definition of the flip tag. Please note, this is a self-closing tag. If you do not close this tag with a /> it will cause an exception.

A List Apart: Zebra Tables

The Script Tag

This tag is bundled with the HtmlHelperProperty and allows the inclusion of external JavaScript files and inline JavaScript. External files can be included by providing paths to the src attribute:

<!-- full paths -->
<view:script src="/scripts/jquery.js,/scripts/ui.core.js" />

<!-- shorthand notation -->
<view:script src="jquery,ui.core" />

Both examples above produce the same output:

<script type="text/javascript" src="/scripts/jquery.js?1233233140"></script>
<script type="text/javascript" src="/scripts/ui.core.js?1233063280"></script>

Inline JavaScript can be added by nesting any JavaScript code between start and end view:script tags. This code will be wrapped in HTML script tag and CDATA to XHTML standards.

<view:script>
	Event.observe(window, 'load', startTimer);
	function startTimer() {
		var timer = new Timer(300);
	}
</view:script>

Would output:

<script type="text/javascript">
// <![CDATA[
	Event.observe(window, 'load', startTimer);
	function startTimer() {
		var timer = new Timer(300);
	}
// ]]>
</script>

Mach-II’s HTMLHelperProperty and the addJavascript() and addJavascriptBody() Methods

The Style Tag

This tag is bundled with the HtmlHelperProperty and allows the inclusion of external CSS files and inline styles. External files can be included by providing paths to the src attribute:

<!-- full paths -->
<view:style src="/styles/reset.css,/styles/base.css" />

<!-- shorthand notation -->
<view:style src="reset,base" />

Both examples above produce the same output:

<link type="text/css" href="/styles/reset.css?1233233140" rel="stylesheet" media="screen" />
<link type="text/css" href="/styles/base.css?1233063280" rel="stylesheet" media="screen" />

Inline styles can be added by nesting any CSS code between start and end view:style tags. This code will be wrapped in HTML style tag and CDATA to XHTML standards.

<view:style>.body { background-color: #FF0000; }</view:style>

Would output:

<style type="text/css">
/* <![CDATA[//> */
	.body { background-color: #FF0000; }
/* ]]> */

Mach-II’s HTMLHelperProperty and the addStylesheet() and addStylesheetBody() Methods

The Meta Tag

This tag is bundled with the HtmlHelperProperty and allows addition of HTML meta information into the head section of the document. The following meta information is supported (as of Mach-II 1.8):

• allow
• author
• content-encoding
• content-language
• content-length
• content-type
• copyright
• date
• description
• expires
• generator
• keywords
• last-modified
• location
• progid
• rating
• refresh
• resource-type
• revisit-after
• robots
• set-cookie
• www-authenticate

Additonally, title is supported. While this does not produce a meta tag (it creates a title tag for the page) it is accessed via the meta custom tag.

<view:meta type="title" content="Awesome Page of Awesomeness" />
<view:meta type="keywords" content="awesome,page,awesomeness,cool,great,gnarly,Mach-II" />
<view:meta type="description" content="This is an awesome page because we use Mach-II to generate the meta information!" />
<view:meta type="robots" content="index,follow" />
<view:meta type="refresh" content="3600" />

Would produce:

<title>Awesome Page of Awesomeness</title>
<meta name="keywords" content="awesome,page,awesomeness,cool,great,gnarly,Mach-II" />
<meta name="description" content="This is an awesome page because we use Mach-II to generate the meta information!" />
<meta name="robots" content="index,follow" />
<meta http-equiv="refresh" content="3600" />

Mach-II’s HTMLHelperProperty and the addMeta() Method

The Link Tag

This tag is bundled with the HtmlHelperProperty and allows output of links into the HTML head section (such as RSS feeds or icon links). This tag automatically selects the type, rel, and title attributes, depending on the value passed in the type argument. Below is an example on how to use the link tag:

<view:link type="rss" href="/feeds/rss.cfm" />
<view:link type="atom" href="/feeds/atom.cfm" />
<view:link type="html" href="/someHTML.cfm" />
<view:link type="icon" href="/icons/icon.ico" />

<!--- you can use shortcuts to help build the URL for the href argument --->
<view:link type="canonical" event="main" />

Would generate the output:

<link rel="alternate" type="application/rss+xml" href="/feeds/rss.cfm" />
<link rel="alternate" type="application/atom+xml" href="/feeds/atom.cfm" />
<link rel="alternate" type="text/html" href="/someHTML.cfm" />
<link rel="shortcut icon" type="image/x-icon" href="/icons/icon.ico" />

<link rel="canonical" href="/index.cfm?event=main" />

It should be noted that, as specified by the W3C, all HTML <link> tags must reside within the HTML head section. This view link tag allows the outputType to be specified as inline, which should only be used when outputting directly to the HTML head.

Mach-II’s HTMLHelperProperty and the addLink() Method

The Image (img) Tag

The image tag is bundled with the HtmlHelperProperty and allows outputting of HTML <img> tags with some special added features. Not unlike some of the other tags, such as script and style, the img tag includes the addition of a timestamp, which allows you to set a far off expiry date for this particular file.

Not only does the img tag help in terms of expiry and nice formatting, but it also helps in calculating the actual dimensions of the images (assuming your image is a jpg, png, or gif). Calculated dimensions aids the browser in rendering the images to the screen and increases performance.

The following example generates two img HTML elements, one of which has its dimensions automatically calculated:

<view:img src="big_logo.jpg" width="300" height="50" alt="My Site Logo" />
<view:img src="big_logo.jpg" alt="My Site Logo - No Dimensions Defined" />

And assuming that the big_logo.jpg is actually 300px width by 50px height, the view tag library would create:

<img src="/img/big_logo.jpg" width="300" height="50" alt="My Site Logo" />
<img src="/img/big_logo.jpg" width="300" height="50" alt="My Site Logo - No Dimensions Defined" />

The auto-dimension calculation is provided by the java.awt.* Java package which is not available in all server environments. A common exception that you may encounter if this is not the case would be: java.awt.HeadlessException. For more information on this calculation and how to resolve issues regarding java.awt.*, please check out the HTMLHelperProperty documentation on the Mach-II website.

Mach-II’s HTMLHelperProperty and the addImage() Method
Mach-II’s HTMLHelperProperty Asset Timestamps

The DocType Tag

The doctype tag is bundled with the HtmlHelperProperty and is a convenience method to help with the gnarly DOCTYPE declarations that nobody can remember. XHTML-strict 1.0 is the default, but it also includes various shortcut accessors to output the other doctypes:

You can leverage the doctype tag like this:

<view:doctype />
<view:doctype type="html-4.0-trans" />

Which would generate the output:

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">

And finally the definition of the doctype tag:

Mach-II’s HTMLHelperProperty and the addDocType() Method

The Charset Tag

Like the doctype tag, the charset tag is bundled with the HTMLHelperProperty and is another convenience method used to help output the character set of the document. The charset generated defaults to utf-8 unless otherwise specified.

<view:charset />
<view:charset type="US-ASCII" />

Which converts to:

<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII" />

The definition for the charset tag:

Mach-II’s HTMLHelperProperty and the addCharset() Method

The Asset Tag

The asset tag is bundled with the HTMLHelperProperty and is perhaps the most powerful tag provided by this library. The asset tag generates script and link tags according to a defined set of assets which are defined within the Mach-II configuration file. For information on setting up asset packages, please refer to the Mach-II HTMLHelperProperty documentation.

<view:asset package="lightbox" />

May output something like:

<script type="text/javascript" src="/js/jquery.js?1233233140" />
<script type="text/javascript" src="/js/jquery.lightbox.js?1194373101" />
<link type="text/css" href="/css/jquery.lightbox.css?1194373101" rel="stylesheet" media="screen,projection" />

The definiton for the asset view tag:

Mach-II’s HTMLHelperProperty and the addAssetPackage() Method

Tags: beginner, BuildRouteUrl, BuildUrl, BuildUrlToModule, ColdFusion, css, htmlheaderproperty, HTMLHelperProperty, JavaScript, Mach-II, SES, ViewTagLibrary

This entry was posted on Wednesday, February 10th, 2010 at 9:25 pm and is filed under Mach-II. You can follow any responses to this entry through the RSS 2.0 feed. You can leave a response, or trackback from your own site.