Countdowns

Countdowns are handled by the jQuery Countdown library.

Our script provides a wrapper to the jQuery Countdown library, allowing countdowns to be configured using HTML and data-attributes.

Countdowns may be configured to use a single element, such as a span to display the entire countdown string, or using the data-detailed="true" option, can be configured to house each time component of the countdown in separate elements for greater design flexibility.

1. Include the library in your page

   • Copy the script tag below and paste in the foot of your page. Add this where you see the other library scripts. This line should be inserted after jquery.js and before theme.js.

     <!-- jQuery Countdown (displays countdown text to a specified date) -->
     <script type="text/javascript" src="assets/js/jquery.countdown.min.js"></script>

     Alternatively you may wish to load this resource from a CDN to potentially improve page load times.

     <!-- jQuery Countdown (displays countdown text to a specified date) -->
     <script type="text/javascript" src="https://unpkg.com/jquery-countdown@~2.2.0"></script>

2. Load the initializer code in index.js

   • Declare the following import statement in js/mrare/index.js. This ensures that the initializer code is included in the theme.js bundle.

     import mrCountdown from './countdown';

   • Ensure the following line appears in the export object:

     export {
     mrCountdown,
     };

Countdowns are initialized by data-attributes on page load.

A simple countdown uses a single inline element (span, h3, h1 etc.) to display the remaining time.

To display a simple countdown, add data-countdown-date to the element. Provide a date in the format YYYY/MM/DD.

<h2 data-countdown-date="2019/08/05"></h2>

Options

Data attribute	Default	Description
data-date-format	%D days %H:%M:%S	Outputs a string from the plugin's strftime() function. Refer to the plugin documentation for formatting rules.
data-days-text	Days	Used for translating the word 'days' in the date format to a language other than English eg. 'Dias' for Spanish. The string provided here is also passed into the default format string to replace days.
data-date-fallback	Timer Done	Text to be shown in the element when the countdown has elapsed.

A detailed countdown uses multiple elements housed in a div and can be arranged in any layout for maximum display flexibility.

Add the attributes data-countdown-date with data-detailed to a div element to create a detailed countdown.

The countdown is constructed using HTML elements within the main div. Each time component of the countdown is represented by an inline element. These can be arranged in columns or any other layout.

A data attribute indicates which part of the countdown to show in each element. The script will replace the text of the inline element with the countdown text once per second.

<div class="col-12" data-countdown-date="2019/08/06" data-detailed>
  <span data-years></span>
  <span data-months></span>
  <span data-weeks></span>
  <span data-days></span>
  <span data-hours></span>
  <span data-minutes></span>
  <span data-seconds></span>
</div>

Any of the elements may be omitted from the countdown if you wish. For example you may not need to display years, months or weeks.

Components of the countdown must be nested inside the data-countdown-date div.

Options

Data attribute	Default Format	Usage
data-years	%Y	Nest inside div[data-countdown-date] to display years
data-months	%m	Nest inside div[data-countdown-date] to display months
data-weeks	%w	Nest inside div[data-countdown-date] to display weeks
data-days	%D	Nest inside div[data-countdown-date] to display days
data-hours	%H	Nest inside div[data-countdown-date] to display hours
data-minutes	%M	Nest inside div[data-countdown-date] to display minutes
data-seconds	%S	Nest inside div[data-countdown-date] to display seconds

Time components are formatted according to the plugin's strftime() function. The string you provide to the formatter determines what is shown in the text of the element.

Add attribute data-format to the element to override the default formatting. This allows you to control whether the count should zero padded (01) or blank padded ( 1).

This example shows how to modify the hours format to be blank padded by adding a data-format attribute to the data-hours element.

<div class="col-12" data-countdown-date="2019/08/06" data-detailed>
  <span data-days></span>
  <span data-hours data-format="%-H"></span>
  <span data-minutes></span>
  <span data-seconds></span>
</div>

See the plugin documentation for the full list of formatting options.

Each component of the countdown may be accompanied by a label which is also customizable for translation and format (see Formatting Labels below).

Add an inline element with attribute data-days-label to display a label for the days component.

Labels must be nested inside the data-countdown-date div.

Options

Data attribute	Default Format	Usage
data-years-label	%!Y:Year,Years;	Nest inside div[data-countdown-date] to display a label for years
data-months-label	%!m:Month,Months;	Nest inside div[data-countdown-date] to display a label for months
data-weeks-label	%!w:Week,Weeks;	Nest inside div[data-countdown-date] to display a label for weeks
data-days-label	%!d:Day,Days;	Nest inside div[data-countdown-date] to display a label for days
data-hours-label	%!H:Hour,Hours;	Nest inside div[data-countdown-date] to display a label for hours
data-minutes-label	%!M:Minute,Minutes;	Nest inside div[data-countdown-date] to display a label for minutes
data-seconds-label	%!S:Second,Seconds;	Nest inside div[data-countdown-date] to display a label for seconds

The text of the label element will be updated once per second. For example, if there is one day remaining, the label will read "Day" if there are more than 1 days remaining, the label will read "Days".

<div class="col-12" data-countdown-date="2019/08/06" data-detailed>
  <span data-years></span>
  <span data-years-label></span>

  <span data-months></span>
  <span data-months-label></span>

  <span data-weeks></span>
  <span data-weeks-label></span>

  <span data-days></span>
  <span data-days-label></span>

  <span data-hours></span>
  <span data-hours-label></span>

  <span data-minutes></span>
  <span data-minutes-label></span>

  <span data-seconds></span>
  <span data-seconds-label></span>
</div>

All labels are optional.

Formatting labels is optional, and is handled on a per-label basis.

Pluralization provided by the plugin allows label text to update so it reads correctly according to the number it represents.

• Labels are dynamic and are updated once per second.
• By default, labels are configured with pluralization in English.

For example, to override the default text in the Days label, add data-format to the data-days-label element.

This example shows translation to Spanish. The days label will read día when days is 1, and días when plural.

<div class="col-12" data-countdown-date="2019/08/06" data-detailed>
  <span data-days></span>
  <span data-days-label data-format="%!d:día,días;"></span>

  <span data-hours></span>
  <span data-hours-label></span>

  <span data-minutes></span>
  <span data-minutes-label></span>

  <span data-seconds></span>
  <span data-seconds-label></span>
</div>

See the plugin documentation for the full list of formatting options.

While the countdown is running, it is considered to be in an active state. When the countdown reaches the specified date/time, it enters the elapsed state.

When the countdown is elapsed, you may wish to show some text, or show completely different content. This is possible by employing the data-active-state and data-elapsed-state divs.

Wrap your countdown elements and labels in a data-active-state div and they will be hidden when the countdown reaches it's elapsed state.

The data-elapsed-state div will then be shown.

<div class="col-12" data-countdown-date="2019/08/06" data-detailed>
  <div data-active-state>
    <span data-days></span>
    <span data-days-label data-format="%!d:día,días;"></span>

    <span data-hours></span>
    <span data-hours-label></span>

    <span data-minutes></span>
    <span data-minutes-label></span>

    <span data-seconds></span>
    <span data-seconds-label></span>
  </div>
  <div data-elapsed-state class="d-none">
    <h3> This will show when the countdown is elapsed</h3>
  </div>
</div>

The data-elapsed-state div requires class d-none. When the countdown reaches its elapsed state, this class is removed and d-none is added to the data-active-state div.