-
Notifications
You must be signed in to change notification settings - Fork 24
The View Tag Library
- Overview
- Using the View Library
- View Library Tags
This is a working document and is subject to change.
Some features in this M2SFP are under tickets (trac-wiki) #239 "enhancement: New "a" tag for the view taglib (closed: completed)").
The Mach-II view tag library is a comprehensive set of CFML tags that reduce writing mundane or complex code within your views. The view tag library is available starting in Mach-II 1.8+.
Since illustrated examples are the most convincing, let's look through the library with corresponding HTML output.
The view library is basically a collection of CFML custom tags. Utilizing it in Mach-II views is as simple as adding a tag library import directive to the top each view that uses the library:
<cfimport prefix="view" taglib="/MachII/customtags/view" />We indicated that we will use the "view" prefix in all of our tags. More on this later. So, that is it - there is nothing to configure.
Some tags in the view library wrap other content (such as the script tag) and have a starting and closing tag. Other tags (such as the flip tag) must be self-closed (meaning a trailing / must in the tag). Lastly, the a tag either wraps content or can be self-closing depending on if the label attribute is used.
Due to the fact that CFML engines import tag libraries at the time .cfm files are compiled, the Mach-II framework cannot "magically" include the library for you on each page because the <cfimport> tag must be included in the source code for each .cfm file where the library is being used.
The a tag is a quick way to create a HTML <a> tag with built-in functionality to build a URL or route. Ever since buildUrl() was introduced back in Mach-II 1.5, many users have been asking for an easier way of passing in parameters instead of name / value pairs. Tags are more flexible than method calls are when it comes to passing in unknown attributes or arguments.
The a tag in the view tag library can build a URL with link text between an opening and closing tag or by using the label attribute: ****
<cfimport prefix="view" taglib="/MachII/customtags/view" />
<p>
Create a link to
<view:a event="showProduct" p="productId=1268">some product</view:a></p>
<p>
Create a link using a different syntax to
<view:a event="showProduct" p="productId=1268" label="Look ma! No nested link text." />
</p>
<p>
Create a link using a module to
<view:a event="showProduct" module="adminConsole" p="productId=1268" label="some product" /></p>
<p>
Create a link using expressions to
<view:a event="showProduct"
p="productId=${event.product.productId}">grab event data for the product id</view:a>
</p>If you use the label attribute, you must close the tag (this is called a self-closing tag) with /> not just a >. Failing to do so will cause an exception like The 'a' in the 'view' tag library must have an end tag.
The a tag support using URL routes as well with link test between an opening and closing tag or by using the label attribute:
<cfimport prefix="view" taglib="/MachII/customtags/view" />
<p>
Create a link to <view:a route="showProduct" p="productId=1268">some product</view:a>
</p>
<p>
Create a link using a different syntax to
<view:a route="showProduct" p="productId=1268" label="Look ma! No nested link text." />
</p>
<p>
Create a link that has additional query string attributes
<view:a event="showProduct" p="productId=1268" q="sortBy=name"
label="Look ma! No nested link text." />
</p>The a tag supports building links using the current URL just like what the buildCurrentUrl() method offers. This is supported by using the useCurrentUrl attribute:
<cfimport prefix="view" taglib="/MachII/customtags/view" />
<p>Create a link to <view:a useCurrentUrl="true" p:productId="1268" label="Some Product" /></p>| Name | Required | Default | Description |
|---|---|---|---|
| event | required (or route / useCurrentUrl / endpoint) |
n/a | The event name to build the URL with (cannot be used with route or useCurrentUrl or endpoint) |
| module | optional | current module name | The module name to build the URL with (not valid with route or useCurrentUrl) |
| route | required (or event / useCurrentUrl / endpoint) |
n/a | The route name to build the URL with (cannot be used with event or useCurrentUrl or endpoint) |
| endpoint | required (or event / useCurrentUrl / route) |
n/a | The endpoint name to build the URL with (cannot be used with event or useCurrentUrl or route). Starting in Mach-II 1.9+ only. |
| useCurrentUrl | optional | n/a | Indicates to use the current URL as a basis to build the link (cannot be used with event or route) |
| label | optional | n/a | The value between the start and closing <a> tags if using a self-closing tag. Any value provided in this attribute will automatically be HTMLEditFormatted. |
| href | optional | n/a | Used for complete external URLs only. Does not work with event, module, route, useCurrentUrl, p, and q attributes. |
| p | optional | n/a | Name / value pair list or struct of URL parameters to build the URL with. Can contain EL syntax for values. |
| q | optional | n/a | Name / value pair list or struct of query string parameters to append to the end of a route (only valid with route). Can contain EL syntax for values. |
| x | optional | n/a | Name / value pair list or struct of additional non-standard attribute to insert into the rendered tag output |
All standard HTML and event attributes as defined by the W3C for the HTML a tag.
As we stated above, some Mach-II developers would prefer to specify URL parameters when building URLs by defining name / value pairs instead of passing in a list or struct. Now, your problems are solved using attribute namespaces. Using attribute namespaces leaves the door open for future enhancements to the tag and provides an easy way around having namespace conflicts (i.e. two keys with the same name, but indicate two separate data fragments).
For example (using the same example from above), if we want to use name / value pairs to indicate the productId we would namespace the productId key like so:
<p>
<view:a event="showProduct" p:productId="1268" p:displayType="fancy">some product</view:a>
</p>
<p>
I am the same as using
<view:a event="showProduct" p="productId=1268|displayType=fancy">some product</view:a>
</p>
<p>
Which is the same as doing
<a href="#BuildUrl('event', 'productId=1268|displayType=fancy')>some product</a>
</p>
<p>
You can also use expressions to make
<view:a event="showProduct" p:productId="${event.product.productId}">getting at deeply nested data easier</view:a>
</p>We strip off the namespace prefix (p:) from the attribute key name and use that as the URL parameter key name when building the URL. The same process applies to the other namespaces we support in the a tag. Any name / value pairs specified as namespaced attributes will overwrite any key conflicts from the p, q or x attributes.
The value of a namespaced key can use the Mach-II expression language syntax (i.e. ${}) to dynamically bind data at runtime.
Available namespaces:
| Namespace | Description |
|---|---|
| p | Used to prefix name / value pairs used for the URL parameters when building URLs. |
| q | Used to prefix name / value pairs used for query string parameters when building routes (valid only when using the route attribute). |
| x | Uses to prefix name / value pairs for non-standard HTML attributes to be inserted into final output of the a tag. For example, you might use a javascript framework look for a non-standard attribute of a tag in order to perform some functionality on it. |
The flip tag simplifies the process of "candy-striping" or "zebra-lining" rows of table data. Most people only stripe between two colors or classes using MOD, however the flip tag will accommodate alternating between as many of items you want. Since the flip tag needs to alternate between at least two items, if only one item is passed into the tag, the tag will alternate between that one item and a zero-length string.
You must close the tag (this is called a self-closing tag) with /> not just a >. Failing to do so will cause an exception like The 'flip' in the 'view' tag library must have an end tag.
Example Code:
<cfimport prefix="view" taglib="/MachII/customtags/view" />
<table>
<tr>
<th><h3>Name</h3></th>
<th><h3>Species</h3></th>
<th><h3>Gender</h3></th>
</tr>
<cfloop query="variables.fictionalCharacters">
<tr class="<view:flip value="#currentRow#" items="shadeLight,shadeMedium,shadeDark" />">
<td><p>#name#</p></td>
<td><p>#species#</p></td>
<td><p>#gender#</p></td>
</tr>
</cfloop>
</table>Example Code Output:
<table>
<tr>
<th><h3>Name</h3></th>
<th><h3>Species</h3></th>
<th><h3>Gender</h3></th>
</tr>
<tr class="shadeLight">
<td><p>Bella</p></td>
<td><p>Human</p></td>
<td><p>F</p></td>
</tr>
<tr class="shadeMedium">
<td><p>Edward</p></td>
<td><p>Vampire</p></td>
<td><p>M</p></td>
</tr>
<tr class="shadeDark">
<td><p>Jacob</p></td>
<td><p>Werewolf</p></td>
<td><p>M</p></td>
</tr>
<tr class="shadeLight">
<td><p>Rosalie</p></td>
<td><p>Vampire</p></td>
<td><p>F</p></td>
</tr>
</table>| Name | Required | Default | Description |
|---|---|---|---|
| value | true | n/a | A numeric value that indicates the current row number or loop iteration. |
| items | true | n/a | A comma-delimited list or array of items to alternative between. If only one item element is specified, the tag will alternative between the one element and a zero-length string. |
The script tag is part of the view custom tag library, however its functionality is driven by the HtmlHelperProperty that is bundled with the framework. For more information on how to use this tag, read about the script tag in the HtmlHelperProperty documentation.
The style tag is part of the view custom tag library, however its functionality is driven by the HtmlHelperProperty that is bundled with the framework. For more information on how to use this tag, read about the style tag in the HtmlHelperProperty documentation.
The meta tag is part of the view custom tag library, however its functionality is driven by the HtmlHelperProperty that is bundled with the framework. For more information on how to use this tag, read about the meta tag in the HtmlHelperProperty documentation.
The link tag is part of the view custom tag library, however its functionality is driven by the HtmlHelperProperty that is bundled with the framework. For more information on how to use this tag, read about the link tag in the HtmlHelperProperty documentation.
The img tag is part of the view custom tag library, however its functionality is driven by the HtmlHelperProperty that is bundled with the framework. For more information on how to use this tag, read about the img tag in the HtmlHelperProperty documentation.
The doctype tag is part of the view custom tag library, however its functionality is driven by the HtmlHelperProperty that is bundled with the framework. For more information on how to use this tag, read about the doctype tag in the HtmlHelperProperty documentation.
The charset tag is part of the view custom tag library, however its functionality is driven by the HtmlHelperProperty that is bundled with the framework. For more information on how to use this tag, read about the charset tag in the HtmlHelperProperty documentation.
The asset tag is part of the view custom tag library, however its functionality is driven by the HtmlHelperProperty that is bundled with the framework. For more information on how to use this tag, read about the asset tag in the HtmlHelperProperty documentation.