Determine when you expire

n: smd_countdown | v: 0.1 | f: Development / Textpattern plugins

Documentation for the Textpattern plugin smd_countdown by Stef Dawson follows this short message from our sponsor ;-)

Plugin list buttonPlugin download buttonCompressed plugin download button

smd_countdown

Features

  • Countdown to either:
    • article posted, expired, modified time
    • any time given in any article field
    • any arbitrary time given as an English date
  • Supports <txp:else /> so you can take action when the time is reached
  • Display number of years, months, weeks, days, hours, minutes, seconds as either:
    • an absolute number (10 days to go)
    • a date-based number (1 week 3 days to go)

Author / credits

Stef Dawson. A more flexible version of glx_countdown.

Installation / Uninstallation

Download the plugin from either textpattern.org, or the software page, paste the code into the Textpattern Admin -> Plugins pane, install and enable the plugin. Visit the forum thread for more info or to report on the success or otherwise of the plugin.

To uninstall, delete from the Admin -> Plugins page.

Usage

<txp:smd_countdown>

Place this tag in any article or page to count down to a specific date/time. If you wish to use it to count down to a date in the given article you must ensure it’s used in an article context (the plugin will complain if you don’t). Use the to attribute to configure the destination date. Examples:

In a Page:

<txp:smd_countdown to="25 Dec 2009">
  It's Christmas day!
</txp:smd_countdown>

In an article / article Form:

<txp:smd_countdown>
  Posted date has arrived.
<txp:else />
  Event hasn't started yet.
</txp:smd_countdown>

Or:

<txp:smd_countdown to="expires">
  Too late, you missed it :-(
<txp:else />
  There's still time to get to the show...
</txp:smd_countdown>

Or:

<txp:smd_countdown to="?my_date">
  The date in custom field #1 (called my_date) has been reached
</txp:smd_countdown>

<txp:smd_time_info>

If you wish to show visitors how much time they have left before the destination arrives, use this tag to display various time elements. The following attributes configure what you wish to show:

Attributes

  • display : the item(s) you wish to display. Can use one or more (comma-separated) from the following:
    • year (or year_total) : the number of years until the event
    • month : the number of calendar months until the event, maximum 121
    • month_total : the absolute number of months until the event1
    • week : the number of calendar weeks until the event, maximum 522
    • week_total : the absolute number of weeks until the event2
    • day : the number of calendar days until the event, maximum 7
    • day_total : the absolute number of days until the event
    • hour : the number of day-based hours until the event, maximum 24
    • hour_total : the absolute number of hours until the event
    • minute : the number of hour-based minutes until the event, maximum 60
    • minute_total : the absolute number of minutes until the event
    • second : the number of minute-based seconds until the event, maximum 60
    • second_total : the absolute number of seconds until the event
    • destination : the UNIX timestamp of the destination
    • difference : the UNIX timestamp difference between now and the destination (may be negative if the destination has passed)
    • abs_difference : the UNIX timestamp difference between now and the destination irrespective of whether the date has passed or not
  • show_zeros : if you wish to hide leading items that have zero months, weeks, days, etc, set this to 0. Default: 1
  • pad : pad the numerical output with some text. Specify up to two comma-separated values here. The first is the total width in characters of the string you wish to display. The second is the text with which you wish to pad the numbers. Default: 2, 0 (i.e. pad to a width of two characters, using zeros if necessary)
  • label : up to two values with which you can label the given display item(s). If you specify two values, the first is what to use for singular numbers (e.g. 1 hour), the second is the plural (e.g. 3 hours). Note that using the singular, plural form in this attribute does not usually make sense when display is a list of items. Default: unset
  • labeltag : (X)HTML tag, without brackets, to wrap the label with. Default: unset
  • labelafter : set to 1 if you wish the label to be appended to the displayed item(s). Default: 0 (i.e. prepend)
  • labelspacer : text to put before/after the label. Very useful if labelafter="1" and you wish to put a space between the number and the label. Default: unset
  • wraptag : (X)HTML tag, without brackets, to wrap the displayed items with. Default: unset
  • class : CSS class name to apply to the wraptag. Default: smd_time_info
  • break : (X)HTML tag, (without brackets) or other delimiter to wrap / put between each display item. Default: unset

1 Months may get a little distorted over time because a month is assumed to be 30 days

2 Weeks may get a little distorted over time because some years have 53 weeks

Examples

Example 1: Countdown to posted item

The tag defaults to the posted date of the current article.

The party <txp:smd_countdown>
   has arrived. Get your raving trousers on!
<txp:else />
   is <txp:smd_time_info display="day_total" />
     days away: buy a shirt.
</txp:smd_countdown>

The above will always show ‘days away’, even when the last day is reached. To improve this, you can do:

is <txp:smd_time_info display="day_total"
     label="day, days" labelafter="1"
     labelspacer=" " />
   away: buy a shirt.

Example 2: Displaying multiple items

<txp:smd_countdown to="expires">
<txp:else />
   Time remaining:
   <txp:smd_time_info display="hour, minute, second"
     break=":" label="s" labelafter="1" />
</txp:smd_countdown>

Add show_zeros="0" if you wish to remove any leading zero items as the date draws near. Note that it only removes ther most significant ‘zero’ items. For example, if you are just over 1 week away from an event:

<txp:smd_time_info
     display="week, day, hour, minute, second"
     break=":" show_zeros="0" />

Might display: 01:00:05:00:19 (1 week, 0 days, 5 hours, 0 minutes, 19 seconds). But at the same time next day it would show: 06:05:00:19 (6 days, 5 hours, 0 minutes, 19 seconds).

Example 3: Using other fields

A question mark before the name of the field will use the date or timestamp given in that field.

<txp:article_custom time="any" section="events">
   <txp:permlink><txp:title /></txp:permlink>
   <txp:smd_countdown to="?event_date">
      <txp:excerpt />
   <txp:else />
      Event kicks off in:
      <txp:smd_time_info display="day" pad="" show_zeros="0"
        label="day, days" labelafter="1" labelspacer=" " />
      <txp:smd_time_info display="hour, minute, second"
        break=":" label="s" labelafter="1" />
   </txp:smd_countdown>
</txp:article_custom>

The event_date custom field in this case must contain either:

  • an English date such as 25 Aug 2009 12:00:00
  • a UNIX timestamp value

Example 4: Chaining timers

Starting to go a little crazy now…

<txp:article_custom time="any" section="zoo"
     wraptag="ul" break="ul">
   <txp:title />
   <txp:smd_countdown>
      <!-- When the article has been posted, this bit runs -->
      <txp:smd_countdown to="expires">
         <!-- When the article's expiry is reached... -->
         Time's up!
         You missed this animal by
         <txp:smd_time_info display="second_total"
           labelafter="1" label="second, seconds"
           labelspacer=" " />
      <txp:else />
         <!-- While the article is live -->
         <txp:excerpt />
         You have
         <txp:smd_time_info display="hour"
           labelafter="1" labelspacer=" "
           label="hour, hours" show_zeros="0" />
         <txp:smd_time_info display="minute"
           labelafter="1" labelspacer=" "
           label="minute, minutes" show_zeros="0" />
         <txp:smd_time_info display="second"
           labelafter="1" labelspacer=" "
           label="second, seconds" show_zeros="0" />
         left to <txp:permlink>enjoy this animal</txp:permlink>.
      </txp:smd_countdown>
   <txp:else />
      <!-- This portion is displayed before the article's
          posted time is met -->
      arrives in <txp:smd_time_info
        display="second_total" /> seconds.
   </txp:smd_countdown>
</txp:article_custom>

Very useful for competition articles or events. Note that this only works if the publish expired articles setting is switched on in Advanced Prefs.

Example 5: There is no example 5…

… but as food for further study you could use the output from smd_countdown to seed the start of a javascript or flash-based timer which updated a real-time clock counting down to your event.

Source code

If you’d rather dig for buried treasure, you’ll need to step into the view source page.

Legacy software

If, for some inexplicable reason, you need last century's version of a plugin, it can probably be found on the plugin archive page.

Experimental software

If you’re feeling brave, or fancy swimming with piranhas, you can test out some of my beta code. It can be found on the plugin beta page.