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

Installation / Uninstallation

Download the plugin from either GitHub, the software page or textpattern.org, paste the code into the Textpattern Admin->Plugins panel, 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 panel.

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 2014">
  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 12¹.
  • month_total the absolute number of months until the event¹.
  • week the number of calendar weeks until the event, maximum 52².
  • week_total the absolute number of weeks until the event².
  • 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 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 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 HTML tag, (without brackets) or other delimiter to wrap / put between each display item. Default: unset.

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

² 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 the 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 2014 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.

Author / credits

Stef Dawson. A more flexible version of glx_countdown.