Applications

The DateTags code relies heavily on the Date::Calc Perl module. Depending on your or your ISP's installation, this may already be present on your system. To check whether Date::Calc is installed, open a shell connection to the host on which you're running Movable Type, and type:

perl -e 'use Date::Calc'

Hit Enter. If this prints nothing, the module is installed. If it prints an error message, you'll need to install Date::Calc. (The MTIfDaysOfMonth and MTBirthstone tags do not require Date::Calc, so you should be able to use those without the module installed.)

Installing Perl modules is beyond the scope of this document, but it's not the hardest thing in the world. However, Date::Calc includes a C library that needs to be compiled, which may prevent you from being able to install it. If this is the case, you can use Date::Pcalc, a Perl-only version of the module that you should be able to install into your Movable Type extlib directory. (You'll have to change all the lines of code in DateTags.pm, DateTags.pl, and MoreDateTags.pl—two lines in each file—that refer to Date::Calc to refer to Date::Pcalc instead.)

The Date::Calc module will be loaded only if one of the tags that requires it is actually called from a template.

Installation

To install the DateTags plugin:

Upload the file DateTags.pm to the extlib directory within your Movable Type directory. If you do not already have an extlib directory, create one before uploading the file.
Upload the file DateTags.pl to the plugins directory within your Movable Type directory. If you do not already have a plugins directory, create one before uploading the file.
If you want to use the MTMoonPhase, MTHolidaysUS, MTAstroSign, or MTBirthstone tags, upload the file MoreDateTags.pl to the plugins directory.

For more information about Movable Type plugins, see the documentation.

Support

Please use the support forums for all support requests, bug reports, feature requests, questions, and comments regarding this plugin.

The "Base Date"

Except for the looping and MTEnglishOrdinal tags, all of these tags operate by comparing a "base date" to something else—a day of the week or month, another date or date range, or a calendar. The base date is determined in the following way:

If you pass a date attribute to a tag, the tag will use that date as the base date. See Passing Dates, below.
If no date attribute is passed, and the tag is called from a location in a template where there's a date context—within an entry, a comment, or a calendar, or on a date-based archive template—that date will be used as the base date.
If no date attribute is passed and no date context is present when the tag is called, the tag will use the current date (the date when you're rebuilding the template) as the base date.

Passing Dates

The base date you pass in the date attribute, and, where applicable, the target or start and end dates, can either be a specific hardcoded date, such as 1/20/2003, or a piece of MT template code that results in a date.

Almost any date format will work, as long as the components of the date are in the correct order.

To pass MT template code, use square brackets instead of angle brackets (and no dollar signs) and single quotes instead of double quotes. The plugin will evaluate any such tags as if they were part of a template, and use the result as the date.

For example, the following code will display the titles of all entries that were not made today:

<MTEntries>
 <MTIfDateNotEqual target="[MTDate format='%m/%d/%Y']">
  <p><$MTEntryTitle$></p>
 </MTIfDateNotEqual>
</MTEntries>

Since the date tag is called from within MTEntries, it uses the date of each entry as the base date; the output of the MTDate tag is used as the target date for the comparison.

Specifying Date Order

By default, all tags that accept date values expect the dates to be in American order (month, day, year). Pass eu="1" to any tag that accepts date attributes to indicate that the date values you're passing are to be in European order (day, month, year).

DISPLAYING ONLY ON CERTAIN DAYS

You may want to use these tags within the MTDateHeader or MTDateFooter container, so that their output will appear only above and/or below a given day's entries.

MTIfDaysOfWeek

This container tag will display its contents if and only if the base date falls on one of the weekdays you specify in the days attribute.

The tag takes the following attributes:

days="D1,D2..." (required)
One or more numbers, separated by commas or spaces, representing the weekdays on which the contents of the tag should be displayed. Each D value is a number from 1 to 7, where 1 is Monday and 7 is Sunday.
To display something only on Saturdays and Sundays, you could use:
```
<MTIfDaysOfWeek days="6,7">
Weekends were made for Michelob!
</MTIfDaysOfWeek>
```
n="N1,N2..." (optional)
One or more numbers, separated by commas or spaces, where each N means "the Nth [day of week] of the month." A value of -1 means "last [day of week] of the month," which might be either the 4th or 5th one. The following code would display the tag's contents on the first and third Monday of each month:
```
<MTIfDaysOfWeek days="1" n="1,3">
I hope that exterminator shows up today.
</MTIfDaysOfWeek>
```

MTIfDaysOfMonth

This container tag will display its contents if and only if the base date falls on one of the days of the month you specify in the days attribute.

The tag takes the following attributes:

days="D1,D2..." (required)
One or more numbers, separated by commas or spaces, representing the days of the month on which the contents of the tag should be displayed. The following code would display on the 7th, 14th, 21st, and 28th of each month:
```
<MTIfDaysOfMonth days="7 14 21 28">
Today is divisible by 7 and that makes it lucky.
</MTIfDaysOfMonth>
```

MTIfMonths

This container tag will display its contents if and only if the base date falls within a month you specify in the months attribute.

The tag takes the following attributes:

months="M1,M2..." (required)
One or more numbers, separated by commas or spaces, representing the months during which the contents of the tag should be displayed. January is 1, December is 12.

You could use this tag to decorate your site with a month-specific or seasonal image or theme:

<MTIfMonths months="1,2,3">
 <img src="winter.gif">
</MTIfMonths>
<MTIfMonths months="4,5,6">
 <img src="spring.gif">
</MTIfMonths>
<MTIfMonths months="7,8,9">
 <img src="summer.gif">
</MTIfMonths>
<MTIfMonths months="10,11,12">
 <img src="fall.gif">
</MTIfMonths>

COMPARING DATES

All of these tags take a required target attribute, which should contain the date to which the base date will be compared. The exception is MTIfDateWithin, which requires start and end dates.

MTDeltaDays

This tag calculates the number of days between the base date and the target date and displays the result.

You may want to use this tag within the MTDateHeader or MTDateFooter container, so that its output will appear only above and/or below a given day's entries.

The tag takes the following attributes:

adjust="N" (optional)
If you pass this attribute, the number of days will be adjusted by N, which can be positive or negative, before it is displayed. Based on the context in which you're using the number, you might want to add or subtract 1 depending on whether the target date itself should be included in the count—for instance:
```
It's <$MTDeltaDays target="1/20/2001"$> days since George W. Bush became President.
<--but:-->
George W. Bush has been President for <$MTDeltaDays target="1/20/2001" adjust="1"$> days.
```
ordinal="1" (optional)
If you pass this attribute, the value displayed will be the ordinal version of the number: 1st, 2nd, 3rd, etc.
```
This is the <$MTDeltaDays target="7-2-1997" ordinal="1" thousands=","$> day of our acquaintance.
```
plural="text" (optional)
If you pass this attribute, MTDeltaDays does not display a number. Instead, it displays nothing if the number of days is 1 or -1, or text if the number is anything else. This allows you to pluralize words properly:
```
<$MTDeltaDays target="12/25/2003"$> shopping day<$MTDeltaDays target="12/25/2003"$> until Christmas!
```
negative="1" (optional)
By default, a negative number of days will be displayed as a positive number (since you usually want to say things like "42 days since..." rather than "-42 days since..."). If you pass this attribute, a negative number of days will be displayed as negative.
thousands="character" (optional)
If you pass this attribute, numbers of 4 or more digits will be formatted with character (probably a comma or period, depending where you are) to delimit thousands (1234 becomes 1,234).

MTIfDateWithin

This container tag will display its contents if and only if the base date falls within (inclusive) the date range you specify.

The tag takes the following attributes:

start="date" (required)
The starting date of the range.
end="date" (required)
The ending date of the range.
start_adjust="N" (optional)
end_adjust="N" (optional)
If you pass one of these attributes, the start or end date will be adjusted by N days, which can be a positive or negative integer.
not="1" (optional)
If you use this attribute, the tag will display its contents on any date that is not within the specified range.

MTIfDateEqual

This container tag will display its contents if and only if the base date is the same as the target date.

MTIfDateNotEqual

This container tag will display its contents if and only if the base date is not the same as the target date.

MTIfDateBefore

This container tag will display its contents if and only if the base date is earlier than the target date.

MTIfDateAfter

This container tag will display its contents if and only if the base date is later than the target date.

MTIfDateBeforeOrEqual

This container tag will display its contents if and only if the base date is earlier than or the same as the target date.

MTIfDateAfterOrEqual

This container tag will display its contents if and only if the base date is later than or the same as the target date.

SHOWING ENTRIES FOR A RANGE OF DATES

This set of tags lets you display the entries that were made during a given range of dates. You can either loop through the range day by day, displaying each day's entries separately (MTDateLoop), or display the whole set of entries for the range (MTDateRange).

MTDateLoop

This tag loops through all the dates from start to end (inclusive), displaying its contents once for each date. For each date, it loads all entries from that date, so you can use MTEntries within this tag to display the entries.

If start is earlier than end, the tag will loop forwards through the date range. If end is earlier than start, the tag will loop backwards through the date range.

The tag takes the following attributes:

start="date" (required)
The starting date of the range.
end="date" (required)
The ending date of the range.
start_adjust="N" (optional)
end_adjust="N" (optional)
If you pass one of these attributes, the start or end date will be adjusted by N days, which can be a positive or negative integer. This is useful if you're using a built value as a start or end date. For example, this code will show the titles of the entries on the last 2 days relative to the current entry:
```
<MTDateLoop start="[MTEntryDate format='%m-%d-%Y']" start_adjust="-2" end="[MTEntryDate format='%m-%d-%Y']">
 <MTEntries>
  <$MTEntryTitle$><br>
 </MTEntries>
</MTDateLoop>
```

MTDateLoopDate

Within MTDateLoop, this tag will display the date for the current loop iteration.

Like MTEntryDate and other date tags, MTDateLoopDate takes optional format and language arguments. See Date Tag Formats in the MT documentation for more information.

MTDateRange

This container tag creates a selection of entries that were created between start and end (inclusive). You must use MTEntries within this tag to display the entries.

Whereas MTDateLoop builds its contents once for each individual date in the range, MTDateRange builds its contents only once, for the entire set of entries in the range. This means that within MTDateRange, MTEntries will work properly with previous/next tags, header/footer tags, the lastn attribute, etc.

The tag takes the following attributes:

start="date" (required)
The starting date of the range.
end="date" (required)
The ending date of the range.
start_adjust="N" (optional)
end_adjust="N" (optional)
If you pass one of these attributes, the start or end date will be adjusted by N days, which can be a positive or negative integer.

MTDateRangeStartDate

MTDateRangeEndDate

Within MTDateRange, these tags will display the starting or ending date of the range.

Like MTEntryDate and other date tags, MTDateRangeStartDate and MTDateRangeEndDate take optional format and language arguments. See Date Tag Formats in the MT documentation for more information.

MTIfEntries

Within MTDateLoop, this container tag will display its contents if and only if there are some entries for a given date. Within MTDateRange, it will display its contents if and only if there are some entries within the specified date range.

MTIfNoEntries

Within MTDateLoop, this container tag will display its contents if and only if there are no entries for a given date. Within MTDateRange, it will display its contents if and only if there are no entries within the specified date range.

DISPLAYING PAST OR FUTURE ENTRIES

These tags allow you to show the specified number of entries whose dates immediately precede or follow the timestamp of the base date.

MTPrevNEntries

MTNextNEntries

MTPrevNEntries selects the n entries immediately prior to the date and time of the base date. MTNextNEntries selects the N entries immediately following the date and time of the base date. If you specify the base date using the date attribute, there is no time specified, so the timestamp used will be 00:00:00 on that date.

These tags select the appropriate entries from the database, but do not actually display them; use a normal MTEntries tag within either one of these tags to display the entries. You can use the usual sort_order and sort_by attributes to control the order in which MTEntries displays the entries.

The following code lists the next 8 entries going forward from the date the template is rebuilt (since the date and time of the rebuild are used for the base date when the tag is called outside of a date context, there's no need to use MTDate to specify the current date):

<MTNextNEntries n="8">
 <MTEntries>
  <$MTEntryTitle$><br>
 </MTEntries>
</MTNextNEntries>

If you're using MT to maintain an event calendar, you could set the above template to rebuild nightly to generate an updated listing of upcoming events.

The tags take the following attributes:

n="N" (required)
The number of entries to select.
modified_on="1" (optional)
By default, the tag selects entries based on their "created on" date. If you pass this attribute, the tag will select entries based on their modification date.
The following code displays the titles of the 5 entries most recently modified:
```
<MTPrevNEntries n="5" modified_on="1">
 <MTEntries sort_by="modified_on" sort_order="descend">
  <$MTEntryTitle$><br>
 </MTEntries>
</MTPrevNEntries>
```

MTIfNEntries

Within MTPrevNEntries or MTNextNEntries, this container tag displays its contents if and only if that tag selected one or more entries.

MTNEntriesCount

Within MTPrevNEntries or MTNextNEntries, displays the number of entries selected by that tag (which may be fewer than the N value passed).

SHOWING CALENDAR INFORMATION

These four tags are contained in the plugin file MoreDateTags.pl. If you don't plan to use any of these tags, you don't need to install this file.

You may want to use these tags within the MTDateHeader or MTDateFooter container, so that their output will appear only above and/or below a given day's entries.

MTMoonPhase

Displays the current phase of the moon for the base date (which includes a time of day, unless you specify the base date by passing the date attribute). Possible values are New, Waxing Crescent, First Quarter, Waxing Gibbous, Full, Waning Gibbous, Last Quarter, and Waning Crescent. Note that the calculation is approximate. It should usually be fine, but in certain cases, depending on the time, it's possible the tag won't show the same full, new, and quarter moon dates as your wall calendar. Sorry.

MTHolidaysUS

Displays the names of any major U.S. holidays that fall on the base date. If there is no holiday on a given date, the tag displays nothing.

The dates of about 30 holidays are defined in the DateTags.pl code. It would be fairly easy to augment or replace these with your own local or national holidays, or annual events of personal significance to you. The comments in the code explain the format for two types of holidays: those that occur on the same date each year, and those that fall on a different date each year (such as Thanksgiving, on the fourth Thursday of November).

The tag takes the following attributes:

glue="gluetext" (optional)
If multiple holidays fall on the same date (which probably won't happen for the predefined set of holidays, but might happen if you define your own), by default they will be separated by a comma and a space. If you use this attribute, multiple holidays will be separated by gluetext instead.

MTAstroSign

Displays the astrological sign for someone who was born on the same day and month as the base date.

MTBirthstone

Displays the birthstone(s) for the month of the base date. You might want to display this only on the 1st of each month:

<MTIfDaysOfMonth days="1">
<p>Birthstone: <$MTBirthstone$>
</MTIfDaysOfMonth>

MISCELLANEOUS

MTEnglishOrdinal

This tag takes the cardinal number you pass in number and displays the corresponding ordinal number, in English—1st, 2nd, 3rd, etc.

The tag takes the following attributes:

number="N" (optional)
The integer to convert to its ordinal form. May be positive or negative.

VERSION HISTORY

2/17/05 - version 2.3

Added MTDateRange and related tags (Neil Lee).
Changed MTDateLoopIfEntries and MTDateLoopIfNoEntries to generalized MTIfEntries and MTIfNoEntries tags.
Added start_adjust and end_adjust attributes to MTIfDateWithin (t0lkien).

8/23/04 - version 2.21

Fixed bug in MTIfDaysOfWeek that was introduced in 2.2 (zro).

7/12/04 - version 2.2

Plugin now registers itself with MT 3 interface.
Added $VERSION variable.
Conditional container tags are now declared as conditional tags, so they should work with MTElse.

3/03/04 - version 2.12

Fixed bug with MTNextNEntries, MTPrevNEntries, and MTIfDateWithin when MT template code was passed for a date (Gregory Maher).

1/22/04 - version 2.11

Fixed bug with parameters passed to subroutine by MTDateLoopIfEntries tag (HMLGC).

1/13/04 - version 2.1

Added MTNextNEntries, MTPrevNEntries, and related tags (Tom Sunshine, Jason Mevius).

11/05/03 - version 2.05

Added MTIfMonths tag.

9/16/03 - version 2.04

Added workaround for bug in MT::ObjectDriver::DBM.pm where entries are sometimes incorrectly loaded when querying by date range (heyharry, Chad Everett)

9/12/03 - version 2.03

All container tags now pass conditions along when building contents, so they'll work outside conditional tags within MTEntries, etc.
MTIfDaysOfMonth now works properly with single-digit days without a leading zero (trialanderror)

7/9/03 - version 2.02

Added start_adjust and end_adjust attributes to MTDateLoop
Moved dt_nwomy subroutine to module so both DateTags.pl and MoreDateTags.pl can access it

6/19/03 - version 2.0

Added comparison tags: MTIfDateEqual, MTIfDateNotEqual, MTIfDateBefore, MTIfDateAfter, MTIfDateBeforeOrEqual, MTIfDateAfterOrEqual.
Added MTDeltaDays tag.
Added tags for looping through dates: MTDateLoop, MTDateLoopIfEntries, MTDateLoopIfNoEntries, MTDateLoopDate.
Added MTEnglishOrdinal tag.
Moved MTDaylightOrStandard to separate plugin.
Moved MTMoonPhase, MTAstroSign, MTHolidaysUS, MTBirthstone tags to MoreDateTags.pl file.
Created DateTags.pm module with code common to DateTags.pl and MoreDateTags.pl.
Removed MTDaysFromNow* tags (superseded by MTDeltaDays and comparison tags).
All tags that expect a base date now accept an optional date attribute that can contain MT template code.
All tags that expect a base date now use the current date if no date attribute or current timestamp is present.
Miscellaneous code improvements.

9/5/02 - version 1.01

Fixed warning in dt_moving_hols() subroutine.

7/18/02 - version 1.0 released