# Calendar of Events

Questions or comments?

## Purpose

This feature provides an interface for navigating a chronological list of events. Implements the WAI-ARIA Date Picker design pattern.

## Use when

This feature can be used on any page where displaying a list of events in a calendar format is needed.

## Working example

- English example
- French example

## How to implement

1. Add a div element to the Web page with a `class` attribute containing "wb-calevt" and a unique name in a `data-calevt-src` attribute (e.g.: `<div class="wb-calevt" data-calevt-src="unique-name"></div>`).
2. Include in the div element a ordered list of events (ol element) with the following structure for each event:
   1. The list element must start with a heading element (`h2` to `h6`, depending on the context of the page).
   2. The heading element must include a link to the event description with the event title for the link text.
   3. The event date must be provided in an HTML5 `time` element contained within a paragraph element (following the heading element). The date to be displayed is contained in the `time` element and an ISO-8601 date (e.g., 2010-03-11) is provided in the `datetime` attribute.
3. Add a second `div` element to the Web page with an `id` attribute containing your `data-calevt-src` attribute's unique name from above (e.g., `<div id="unique-name"></div>`). This will hold the calendar interface.

### Example Code

    <div id="calendar1"></div>

    <div class="wb-calevt" data-calevt-src="calendar1">
    	<ol>
    		<li>
    			<section>
    				<h4><a href="http://www.canada.gc.ca">Single-Day Event</a></h4>
    				<p><time datetime="2011-03-11">March 11th 2011</time></p>
    				<p>Event Description</p>
    			</section>
    		</li>
    		<li>
    			<section>
    				<h4><a href="http://www.canada.gc.ca">Multi-Day Event</a></h4>
    				<p><time datetime="2011-03-22">March 22nd, 2011</time> to <time datetime="2011-04-26">April 26th, 2011</time></p>
    				<p>Event Description</p>
    			</section>
    		</li>
    	</ol>
    </div>

### Details Linking

In this method, the calendar links to the details of the event. This is used when an event has multiple links.

    <div id="calendar2"></div>

    <div class="wb-calevt evt-anchor" data-calevt-src="calendar2">
    	<ol>
    		<li>
    			<section>
    				<h4>Single-Day Event</h4>
    				<p><time datetime="2011-03-11">March 11th 2011</time></p>
    				<p>Event Description</p>
    				<p>Links:</p>
    				<ul>
    					<li><a href="http://www.canada.gc.ca">Single-Day Event Link 1</a></li>
    					<li><a href="http://www.canada.gc.ca">Single-Day Event Link 2</a></li>
    				</ul>
    			</section>
    		</li>
    		<li>
    			<section>
    				<h4>Multi-Day Event</h4>
    				<p><time datetime="2011-03-22">March 22nd, 2011</time> to <time datetime="2011-04-26">April 26th, 2011</time></p>
    				<p>Event Description</p>
    				<p>Links:</p>
    				<ul>
    					<li><a href="http://www.canada.gc.ca">Multi-Day Event Link 1</a></li>
    					<li><a href="http://www.canada.gc.ca">Multi-Day Event Link 2</a></li>
    				</ul>
    			</section>
    		</li>
    	</ol>
    </div>

### List Filtering

This option filters out events from the list that are not for the current month. Enable this option by adding the `cal-disp-onshow` class to each event that should be filtered by month.

Events that do not have the `cal-disp-onshow` class will always be visible.

    <div id="calendar3"></div>

    <div class="wb-calevt evt-anchor" data-calevt-src="calendar3">
    	<section>
    		<h4>Events List 1</h4>
    		<ol>
    			<li class="cal-disp-onshow">
    				<section>
    					<h5><a href="http://www.ec.gc.ca">Event 1</a></h5>
    					<p><time datetime="2011-03-11">March 11th 2011</time></p>
    				</section>
    			</li>
    			<li class="cal-disp-onshow">
    				<section>
    					<h5><a href="http://canada.gc.ca">Event 2</a></h5>
    					<p><time datetime="2011-03-11">March 11th 2011</time></p>
    				</section>
    			</li>
    			<li class="cal-disp-onshow">
    				<section>
    					<h5>World Expo Shanghai (Shanghai, China)</h5>
    					<p><time datetime="2011-03-22">March 22nd, 2011</time> to <time datetime="2011-04-26">April 26th, 2011</time></p>
    					<p>The Canada Pavilion celebrates the vibrancy and the vitality of Canadian communities and the people within them.</p>
    					<p>For more information about Canada at Expo 2010 Shanghai, visit: <a href="http://www.expo2010canada.gc.ca/index-eng.cfm">www.expo2010canada.gc.ca/index-eng.cfm</a></p>
    				</section>
    			</li>
    			<li class="cal-disp-onshow">
    				<section>
    					<h5><a href="http://gcpedia.gc.ca">Event 4</a></h5>
    					<p><time datetime="2011-03-24">March 24th 2011</time></p>
    				</section>
    			</li>
    			<li class="cal-disp-onshow">
    				<section>
    					<h5><a href="http://www.ec.gc.ca">Event 6</a></h5>
    					<p><time datetime="2011-04-11">April 11th 2011</time></p>
    				</section>
    			</li>
    			<li class="cal-disp-onshow">
    				<section>
    					<h5><a href="http://canada.gc.ca">Event 7</a></h5>
    					<p><time datetime="2011-04-23">April 23rd 2011</time></p>
    				</section>
    			</li>
    			<li class="cal-disp-onshow">
    				<section>
    					<h5><a href="http://canada.gc.ca">Event 17</a></h5>
    					<p><time datetime="2011-04-23">April 23rd 2011</time></p>
    				</section>
    			</li>
    		</ol>
    	</section>
    </div>

## Events

Event | Trigger | What it does
--- | --- | ---
`wb-init.wb-calevt` | Triggered manually (e.g., `$elm.trigger( "wb-init.wb-calevt" );`). | Used to manually initialize the Calendar of events plugin. Note: The Calendar of events plugin will be initialized automatically unless the required markup is added after the page has already loaded.
`wb-ready.wb-calevt` (v4.0.5+) | Triggered automatically after a calendar of events initializes. | Used to identify which calendar of events was initialized (target of the event)
    $( document ).on( "wb-ready.wb-calevt", ".wb-calevt", function( event ) {
    });
    $( ".wb-calevt" ).on( "wb-ready.wb-calevt", function( event ) {
    });
`wb-updated.wb-calevt` (v4.0.5+) | Triggered automatically each time the calendar of events is updated (e.g., month changed). | Used to identify which calendar of events was updated (target of the event)
    $( document ).on( "wb-updated.wb-calevt", ".wb-calevt", function( event ) {
    });
    $( ".wb-calevt" ).on( "wb-updated.wb-calevt", function( event ) {
    });
`wb-ready.wb` (v4.0.5+) | Triggered automatically when WET has finished loading and executing. | Used to identify when all WET plugins and polyfills have finished loading and executing.
    $( document ).on( "wb-ready.wb", function( event ) {
    });

## Source code

Source code for the calendar of events

Date modified:
  2014-08-06