CountdownDoc

## Description

The **dmkCountdown** script creates a countdown clock where specified.

## What it does

You add an element with a target date to the page and this script will replace that date with a countdown until the day/hour/minute/second of that date is reached.

## Creating a countdown

A countdown can be added to a page using the following format:

```
<span class="dmkcountdown" style="display:none;">Only <span class="countdowndate">January 01 2025 00:00:00</span> until the new year...</span>

```
The text within "countdown" only appears when the countdown is active. Any text before "countdowndate" will precede the countdown, and any text after "countdowndate" will follow the countdown.

The example above produces:

Only January 01 2025 00:00:00 until the new year...(Countdown example)

An optional span with class "nodmkcountdown" can be used as alternative text when the countdown script does not work or while it is loading.

* e.g. Using `<span class="nodmkcountdown">It's almost the new year!</span>` results in
**"It's almost the new year!"** while the script loads.

This span should be placed directly after the countdown code above.

## Time zones

Using the example code above, the countdown works relative to the reader's system clock. While this may be useful in cases such as counting down to the new year, it is impractical in others.

Two methods can be used to make the countdown work based on a specific time zone. The easiest is to add the time zone identifier to the end of the code. For example, to make a countdown for Eastern Standard Time (EST):

```
<span class="countdowndate">January 01 2025 00:00:00 EST</span>

```

While this method works with most identifiers, it does not work for *some* daylight savings variants (e.g. British Summer Time - BST).

An alternative and more reliable method is to add the Coordinated Universal Time (UTC) offset to the end of the code. For example, to make a countdown for EST, which has an offset of -5 hours:

```
<span class="countdowndate">January 01 2025 00:00:00 -0500</span>

```

Note that changes to and from daylight savings are not done automatically, and must be done by the user - either with the daylight savings identifier, or by using the UTC offset.

## Options

### Ending the Countdown

How do you want the countdown to end? There are five options:

1. stopping the countdown at zero — this is the default for legacy reasons
2. counting up from zero
3. removal of the countdown container
4. replacing the countdown with something else
5. calling a custom JavaScript function of your choice

#### Stop

Since this is the default option, you don't need to do anything.

#### Countup

Add a `data-end` attribute with the value "countup" to the container:

```
<span data-end="countup" class="dmkcountdown" style="display:none;"><!--
-->Only <span class="countdowndate">January 01 2025 00:00:00</span> until the new year...<!--
--></span>

```

#### Remove

Add a `data-end` attribute with the value "remove" to the container:

```
<span data-end="remove" class="dmkcountdown" style="display:none;"><!--
-->Only <span class="countdowndate">January 01 2025 00:00:00</span> until the new year...<!--
--></span>

```

#### Replacement

Add a `data-end` attribute with the value "toggle" to the container. Additionally you will have to add a `data-toggle` attribute with a selector that points to the replacement:

```
<span data-end="toggle" data-toggle=".post-countdown" class="dmkcountdown" style="display:none;"><!--
-->Only <span class="countdowndate">January 01 2025 00:00:00</span> until the new year...<!--
--></span><span class="post-countdown" style="display:none;">Happy 2025!</span>

```

Note the dot in the value of `data-toggle`! The expected value is a CSS or jQuery selector. So that's ".name" for classes. "#name" for IDs. Etc.

Alternatively, if the toggle container is the following one after the counter, the special value `data-toggle="next"` can be used instead, without needing to specify any selector. This is useful when using multiple countdowns as part of a template, for instance.

#### Custom Callback

Add a `data-end` attribute with the value "callback" to the container. Additionally you will have to add a `data-callback` attribute with the name of the function you want to call:

```
<span data-end="callback" data-callback="myFunction" class="dmkcountdown" style="display:none;"><!--
-->Only <span class="countdowndate">January 01 2025 00:00:00</span> until the new year...<!--
--></span>

```

The countdown will stop at zero and then your function will be called. The countdown container will be the `this` object of the function.

To make the function available to the Countdown module, you will have to add it to the module itself:

```
window.dmkcountdownTimer = {
 myFunction: function () {
 $(this).text('Happy 2025!');
 }
}

```

## Display Format

By default, the countdown will be displayed following the DMK in-game timers. For this, the following format options are enabled by default:

* **no-leading-zeros**
* **short-format**
* **first-two**

To override the default format, add a `data-options` attribute with the value "no-dmk":

```
<span data-options="no-dmk" class="dmkcountdown" style="display:none;"><!--
-->Only <span class="countdowndate">January 01 2025 00:00:00</span> until the new year...<!--
--></span>

```

### Leading Zeros

With leading zeros, the display is of the format:

```
0 days, 0 hours, 10 minutes and 10 seconds
```

To remove the leading zeros to display in the format (default):

```
10 minutes and 10 seconds
```

you need to add a `data-options` attribute with the value "no-leading-zeros":

```
<span data-options="no-dmk no-leading-zeros" class="dmkcountdown" style="display:none;"><!--
-->Only <span class="countdowndate">January 01 2025 00:00:00</span> until the new year...<!--
--></span>

```

### Short format

If you prefer to show the countdown in a short format like `2d 5h 30m 1s` instead of the full words, you need to add a `data-options` attribute with the value "short-format". This option is enabled by default.

If you already set the `data-options` attribute, add all the options separating them with a space:

```
<span data-options="no-leading-zeros short-format" class="countdown" style="display:none;"><!--
-->Only <span class="countdowndate">January 01 2025 00:00:00</span> until the new year...<!--
--></span>

```

### Long format

This option "long-format" is the opposite of "short-format"

### First Two Non-Zero terms

If you prefer to show the countdown in the format similar to DMK in-game timers, with the first two non-zero terms displayed, like `2d 5h` instead of the full date, you need to add a `data-options` attribute with the value "first-two". Enabled by default.

If you already set the `data-options` attribute, add all the options separating them with a space:

```
<span data-options="no-dmk first-two" class="countdown" style="display:none;"><!--
-->Only <span class="countdowndate">January 01 2025 00:00:00</span> until the new year...<!--
--></span>

```

### Full mode

This option "full-mode" is the opposite of "first-two"

## Dynamic content

This script supports dynamic inserted content, such as article comments or editor previews. However, if you insert a counter via JavaScript, you need to fire this event after inserting it:

```
mw.hook('wikipage.content').fire($('ELEMENT'));

```

Where `ELEMENT` is a selector to the element in which the counter has been inserted.

## Major Updates

May 30, 2021
Effan R: first version customized for DMK Wiki