You are viewing documentation for v1.0.x. Change

Date, Media, and Text Helpers

Wheels includes a plethora of view helpers to help you transform data into a format more easily consumed by your applications' users.

Wheels's included view helper functions can help you out in those tricky little tasks that need to be performed in the front-end of your web applications. Although they are called miscellaneous, they are in fact categorized into 3 categories:

  • Date Helpers
  • Media Helpers
  • Text Helpers

We also have separate chapters about Wheels form helpers in Form Helpers and Showing Errors and creating your own helpers in Creating Your Own View Helpers.

Date Helpers

Wheels does a good job at simplifying the not so fun task of date and time transformations.

Let's say that you have a comment section in your application, which shows the title, comment, and date/time of its publication. In the old days, your code would have looked something like this:

<cfoutput query="comments">
<div class="comment">
<h2>#comments.title#</h2>
<p class="timestamp">
#DateFormat(comments.createdAt, "mmmm d, yyyy")#
#LCase(TimeFormat(comments.createdAt, "h:mm tt"))#</p>
<p>#comments.comment#</p>
</div>
</cfoutput>

That works, but it's pretty tedious. And if you think about it, the date will be formatted in a way that is not that meaningful to the end user.

Instead of "April 27, 2009 10:10 pm," it may be more helpful to display "a few minutes ago" or "2 hours ago." This can be accomplished with a Wheels date helper called timeAgoInWords().

<cfoutput query="comments">
<div class="comment">
<h2>#comments.title#</h2>
<p class="timestamp">(#timeAgoInWords(comments.createdAt)#)</p>
<p>#comments.comment#</p>
</div>
</cfoutput>

With that minimal change, you have a prettier presentation for your end users. And most important of all, it didn't require you to do anything fancy in your code.

Media Helpers

Working with media is also a walk in the park with Wheels. Let's jump into a few quick examples.

Style Sheets

First, to include CSS files in your layout, you can use the styleSheetLinkTag() function:

<!--- layout.cfm --->
<cfoutput>
#styleSheetLinkTag("main")#
</cfoutput>

This will generate the <link> tag for you with everything needed to include the file at stylesheets/main.css.

If you need to include more than one style sheet and change the media type to "print" for another, there are arguments for that as well:

#styleSheetLinkTag(sources="main,blog")#
#styleSheetLinkTag(source="printer", media="print")#

JavaScript Files

Including JavaScript files is just as simple with the javaScriptIncludeTag() helper.

#javaScriptIncludeTag("jquery")#

Displaying Images

Wheels's imageTag() helper also provides some simple, yet powerful functionality:

<cfoutput>
#imageTag("logo.png")#
</cfoutput>

With this simple call, Wheels will generate the <img> tag for images/logo.png and also set the width, height and alt attributes automatically for you (based on image dimensions and the image file name). Wheels will also cache this information for later use in your application.

If you need to override the alt attribute for better accessibility, you can still do that too:

#imageTag(source="logo.png", alt="ColdFusion on Wheels")#

Text Helpers

To illustrate what the text helpers can help you with, let's see a piece of code that includes 2 of the text helpers in a simple search results page.

<!--- Query of search results --->
<cfparam name="searchResults" type="query">
<!--- Search query provided by user --->
<cfparam name="params.q" type="string">

<cfoutput>
<p>
#highlight(text="Your search for #params.q#", phrases=params.q)#
returned #searchResults.RecordCount#
#pluralize(word="result", count=searchResults.RecordCount)#.</p>
</cfoutput>

That code will highlight all occurrences of params.q and will pluralize the word "result" to "results" if the number of records in searchResults is greater than 1. How about them apples? No <cfif> statements, no extra lines, no nothing.

The functions we have shown in this chapter are only the tip of the iceberg when it comes to helper functions. There's plenty more, so don't forget to check out the View Helper Functions API.

^ Top
Table of Contents

Comments

Read and submit questions, clarifications, and corrections about this chapter.

[Add Comment]

  1. Why does the pluralize() helper also output the number of records found? I just want to change the word, not display the number too. Any ideas?

  2. Chris Peters's Gravatar Chris Peters says:

    Hey Michael,

    If you pass returnCount=false to pluralize(), it'll just return the word and not the number of records.

    See the API docs for more info:
    http://cfwheels.org/docs/function/pluralize

  3. Why is Wheels appending a question mark and long string ending with "E" to my image URLs when I use imageTag?

Add Comment