# Countdowns

Provides an animated countdown to display time remaining until a specified time and date.

###

About the Plugin

Website GitHub npm

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.

###

Initializing

The demo pages already include the following code. These steps are only necessary if you are building a page from scratch. Remove these references if you are not using this plugin to improve page load times.

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,
         };

###

Basic Usage

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.

###

Advanced Usage

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

###

Formatting

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.

###

Labels

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

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.

###

Elapsed State

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.