Duration block
Duration block
Code
<script type="text/javascript">
$( document ).ready( function() {
var generalData = {
id: {{ID}},
referenceDateTime: "2020-12-25T00:00:00.000-07:00",
largestDateTimeUnit: 4,
smallestDateTimeUnit: 0,
useDynamicUnits: false,
durationNotApplicablePhrase: "Duration not applicable",
referenceDateTimeInvalidPhrase: "Reference date/time invalid or not available"
};
var displayOptions = {
liveUpdate: true,
hideWhenDurationNotApplicable: false,
hideWhenLargestDurationExceeded: false,
hideWhenReferenceDateTimeInvalid: false
};
var countUpOptions = {
outputCountUp: false,
countUpValueQualifierType: "none",
countUpValueRoundingType: "down",
beforeCountUpValuePhrase: "",
afterCountUpValuePhrase: "",
countUpLargestDuration: 10,
countUpLargestDurationUnit: "years",
countUpLargestDurationExceededPhrase: "Largest duration exceeded"
};
var countDownOptions = {
outputCountDown: true,
countDownValueQualifierType: "none",
countDownValueRoundingType: "down",
beforeCountDownValuePhrase: "Only",
afterCountDownValuePhrase: "remaining",
countDownLargestDuration: 10,
countDownLargestDurationUnit: "years",
countDownLargestDurationExceededPhrase: "Largest duration exceeded"
};
var durationBlockTimer = new COC.Components.DurationBlock.Timer(generalData, displayOptions, countUpOptions, countDownOptions);
durationBlockTimer.StartTimer();
});
</script>
<div id="durationBlock{{ ID }}" class="duration-block cui {{ vertical | horizontal | single-line }} {{ bg-light | bg-medium | bg-transparent }} {{ highlight }} {{ md | lg }} aria-hidden="true" ">
<div id="durationBlockHeader{{ID}}" class="time-header-block">
<p class="time-header-block-text">{{ content }}</p>
</div>
<div id="durationBlockBody{{ ID }}" class="time-body-block {{ unit-full-word | unit-abbr | unit-hide }}">
<div class="holder year">
<span class="year-number number"></span>
<span class="{{ year-title | years-title }}"></span>
</div>
<div class="holder month">
<span class="month-number number"></span>
<span class="{{ month-title | months-title }}"></span>
</div>
<div class="holder week">
<span class="week-number number"></span>
<span class="{{ week-title | weeks-title }}"></span>
</div>
<div class="holder day">
<span class="day-number number"></span>
<span class="{{ day-title | days-title }}"></span>
</div>
<div class="holder hour">
<span class="hour-number number"></span>
<span class="{{ hour-title | hours-title }}"></span>
</div>
<div class="holder minute">
<span class="minute-number number"></span>
<span class="{{ minute-title | minutes-title }}"></span>
</div>
<div class="holder second">
<span class="second-number number"></span>
<span class="{{ second-title | seconds-title }}"></span>
</div>
</div>
<div id="durationBlockFooter{{ID}}" class="time-footer-block">
<p class="time-footer-block-text">{{ content }}</p>
</div>
</div>
<div id="durationBlockScreenReaderOutput{{ID}}" class="sr-only" role="alert" aria-live="polite"></div>Usage
General guidelines
Displaying time units
- When expressing duration as more than one unit of time (i.e. a combination of days, hours, and minutes), always show unit labels for each unit value
- When hiding the unit (only when a single unit value is being shown for the duration), ensure that supporting labels still convey the unit being shown (i.e. "Days until event starts:")
- Don't hide time units when showing duration as a combination of more than one time unit values (i.e. hours and minutes)
Use an appropriate range of units
Any range of time units can be used as long as it is supported by how time is evaluated for the duration block in implementation
- Generally, select units that allow duration to be expressed in values of 3 or less digits (across the range of durations that the duration block will show over its lifetime)
- Use seconds for precise deadlines or where expectations of exact duration is expected (i.e. fireworks, New Year's, time remaining to apply)
- Use years only when representing long-term projects, plans, or impacts
- Don't skip units between the largest and smallest units - display the full range of units in between the largest and smallest time units being displayed
- Don't use a range of units that will prevent all duration unit values from being displayed side-by-side (i.e. do not force the duration value to wrap in any display)
Support each duration value with clear context
- Use clear labelling for the duration block, either:
- Outside the duration block: for labels that will not change or be removed as the duration value or context changes (i.e. when a countdown expires)
Within the duration block (immediately before or after the duration value): when labelling may change as the duration value changes
- Labels associated with a duration block must convey:
- What the duration block applies to (i.e. event name, deadline, project)
- What measure of time is represented (time passed by, time remaining until, etc)
- Where needed, use duration value qualifiers in labels (i.e. "over/under", "more than/less than") to convey more accurate context and sense of urgency/comfort for values shown (i.e. show "over 3 days left" vs "3 days left"). When used, qualifiers must work hand-in-hand with how rounding is being applied to duration values in implementation
- Don't place a duration block into a page without clear context for what the duration represents
When updating live, only use one duration block per page
- If the duration block is being updated after initial page load, it must be the only item that is updated dynamically without user intervention.
- If not being updated live, multiple duration blocks can be displayed in a single page and/or with other dynamically-updated elements
- Don't update multiples duration blocks in-page without user intervention (i.e. filters applied, reset/update buttons used)
- Don't update the duration block in-page when alongside other items that also update dynamically without user intervention
Use for date-related content, not user session information (i.e. no timeouts)
- Use the duration block to convey how far the current time is from another content-related date (independent of the current user session)
- Don't use the duration block to convey user session-related information, such as timeouts, session log-in length
Implementation Considerations
The Duration Block pattern captures how a span of time can be displayed. However, as the use of this pattern is intended for dynamically conveying information relative to the current time, it also relies on the capabilities of the system it is implemented in (i.e. how time is evaluated and processed on the server or within a browser, and what happens when the context for the duration changes). Therefore, additional considerations need to be made in implementation for it to be applied properly.
Handling shifting context:
Adjust messaging and labels:
The duration block pattern displays a single duration, but if the duration context for a duration block shifts - i.e. countdown starts or completes, count up starts or a limit is reached, the messaging surrounding the duration value should also change to reflect that shift
Duration not yet or no longer applicable:
- After a countdown has expired and when a count up has not yet started, the duration shown can be zero. However alternative content should instead be provided (either automated via a control, or manually adjusted) in place of the duration block or the duration block should be removed
- The duration block must never be used to show "negative duration" (instead, alternative labelling should be applied to reflect the change in context with a positive duration value)
Avoid displaying very long durations:
As when a duration is not applicable, a count up duration should not be left to continue indefinitely - a limit on the duration should be set and (via automation or manual content adjustments) alternative content should replace the duration block, or the duration block should be removed
Handling display of imprecise durations
Rounding
Unless seconds are displayed, there will not be a precise match between the duration shown and the actual current duration. Implementation must consider what happens when a duration is not an exact match - rounding the smallest time unit value up or down accordingly. If not done the same for all values - i.e. if rounding to closest value - then the labelling applied to duration block, such as value qualifiers, may also need to be applied dynamically along with the duration.
Month and year values
As months and years are not precise durations (i.e. a month can range from 28 to 31 days), how they are interpreted is dependent on implementation. Some platforms and libraries may be able to determine more intuitive comparisons while other may not (i.e. is Apr 15 more than two months away from Feb 14?), and care should be taken to ensure a duration block will display values properly if month and year units are to be used.
Live updates: Announcing changes in an accessible manner
Content presented to screen readers (and other non-visual mediums) must match what is being presented in visual displays. Therefore, if updating duration block content continually in-page without user intervention, non-sighted readers must also be made aware of the changes.
- This may implemented as a separate element containing the duration information portrayed in the duration block (while hiding the duration block visual content).
- Updates should only be announced to screen readers when the content of the duration block actually changes (i.e. not at a set interval ignoring if content changed or not)
- Updates should be announced using aria-live value of "polite"
- Exceptions to the above:
- Announcements to screen readers should only be made once a minute at most, even if displayed duration block time values update every second)
- Content considered critical in context may be announced using aria-live value of "assertive" (essentially raising an audio alert)