Date Looping Using ColdFusion Custom DateLoop Tag
Posted August 3, 2007 at 3:01 PM
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:
Launch code in new window » Download code as text file »
- <!--- 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:
Launch code in new window » Download code as text file »
- <!--- 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:
Launch code in new window » Download code as text file »
- <!--- 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.
Download Code Snippet ZIP File
Post Comment | Ask Ben | Permalink | Other Searches | Print Page
Newer Post
No Reservations Starring Catherine Zeta-Jones And Aaron Eckhart
Older Post
Lenny And Bo, ColdFusion Programmers (Vol. 30)
Reader Comments
Ooooohhh, I like :-> Gotta play with this when I get back to calendars!
Cool. Let me know what you think.
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?
I figured it out. Sorry to have bothered you mate. I was being a complete muppet
No worries. Next time you run into a roadblock, just post your start tag code here.
Awesome tag Ben! This is exactly what I needed. Trying to implement recurring calendar events without it is much harder! Thanks a bunch.
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?
@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".
Thank you. I will play around with it and see what I come up with.
