Skip to main content
Ben Nadel at CFUNITED 2009 (Lansdowne, VA) with: Dee Sadler
Ben Nadel at CFUNITED 2009 (Lansdowne, VA) with: Dee Sadler ( @DeeSadler )

Date Looping Using ColdFusion Custom DateLoop Tag

By on
Tags:

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.

Want to use code from this post? Check out the license.

Reader Comments

18 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?

2 Comments

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?

15,663 Comments

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

2 Comments

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

15,663 Comments

@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 :)

1 Comments

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

I believe in love. I believe in compassion. I believe in human rights. I believe that we can afford to give more of these gifts to the world around us because it costs us nothing to be decent and kind and understanding. And, I want you to know that when you land on this site, you are accepted for who you are, no matter how you identify, what truths you live, or whatever kind of goofy shit makes you feel alive! Rock on with your bad self!
Ben Nadel