Agenda component in the Microsoft Graph Toolkit

The mgt-agenda web component represents events in a user or group calendar. By default, the calendar displays the current signed in user events for the current day. The component can also use any endpoint that returns events from Microsoft Graph.

Example

The following example shows the signed-in user's calendar events displayed using the mgt-agenda component. You can use the code editor to see how properties change the behavior of the component.

Open this example in mgt.dev

Properties

By default, the mgt-agenda component fetches events from the /me/calendarview endpoint and displays events for the current day. There are several properties you can use to change this behavior.

Attribute Property Description
date date A string that represents the start date of the events to fetch from Microsoft Graph. Value should be in a format that can be parsed by the Date constructor - value has no effect if event-query attribute is set.
days days A number of days to fetch from Microsoft Graph - default is 3 - value has no effect if event-query attribute is set.
show-max showMax A number to indicate the maximum number of events to show. The default value is not set (no maximum).
group-id groupId A string ID for a group calendar to use instead of the current signed in user's calendar.
event-query eventQuery A string that represents an alternative query to be used when fetching events from Microsoft Graph. Optionally, add the delegated scope at the end of the string by delimiting it with | (/groups/GROUP-ID-GUID/calendar/calendarView | group.read.all).
events events An array of events to get or set the list of events rendered by the component - use this property to access the events loaded by the component. Set this value to load your own events - if value is set by developer, the date, days, or event-query attributes have no effect.
group-by-day groupByDay A Boolean value to group events by day - by default events are not grouped.
preferred-timezone preferredTimezone Name of the preferred time zone to use when retrieving events from Microsoft Graph; for example, Pacific Standard Time. By default, this attribute uses the UTC time zone. The preferred time zone for the current user can be retrieved by calling the me/mailboxSettings endpoint and reading the value of the timeZone property.

The following example changes the behavior of the component to fetch data for a specific date and up to three days.

<mgt-agenda
  group-by-day
  date="May 7, 2019"
  days="3"
  ></mgt-agenda>

The following example changes the behavior of the component to fetch data from a specific query.

<mgt-agenda
  event-query="/me/events?orderby=start/dateTime"
  ></mgt-agenda>

Methods

Method Description
reload() Call the method to reload the component with potential new data based on its properties.

CSS custom properties

The mgt-agenda component defines these CSS custom properties

mgt-agenda {
  --event-box-shadow: 0px 2px 8px rgba(0, 0, 0, 0.092);
  --event-margin: 0px 10px 14px 10px;
  --event-padding: 8px 0px;
  --event-background-color: #ffffff;
  --event-border: solid 2px rgba(0, 0, 0, 0);

  --agenda-header-margin: 40px 10px 14px 10px;
  --agenda-header-font-size: 24px;
  --agenda-header-color: #333333;

  --event-time-font-size: 12px;
  --event-time-color: #000000;

  --event-subject-font-size: 19px;
  --event-subject-color: #333333;

  --event-location-font-size: 12px;
  --event-location-color: #000000;
}

To learn more, see styling components.

Templates

The mgt-agenda component supports several templates that allow you to replace certain parts of the component. To specify a template, include a <template> element inside of a component and set the data-type value to one of the following:

Data type Data context Description
default events: list of event objects The default template replaces the entire component with your own.
event event: event object The template used to render each event.
event-other event: event object The template used to render additional content for each event.
header header: string The template used to render the header for each day.
loading No data context is passed The template used when data is loading.
no-data No data context is passed The template used when no events are available.

The following examples illustrates how to use the event template:

<mgt-agenda>
  <template data-type="event">
    <button class="eventButton">
      <div class="event-subject">{{ event.subject }}</div>
      <div data-for="attendee in event.attendees">
        <mgt-person
          person-query="{{ attendee.emailAddress.name }}"
          view="twolines">
        </mgt-person>
      </div>
    </button>
  </template>
  <template data-type="no-data">
    There are no events found!
  </template>
</mgt-agenda>

To learn more, see templates.

Events

The following events are fired from the control.

Event When is it emitted Custom data Cancelable Bubbles Works with custom template
eventClick The user clicks or taps an event. Selected event No No Yes, with custom event template

For more information about handling events, see events.

Microsoft Graph permissions

This component uses the following Microsoft Graph APIs and permissions:

Configuration Permission API
default Calendars.Read /me/calendarview

The component allows you to specify a different Microsoft Graph query to call (such as /groups/{id}/calendar/calendarView). In this case, append the permission to the end of the string, delimited by |.

When using the default template and default renderAttendees template, additional APIs and permissions are required. The default template for this component uses a mgt-people component for events that have attendees, and inherits all permissions.

Authentication

The login control uses the global authentication provider described in the authentication documentation.

Cache

The mgt-agenda component doesn't cache any data.

Extend for more control

For more complex scenarios or a truly custom UX, this component exposes several protected render* methods for override in component extensions.

Method Description
renderLoading Renders a loading state while the component loads.
renderNoData Renders an empty data state.
renderGroups Sorts event data into groups and renders them with group headers.
renderHeader Renders a group header.
renderEvents Renders a list of event objects.
renderEvent Renders a singular event and all of its parts.
renderTitle Renders the event title part.
renderLocation Renders the event location part.
renderAttendees Renders the event attendees part.
renderOther Renders additional event content.