---
{
	"title": "Calendar of Events",
	"language": "en",
	"category": "Plugins",
	"categoryfile": "plugins",
	"description": "Dynamically generates a calendar interface for navigating a list of events.",
	"altLangPrefix": "cal-events",
	"dateModified": "2023-08-14"
}
---
<span class="wb-prettify all-pre hide"></span>

<section>
	<h2>Purpose</h2>
	<p>This feature provides an interface for navigating a chronological list of events. Implements the <a href="https://www.w3.org/TR/wai-aria-practices/#datepicker">WAI-ARIA Date Picker design pattern</a>.</p>
</section>

<section>
	<h2>Use when</h2>
	<p>This feature can be used on any page where displaying a list of events in a calendar format is needed.</p>
</section>

<section>
	<h2>Working example</h2>
	<ul>
		<li><a href="../../../demos/cal-events/cal-events-en.html">English example</a></li>
		<li><a href="../../../demos/cal-events/cal-events-fr.html">French example</a></li>
	</ul>
</section>

<section>
	<h2>Evaluation and report</h2>
	<ul>
		<li>Accessibility (SC WCAG 2.1/2.2 Level A &amp; AA)- <a href="../../../demos/cal-events/reports/a11y-1-en.html">English Report</a></li>
		<li>Accessibility (SC WCAG 2.1/2.2 Level A &amp; AA)- <a href="../../../demos/cal-events/reports/a11y-1-fr.html">French Report</a></li>
	</ul>
</section>

<section>
	<h2>How to implement</h2>
	<ol>
		<li>Add a div element to the Web page with a <code>class</code> attribute containing "wb-calevt" and a unique name in a <code>data-calevt-src</code> attribute (e.g.: <code>&lt;div class="wb-calevt" data-calevt-src="unique-name"&gt;&lt;/div&gt;</code>).</li>
		<li>Include in the div element an unordered list of events (ul element) with the following structure for each event:
			<ol>
				<li>The list element must start with a heading element (<code>h2</code> to <code>h6</code>, depending on the context of the page).</li>
				<li>The heading element must include a link to the event description with the event title for the link text.</li>
				<li>The event date must be provided in an HTML5 <code>time</code> element contained within a paragraph element (following the heading element). The date to be displayed is contained in the <code>time</code> element and an ISO-8601 date (e.g., 2010-03-11) is provided in the <code>datetime</code> attribute.</li>
				<li>Note: to exclude an item from being shown on the calendar and in the list, simply add the CSS class <code>wb-fltr-out</code> to the list element (<code>&lt;li&gt;</code>).</li>
			</ol>
		</li>
		<li>Add a second <code>div</code> element to the Web page with an <code>id</code> attribute containing your <code>data-calevt-src</code> attribute's unique name from above (e.g., <code>&lt;div id="unique-name"&gt;&lt;/div&gt;</code>). This will hold the calendar interface.</li>
	</ol>
	<div class="alert alert-info">
		<p><strong>Note</strong>: the plugin still supports <code>&lt;ul&gt;</code> and <code>&lt;ol&gt;</code>, but, as of October 4th 2022, we recommend using a <code>&lt;ul&gt;</code> since items numbers in a <code>&lt;ol&gt;</code> will always start at 1, even when some items are hidden.</p>
	</div>

	<h3>Example Code</h3>
	<pre><code>&lt;div id="calendar1"&gt;&lt;/div&gt;

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

	<section>
		<h3>Details Linking</h3>
		<p>In this method, the calendar links to the details of the event. This is used when an event has multiple links.</p>
		<pre><code>&lt;div id="calendar2"&gt;&lt;/div&gt;

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

	<section>
		<h3>List Filtering</h3>
		<p>This option filters out events from the list that are not for the current month. Enable this option by adding the <code>cal-disp-onshow</code> class to each event that should be filtered by month.</p>
		<p>Events that do not have the <code>cal-disp-onshow</code> class will always be visible.</p>
		<pre><code>&lt;div id="calendar3"&gt;&lt;/div&gt;

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

<section>
	<h2>Events</h2>
	<table class="table">
		<thead>
			<tr>
				<th>Event</th>
				<th>Trigger</th>
				<th>What it does</th>
			</tr>
		</thead>
		<tbody>
			<tr>
				<td><code>wb-init.wb-calevt</code></td>
				<td>Triggered manually (e.g., <code>$elm.trigger( "wb-init.wb-calevt" );</code>).</td>
				<td>Used to manually initialize the Calendar of events plugin. <strong>Note:</strong> The Calendar of events plugin will be initialized automatically unless the required markup is added after the page has already loaded.</td>
			</tr>
			<tr>
				<td><code>wb-ready.wb-calevt</code> (v4.0.5+)</td>
				<td>Triggered automatically after a calendar of events initializes.</td>
				<td>Used to identify which calendar of events was initialized (target of the event)
					<pre><code>$( document ).on( "wb-ready.wb-calevt", ".wb-calevt", function( event ) {
});</code></pre>
					<pre><code>$( ".wb-calevt" ).on( "wb-ready.wb-calevt", function( event ) {
});</code></pre>
				</td>
			</tr>
			<tr>
				<td><code>wb-updated.wb-calevt</code> (v4.0.5+)</td>
				<td>Triggered automatically each time the calendar of events is updated (e.g., month changed).</td>
				<td>Used to identify which calendar of events was updated (target of the event)
					<pre><code>$( document ).on( "wb-updated.wb-calevt", ".wb-calevt", function( event ) {
});</code></pre>
					<pre><code>$( ".wb-calevt" ).on( "wb-updated.wb-calevt", function( event ) {
});</code></pre>
				</td>
			</tr>
			<tr>
				<td><code>wb-ready.wb</code> (v4.0.5+)</td>
				<td>Triggered automatically when WET has finished loading and executing.</td>
				<td>Used to identify when all WET plugins and polyfills have finished loading and executing.
					<pre><code>$( document ).on( "wb-ready.wb", function( event ) {
});</code></pre>
				</td>
			</tr>
			<tr>
				<td><code>wb-redraw.wb-calevt</code> (v4.0.??)</td>
				<td>Triggered manually (e.g., <code>$elm.trigger( "wb-redraw.wb-calevt" );</code>).</td>
				<td>Used to manually redraw the Calendar widget. For example, when events have been changed dynamically after page load.</td>
			</tr>
		</tbody>
	</table>
</section>

<section>
	<h2>Source code</h2>
	<p><a href="https://github.com/wet-boew/wet-boew/tree/master/src/plugins/cal-events">Source code for the calendar of events</a></p>
</section>
