మూస:Countdown-ymd/doc పేజీ సోర్సు చూడండి

{{Documentation subpage}}
{{lua|Module:Countdown-ymd}}

<!-- Please place categories where indicated at the bottom of this page and interwikis at Wikidata (see [[Wikipedia:Wikidata]]) -->
Similar to {{tlx|countdown}}, {{tld|countdown-ymd}} renders a countdown in years, months, days, hours, minutes, and seconds.  It also offer different text handling and supports UTC offsets.

== Usage ==
The minimal form is:
:<code><nowiki>{{countdown-ymd |year=event year}}</nowiki></code>
which gives:
:{{countdown-ymd |year={{#time:Y|now + 1 year}}}}

===Parameters===
{{tld|countdown-ymd}} renders an output that is the difference between the date / time of the article's last refresh to the date / time of a future event.

====event date / time====
{| class="wikitable floatright"
|+24hr time
!12hr clock
!colspan="2"|24hr clock
|-
!am/pm !!am !! pm
|-
|midnight || 00 || 
|-
|noon|| || 12
|-
|1||01||13
|-
|2||02||14
|-
|3||03||15
|-
|4||04||16
|-
|5||05||17
|-
|6||06||18
|-
|7||07||19
|-
|8||08||20
|-
|9||09||21
|-
|10||10||22
|-
|11||11||23
|}
Date / time calculations are made using [[UTC]] time provided by WikiMedia's servers.  Future event date / times are assumed to begin or end at the UTC time specified in these parameters.  {{para|utc offset}} can ease the calculation burden.
:'''year''': required; four-digit year in which the event takes place 
:'''month''': required if '''day''' is specified; one- or two-digit month in which the event takes place; January = 1
:'''day''': required if '''hour''' is specified; one- or two-digit day on which the event takes place; 1–28, 29, 30, or 31 depending on '''month''' and '''year'''
:'''hour''': required if '''minute''' is specified; one- or two-digit hour at which the event takes place; uses 24-hour clock; 0–23; defaults to midnight (00h)
:'''minute''': required if '''second''' is specified; one- or two-digit minute at which the event takes place; 0–59; defaults to on the hour (hh:00)
:'''second''': one- or two-digit second at which the event takes place; 0–59; defaults to on the minute (hh:mm:00)
:'''duration''': time in the form of a number followed by a unit keyword that, when added to the event start date / time, identifies the event end date / time; accepted unit keywords are <code>day</code>, <code>hour</code>, <code>minute</code>, <code>second</code> in both singular and plural forms; default is <code>second</code>
:'''utc offset''': hours and minutes difference between UTC and local time zone

====presentation====
The presentation parameters allow users to customize the template output to suit particular needs.
:'''color''': sets the color of the date / time digits in the rendered output; default is {{color|blue|blue}}
:'''event lead''': requires '''duration'''; text that precedes the countdown when the countdown refers to the end of the event; default is: 'Event ends in' (without quotes)
:'''event tail''': requires '''duration'''; text that follows the countdown when the countdown refers to the end of the event; terminal punctuation is not supplied
:'''expired''': text to be displayed when the event date / time has passed; default is 'Event time has passed.' (without quotes)
:'''lead''': text that precedes the countdown when the countdown refers to the event; defaults: 'Time to event:' (without quotes); when '''duration''' is set: 'Event begins in' (without quotes)
:'''tail''': text that follows the countdown when the countdown refers to the event; terminal punctuation is not supplied

==examples==
In the following examples, the countdown time to the event is determined from the date / time that this page was last refreshed.  That date / time is:
:{{#time:r}}
:{{#time:Y-m-d\TH:i:s (T)}} ([[ISO 8601]] format)

===countdown===
Countdown to tomorrow at 6 pm (18:00:00 UTC) → {{#time:Y|tomorrow}}-{{#time:m|tomorrow}}-{{#time:d|tomorrow}}T18:00:00 (UTC)
:<code><nowiki>{{</nowiki>countdown-ymd |lead=none |year={{#time:Y|tomorrow}} |month={{#time:n|tomorrow}} |day={{#time:d|tomorrow}} |hour=18 |minute=0 |second=0<nowiki>}}</nowiki></code>
::{{countdown-ymd |lead=none |year={{#time:Y|tomorrow}} |month={{#time:n|tomorrow}} |day={{#time:d|tomorrow}} |hour=18 |minute=0 |second=0}}
Countdown to {{#time:j F Y|tomorrow + 6 months}} at 6pm (18:00:00 UTC) → {{#time:Y|tomorrow + 6 months}}-{{#time:m|tomorrow + 6 months}}-{{#time:d|tomorrow + 6 months}}T18:00:00 (UTC)
:<code><nowiki>{{</nowiki>countdown-ymd |lead=none |year={{#time:Y|tomorrow + 6 months}} |month={{#time:m|tomorrow + 6 months}} |day={{#time:d|tomorrow + 6 months}} |hour=18<nowiki>}}</nowiki></code>
::{{countdown-ymd |lead=none |year={{#time:Y|tomorrow + 6 months}} |month={{#time:m|tomorrow + 6 months}} |day={{#time:d|tomorrow + 6 months}} |hour=18}} – {{tld|countdown-ymd}} reduces the rendered precision when {{para|minute}} and / or {{para|second}} are not specified
Countdown to {{#time:j F Y ga|now + 2 hours}}
:<code><nowiki>{{</nowiki>countdown-ymd |lead=none |year={{#time:Y|now + 2 hours}} |month={{#time:m|now + 2 hours}} |day={{#time:d|now + 2 hours}} |hour={{#time:H|now + 2 hours}}<nowiki>}}</nowiki></code>
::{{countdown-ymd |lead=none |year={{#time:Y|now + 2 hours}} |month={{#time:m|now + 2 hours}} |day={{#time:d|now + 2 hours}} |hour={{#time:H|now + 2 hours}}}} – when less than 24 hours until the event, {{tld|countdown-ymd}} shifts to an hours minutes and seconds  display regardless of the state of {{para|minute}} and {{para|second}}

====duration====
An event can be a single point in time as the deadline for filing yearly tax returns, or it can have beginning and end date / times.  For this latter, {{tlx|countdown-ymd}} uses {{para|duration}}.  For events that are not single point events, the start time is defined by the basic date / time parameters and the end time is the start time plus duration (a number) of duration units.  The supported duration units are seconds, minutes, hours, and days.  For an event that lasts two weeks we write {{para|duration|14}} {{para|duration unit|days}}.

Default rendering for an event that lasts two hours but hasn't yet begun:
:<code><nowiki>{{</nowiki>countdown-ymd |duration=2 hours |year={{#time:Y|tomorrow}} |month={{#time:n|tomorrow}} |day={{#time:d|tomorrow}} |hour=18 |minute=0 |second=0<nowiki>}}</nowiki></code>
::{{countdown-ymd |duration=2 hours |year={{#time:Y|tomorrow}} |month={{#time:n|tomorrow}} |day={{#time:d|tomorrow}} |hour=18 |minute=0 |second=0}}
Default rendering for an event in progress that lasts two hours but hasn't yet ended:
:<code><nowiki>{{</nowiki>countdown-ymd |duration=2 hours |year={{#time:Y|now - 1 hour}} |month={{#time:n|now - 1 hour}} |day={{#time:d|now - 1 hour}} |hour={{#time:H|now - 1 hour}} |minute=0 |second=0<nowiki>}}</nowiki></code>
::{{countdown-ymd |duration=2 hours |year={{#time:Y|now - 1 hour}} |month={{#time:n|now - 1 hour}} |day={{#time:d|now - 1 hour}} |hour={{#time:H|now - 1 hour}} |minute=0 |second=0}}

====utc offset====
{{para|utc offset}} eliminates the need to calculate UTC time from local time if the UTC offset of the local time is known.  For example, [[Phoenix, Arizona]] is in [[Mountain Time Zone]] or [[UTC−07:00]].  An event that occurs a noon local time in Phoenix occurs at 7pm UTC.

Countdown to {{#time:j F Y ga|now - 4 hours}} local time in Phoenix
:<code><nowiki>{{</nowiki>countdown-ymd |utc offset=-7:00 |lead=none |year={{#time:Y|now - 4 hours}} |month={{#time:m|now - 4 hours}} |day={{#time:d|now - 4 hours}} |hour={{#time:H|now - 4 hours}}<nowiki>}}</nowiki></code>
::{{countdown-ymd |utc offset=-7:00 |lead=none |year={{#time:Y|now - 4 hours}} |month={{#time:m|now - 4 hours}} |day={{#time:d|now - 4 hours}} |hour={{#time:H|now - 4 hours}}}}

The Phoenix example was chosen because Arizona does not observe [[daylight saving time]].  For those locations that do, editors must account for the time difference when setting {{para|utc offset}}.

===presentation===
{{tld|countdown-ymd}} has several parameters that allow editors to customize the appearance of the rendered template.
:'''color''': values can be [[RGB color model|RGB]] hex codes or any of the CSS colors
::{{countdown-ymd |color=#C9E72A|lead=none |year={{#time:Y|now + 2 hours}} |month={{#time:m|now + 2 hours}} |day={{#time:d|now + 2 hours}} |hour={{#time:H|now + 2 hours}}}} – {{para|color|#C9E72A}}
::{{countdown-ymd |color=DarkOliveGreen |lead=none |year={{#time:Y|now + 2 hours}} |month={{#time:m|now + 2 hours}} |day={{#time:d|now + 2 hours}} |hour={{#time:H|now + 2 hours}}}} – {{para|color|DarkOliveGreen}}
:'''lead''' and '''tail''' provide text that precedes and follows the countdown while the countdown is in progress. If lead text is not desired, {{para|lead|none}} will suppress the default lead text.
::<code><nowiki>{{</nowiki>countdown-ymd<br /></code>
::|<code>lead=<nowiki>'''</nowiki>lead<nowiki>'''</nowiki> precedes the countdown:<br /></code>
::|<code>tail=which is followed by <nowiki>'''</nowiki>tail<nowiki>'''</nowiki> while the countdown is in progress.<br /></code>
::|<code>year={{#time:Y|now - 1 hour}} |month={{#time:n|now - 1 hour}} |day={{#time:d|now - 1 hour}} |hour={{#time:H|now - 1 hour}} |minute=0 |second=0<nowiki>}}</nowiki></code>
:::{{countdown-ymd |lead='''lead''' precedes the countdown: |tail=which is followed by '''tail''' while the countdown is in progress. |year={{#time:Y|tomorrow}} |month={{#time:n|tomorrow}} |day={{#time:d|tomorrow}} |hour=18 |minute=0 |second=0}}
:'''event lead''' and '''event tail''' provide text that precedes and follows the countdown while an event is in progress.  These parameters require '''duration''' without which they are ignored. If leading event text is not desired, {{para|event lead|none}} will suppress the default event lead text.
::<code><nowiki>{{</nowiki>countdown-ymd<br /></code>
::|<code>event lead=<nowiki>'''</nowiki>event lead<nowiki>'''</nowiki> precedes the countdown:<br /></code>
::|<code>event tail=which is followed by <nowiki>'''</nowiki>event tail<nowiki>'''</nowiki> while the event is in progress.<br /></code>
::|<code>duration=2 |duration unit=hours<br /></code>
::|<code>year={{#time:Y|now - 1 hour}} |month={{#time:n|now - 1 hour}} |day={{#time:d|now - 1 hour}} |hour={{#time:H|now - 1 hour}} |minute=0 |second=0<nowiki>}}</nowiki></code>
:::{{countdown-ymd |event lead='''event lead''' precedes the countdown: |event tail=which is followed by '''event tail''' while the event is in progress. |duration=2 |duration unit=hours |year={{#time:Y|now - 1 hour}} |month={{#time:n|now - 1 hour}} |day={{#time:d|now - 1 hour}} |hour={{#time:H|now - 1 hour}} |minute=0 |second=0}}
:'''expired''' provides text to take the place of the countdown once the countdown is completed.  If text noting the completion of the countdown is not desired, {{para|expired|none}} will suppress the default completion text.
::<code><nowiki>{{</nowiki>countdown-ymd<br /></code>
::|<code>expired=<nowiki>'''</nowiki>expired<nowiki>'''</nowiki> takes the place of a completed countdown.<br /></code>
::|<code>year={{#time:Y|yesterday}} |month={{#time:n|yesterday}} |day={{#time:d|yesterday}} |hour=18 |minute=0 |second=0<nowiki>}}</nowiki></code>
:::{{countdown-ymd |expired='''expired''' takes the place of a completed countdown. |year={{#time:Y|yesterday}} |month={{#time:n|yesterday}} |day={{#time:d|yesterday}} |hour={{#time:H|yesterday}} |minute=0 |second=0}}

==error messages==
{{tld|countdown-ymd}} emits only one error message:
:<span style="font-size:100%" class="error">Error: invalid date and/or time</span>
For dates, the valid combinations of parameters are:
:{{para|year}} or
:{{para|year}} {{para|month}} or
:{{para|year}} {{para|month}} {{para|day}}
all other date combinations are erroneous.
 
If time is included, all of the date parameters are required and one of these combinations of time parameters:
:{{para|hour}} or
:{{para|hour}} {{para|minute}} or
:{{para|hour}} {{para|minute}} {{para|second}}
all other time combinations are erroneous.

Countdown to 30 February {{#time:Y|now + 1 year}}
:<code><nowiki>{{</nowiki>countdown-ymd |lead=none |year={{#time:Y|now + 1 year}} |month=2 |day=30<nowiki>}}</nowiki></code>
::{{countdown-ymd |lead=none |year={{#time:Y|now + 1 year}} |month=2 |day=30}}

==see also==
{{tlx|countdown}} – renders a similar countdown in years, weeks, days, hours, minutes, and seconds.

{{UTC time offsets}}

<includeonly>{{Sandbox other| |
<!-- Categories below this line, please; interwikis at Wikidata -->

}}</includeonly>