Ben Nadel
On User Experience (UX) Design, JavaScript, ColdFusion, Node.js, Life, and Love.
I am the chief technical officer at InVision App, Inc - a prototyping and collaboration platform for designers, built by designers. I also rock out in JavaScript and ColdFusion 24x7.
Meanwhile on Twitter
Loading latest tweet...
Ben Nadel at the New York ColdFusion User Group (May. 2009) with:

Date Looping Using ColdFusion Custom DateLoop Tag

By Ben Nadel on
Tags: ColdFusion

I have talked at length about date looping in ColdFusion both in terms of calendars as well as plain old indexed loops. Looping works particularly well if you want to do some sort of day-based increment for your loop. This is because in ColdFusion (and many other technologies), a Day can be represented as 1 (or a fraction of 1). Once you get out of a day-based increment, things get a bit more tricky. Incrementing by weeks, week days, years, or any other non-consistent value makes things more complicated.

To try and keep this very easy and simple, I created this really simple ColdFusion custom tag that elegantly handles looping through dates in a highly intuitive way. This ColdFusion custom tag, DateLoop.cfm, basically is a modified version of the CFLoop tag that ColdFusion already uses. In addition to the normal Index, From, To, and Step attributes, DateLoop.cfm also provides a DatePart attribute. This attribute can hold any value that is valid as the "date part" argument for the DateAdd() ColdFusion function.

Here is how it can be used; here, we are going to loop over all days in August:

  • <!--- Loop through all the days in august. --->
  • <cf_dateloop
  • index="dtDay"
  • from="8/1/2007"
  • to="8/31/2007">
  •  
  • #dtDay#<br />
  •  
  • </cf_dateloop>

This gives us the following (abridged) output:

{ts '2007-08-01 00:00:00'}
{ts '2007-08-02 00:00:00'}
....
{ts '2007-08-30 00:00:00'}
{ts '2007-08-31 00:00:00'}

As you can see, we are invoke the ColdFusion custom tag using the "cf_" construct. Of course, we are only adding a day at a time - nothing special. In fact, this is exactly how a CFLoop index loop would work (minus the date formatting). The power of a ColdFusion custom tag like this is that you can now start to use different DatePart values.

In this example, we are going to loop over August, but only include week days:

  • <!--- Loop through all the week days in august. --->
  • <cf_dateloop
  • index="dtDay"
  • from="8/1/2007"
  • to="8/31/2007"
  • datepart="w">
  •  
  • #dtDay#<br />
  •  
  • </cf_dateloop>

Notice that our <cf_dateloop /> tag now has the attribute DatePart set to "w". This gives us the following output:

{ts '2007-08-01 00:00:00'}
{ts '2007-08-02 00:00:00'}
{ts '2007-08-03 00:00:00'}
{ts '2007-08-06 00:00:00'}
{ts '2007-08-07 00:00:00'}
{ts '2007-08-08 00:00:00'}
{ts '2007-08-09 00:00:00'}
{ts '2007-08-10 00:00:00'}
{ts '2007-08-13 00:00:00'}
{ts '2007-08-14 00:00:00'}
{ts '2007-08-15 00:00:00'}
{ts '2007-08-16 00:00:00'}
{ts '2007-08-17 00:00:00'}
{ts '2007-08-20 00:00:00'}
{ts '2007-08-21 00:00:00'}
{ts '2007-08-22 00:00:00'}
{ts '2007-08-23 00:00:00'}
{ts '2007-08-24 00:00:00'}
{ts '2007-08-27 00:00:00'}
{ts '2007-08-28 00:00:00'}
{ts '2007-08-29 00:00:00'}
{ts '2007-08-30 00:00:00'}
{ts '2007-08-31 00:00:00'}

Notice that weekend days (ex. 08/04, 08/05, 08/11) are skipped over.

I think this adds some really intuitive functionality for Date-based looping. Here is the ColdFusion custom tag that makes this possible:

  • <!--- Kill extra output. --->
  • <cfsilent>
  •  
  • <!---
  • Check to see which tag execution mode we are in.
  • We have acitons that can / should only be done in
  • one or the other.
  • --->
  • <cfswitch expression="#THISTAG.ExecutionMode#">
  •  
  • <cfcase value="Start">
  •  
  • <!---
  • In the start mode, we are going to need to
  • param the tag attributes.
  • --->
  •  
  • <!---
  • This is the name of the caller-scoped variable
  • into which we want to store the iteration value.
  • --->
  • <cfparam
  • name="ATTRIBUTES.Index"
  • type="string"
  • />
  •  
  • <!---
  • This is the value at which we will start the
  • date looping.
  • --->
  • <cfparam
  • name="ATTRIBUTES.From"
  • type="numeric"
  • />
  •  
  • <!---
  • This is the value at which we will end the
  • date looping (value is inclusive in loop).
  • --->
  • <cfparam
  • name="ATTRIBUTES.To"
  • type="numeric"
  • />
  •  
  • <!---
  • This is the amount by which we will incrememnt
  • the loop for each iteration. How this actually
  • translates will be dependent on the DatePart.
  • --->
  • <cfparam
  • name="ATTRIBUTES.Step"
  • type="numeric"
  • default="1"
  • />
  •  
  • <!---
  • This is how the step increment value is applied
  • to the iteration. By default, we will add a day
  • for each increment. This value can be anything
  • used in DateAdd():
  •  
  • yyyy: Year
  • q: Quarter
  • m: Month
  • y: Day of year
  • d: Day
  • w: Weekday
  • ww: Week
  • h: Hour
  • n: Minute
  • s: Second
  • l: Millisecond
  • --->
  • <cfparam
  • name="ATTRIBUTES.DatePart"
  • type="string"
  • default="d"
  • />
  •  
  •  
  • <!---
  • Now that we have paramed all of our attributes,
  • we have to validate the data.
  • --->
  • <cfif (NOT Fix( ATTRIBUTES.Step ))>
  •  
  • <!---
  • The step value must be a non-zero number to
  • prevent infinite looping.
  • --->
  • <cfthrow
  • type="DateLoop.InvalidAttributeValue"
  • message="Step must be a non-zero number."
  • detail="The Step value you provide [#UCase( ATTRIBUTES.Step )#] must be non-zero number to prevent infinite looping."
  • />
  •  
  • </cfif>
  •  
  •  
  • <!---
  • ASSERT: If we have made it this far than we have
  • all the required attributes and valid data.
  • --->
  •  
  • <!--- Initialize the loop sequence. --->
  • <cfset THISTAG.Day = ATTRIBUTES.From />
  •  
  • <!--- Store the current value into the caller. --->
  • <cfset "CALLER.#ATTRIBUTES.Index#" = ParseDateTime(
  • DateFormat( THISTAG.Day, "mm/dd/yyyy" ) & " " &
  • TimeFormat( THISTAG.Day, "HH:mm:ss" )
  • ) />
  •  
  •  
  • <!---
  • Before we even start looping, let's check to see
  • if we haven't already met our final condition.
  • --->
  • <cfif (
  • <!--- Incrementing. --->
  • (
  • (ATTRIBUTES.Step GT 0) AND
  • (THISTAG.Day GT ATTRIBUTES.To)
  • ) OR
  •  
  • <!--- Decrementing. --->
  • (
  • (ATTRIBUTES.Step LT 0) AND
  • (THISTAG.Day LT ATTRIBUTES.To)
  • ))>
  •  
  • <!---
  • We have already met the final condition.
  • Exit out before the loop even starts.
  • --->
  • <cfexit method="EXITTAG" />
  •  
  • </cfif>
  •  
  • </cfcase>
  •  
  •  
  • <cfcase value="End">
  •  
  • <!---
  • Increment the index value using the specified
  • increment and date part.
  • --->
  • <cfset THISTAG.Day = DateAdd(
  • ATTRIBUTES.DatePart,
  • ATTRIBUTES.Step,
  • THISTAG.Day
  • ) />
  •  
  •  
  • <!--- Store the current value into the caller. --->
  • <cfset "CALLER.#ATTRIBUTES.Index#" = THISTAG.Day />
  •  
  •  
  • <!---
  • Check to see if we should continue to loop this
  • value. When checking this, it depends on how the
  • From and To values relate to each other.
  • --->
  • <cfif (
  • <!--- Incrementing. --->
  • (
  • (ATTRIBUTES.Step GT 0) AND
  • (THISTAG.Day LTE ATTRIBUTES.To)
  • ) OR
  •  
  • <!--- Decrementing. --->
  • (
  • (ATTRIBUTES.Step LT 0) AND
  • (THISTAG.Day GTE ATTRIBUTES.To)
  • ))>
  •  
  • <!---
  • We are not done looping. Exit out using the
  • LOOP type so that the EndTag will execute
  • at least one more time.
  • --->
  • <cfexit method="LOOP" />
  •  
  • <cfelse>
  •  
  • <!---
  • We are done looping. Exit out of the
  • tag fully.
  • --->
  • <cfexit method="EXITTAG" />
  •  
  • </cfif>
  •  
  • </cfcase>
  •  
  • </cfswitch>
  •  
  • </cfsilent>

The only drawback to the DateLoop.cfm ColdFusion custom tag is that because it is using the ColdFusion function DateAdd(), it is limited by the DateAdd() rules. In particular, the "step" value must be an integer. So, where as with a standard CFLoop you could have incremented by ".5", DateLoop.cfm requires an integer "step" value.




Reader Comments

This custom tag is super Ben, one question though, how do I make the to dates dynamic? It only seems to work if I hard-code the date in the to="" field of the custom tag, if I try and create a variable for today using the dateformat function and then insert that variable into the custom tag it doesn't work. What am I doing wrong?

Reply to this Comment

I figured it out. Sorry to have bothered you mate. I was being a complete muppet

Reply to this Comment

Awesome tag Ben! This is exactly what I needed. Trying to implement recurring calendar events without it is much harder! Thanks a bunch.

Reply to this Comment

This tag is exactly what I was looking for! I have one question though. Is there a way I can use this to somehow get only the weekend days? Days 1, 7?

Reply to this Comment

@Chris,

In the tag logic, you'd have to add just a bit of logic when incrementing the date. You'd probably also have to add either a new type of date increment (for weekend days) or add some sort of dayIndexes attribute which could be a list of day indexes, ex: dayindexes="1,7".

Reply to this Comment

FANTASTIC!

What a useful custom tag.

However...

At my work they do not let us use custom tags, so I've made a component function version of this if anyone wants one.

Cheers, Michael

Reply to this Comment

@Michael,

Thanks my man. Date looping and dates in general in ColdFusion are kind of cool. Glad you're getting some value out of this approach. Wrapping it up in a CFC sounds like a good thing too :)

Reply to this Comment

Man, i'm going to start searching here instead of googling. I always end up here anyway.

Your last name is now a verb.

"I don't know how to do that, i'm gonna have to go and Nadel it."

Reply to this Comment

Post A Comment

You — Get Out Of My Dreams, Get Into My Comments
Live in the Now
Oops!
Comment Etiquette: Please do not post spam. Please keep the comments on-topic. Please do not post unrelated questions or large chunks of code. And, above all, please be nice to each other - we're trying to have a good conversation here.