Merge pull request #13209 from waldekmastykarz/mgt-events

Adds documentation for handling MGT events

concepts/toc.yml

@@ -706,6 +706,8 @@ items:
                 href: toolkit/customize-components/style.md
               - name: Templating components
                 href: toolkit/customize-components/templates.md
+              - name: Handling events
+                href: toolkit/customize-components/events.md
               - name: Caching Microsoft Graph calls in components
                 href: toolkit/customize-components/cache.md
               - name: Localizing components

concepts/toolkit/components/agenda.md

@@ -126,7 +126,9 @@ The following events are fired from the control.
 
 | Event | Description |
 | --- | --- |
-| eventClick | The user clicks or taps an event.|
+| `eventClick` | The user clicks or taps an event.|
+
+For more information about handling events, see [events](../customize-components/events.md).
 
 ## Microsoft Graph permissions
 

concepts/toolkit/components/file-list.md

@@ -133,7 +133,9 @@ To learn more, see [styling components](../customize-components/style.md).
 
 | Event | Description |
 | ----- | ----------- |
-| itemClick | Fired when the user clicks a file. Returns the file details. |
+| `itemClick` | Fired when the user clicks a file. Returns the file details. |
+
+For more information about handling events, see [events](../customize-components/events.md).
 
 ## Templates
 

concepts/toolkit/components/get.md

@@ -35,15 +35,18 @@ You can use several attributes to change the behavior of the component. The only
 | N/A |error| Read-only error from Microsoft Graph if request was not successful. |
 
 ## Methods
+
 | Method | Description |
 | --- | --- |
 | refresh(force?:boolean) | Call the method to refresh the data. By default, the UI will only update if the data changes. Pass `true` to force the component to update.  |
 
-
 ## Events
+
 | Event | Detail | Description |
 | --- | --- | --- |
-| dataChange | The detail contains the `response` and `error` objects. | Fired when the response or error change. |
+| `dataChange` | The detail contains the `response` and `error` objects. | Fired when the response or error change. |
+
+For more information about handling events, see [events](../customize-components/events.md).
 
 ## Templates
 

concepts/toolkit/components/login.md

@@ -78,6 +78,8 @@ The following events are fired from the control.
 | `logoutInitiated` | The user started to logout - cancelable. |
 | `logoutCompleted` | The user signed out. |
 
+For more information about handling events, see [events](../customize-components/events.md).
+
 ## Templates
 
 The `mgt-login` component supports several [templates](../customize-components/templates.md) 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 values listed in the following table. 

concepts/toolkit/components/people-picker.md

@@ -76,6 +76,8 @@ The following events are fired from the component.
 | --- | --- |
 | `selectionChanged` | The user added or removed a person from the list of selected/picked people.|
 
+For more information about handling events, see [events](../customize-components/events.md).
+
 ## CSS custom properties
 
 The `mgt-people-picker` component defines the following CSS custom properties.

concepts/toolkit/components/person-card.md

@@ -132,6 +132,8 @@ The following events are fired from the component.
 | --- | --- |
 | `expanded` | The user has opened the expanded details section of the card. |
 
+For more information about handling events, see [events](../customize-components/events.md).
+
 ## CSS custom properties
 
 The `mgt-person-card` component defines the following CSS custom properties. 

concepts/toolkit/components/person.md

@@ -113,9 +113,11 @@ The following events are fired from the component.
 
 | Event | Detail | Description |
 | --- | --- | --- |
-| line1clicked | The detail contains the respective `person` object | Fired when line1 is clicked. |
-| line2clicked | The detail contains the respective `person` object | Fired when line2 is clicked. |
-| line3clicked | The detail contains the respective `person` object | Fired when line3 is clicked. |
+| `line1clicked` | The detail contains the respective `person` object | Fired when line1 is clicked. |
+| `line2clicked` | The detail contains the respective `person` object | Fired when line2 is clicked. |
+| `line3clicked` | The detail contains the respective `person` object | Fired when line3 is clicked. |
+
+For more information about handling events, see [events](../customize-components/events.md).
 
 ## Templates
 

concepts/toolkit/components/tasks.md

@@ -114,12 +114,15 @@ mgt-tasks {
 ````
 
 ## Events
+
 | Event | Detail | Description |
 | --- | --- | --- |
-| taskAdded | The detail contains the respective `task` object | Fires when a new task has been created. |
-| taskChanged | The detail contains the respective `task` object | Fires when task metadata has been changed, such as marking completed. |
-| taskClick | The detail contains the respective `task` object | Fires when the user clicks or taps on a task. |
-| taskRemoved | The detail contains the respective `task` object | Fires when an existing task has been deleted. |
+| `taskAdded` | The detail contains the respective `task` object | Fires when a new task has been created. |
+| `taskChanged` | The detail contains the respective `task` object | Fires when task metadata has been changed, such as marking completed. |
+| `taskClick` | The detail contains the respective `task` object | Fires when the user clicks or taps on a task. |
+| `taskRemoved` | The detail contains the respective `task` object | Fires when an existing task has been deleted. |
+
+For more information about handling events, see [events](../customize-components/events.md).
 
 ## Templates
 

concepts/toolkit/components/teams-channel-picker.md

@@ -72,9 +72,12 @@ mgt-teams-channel-picker {
 ```
 
 ## Events
+
 | Event | Detail | Description |
 | --- | --- | --- |
-| selectionChanged | The detail contains the currently selected item  of `{channel : `[MicrosoftGraph.Channel](/graph/api/resources/channel)`, team: `[MicrosoftGraph.Team](/graph/api/resources/team)`}` | Fired when user makes a change in selection of a channel. |
+| `selectionChanged` | The detail contains the currently selected item  of `{channel : `[MicrosoftGraph.Channel](/graph/api/resources/channel)`, team: `[MicrosoftGraph.Team](/graph/api/resources/team)`}` | Fired when user makes a change in selection of a channel. |
+
+For more information about handling events, see [events](../customize-components/events.md).
 
 ## Templates
 

concepts/toolkit/components/todo.md

@@ -96,10 +96,12 @@ The following events are fired from the component.
 
 | Event | Detail | Description |
 | --- | --- | --- |
-| taskAdded | The detail contains the respective `task` object | Fires when a new task has been created. |
-| taskChanged | The detail contains the respective `task` object | Fires when task metadata has been changed, such as marking completed. |
-| taskClick | The detail contains the respective `task` object | Fires when the user clicks or taps on a task. |
-| taskRemoved | The detail contains the respective `task` object | Fires when an existing task has been deleted. |
+| `taskAdded` | The detail contains the respective `task` object | Fires when a new task has been created. |
+| `taskChanged` | The detail contains the respective `task` object | Fires when task metadata has been changed, such as marking completed. |
+| `taskClick` | The detail contains the respective `task` object | Fires when the user clicks or taps on a task. |
+| `taskRemoved` | The detail contains the respective `task` object | Fires when an existing task has been deleted. |
+
+For more information about handling events, see [events](../customize-components/events.md).
 
 ## Templates
 

concepts/toolkit/customize-components/events.md

@@ -0,0 +1,41 @@
+---
+title: "Handle events exposed by Microsoft Graph Toolkit components"
+description: "Many Microsoft Graph Toolkit components emit custom events. Attaching event handlers to these events allows you to respond to them and control the behavior of your app."
+localization_priority: Normal
+author: waldekmastykarz
+---
+
+# Handle events exposed by Microsoft Graph Toolkit components
+
+Many Microsoft Graph Toolkit components emit custom events. Attaching event handlers to these events allows you to respond to them and control the behavior of your app.
+
+## Discover which events components emit
+
+Each Microsoft Graph Toolkit component emits different events, specific to its functionality. To see the list of events emitted by the specific component, see the **Events** section of the documentation for that component.
+
+> [!IMPORTANT]
+> Some events, like `itemClick` in the File list component, are emitted only when using the default template. If you use a custom template, you overwrite the default rendering that is responsible for emitting the event.
+
+## Add event handlers to events
+
+Microsoft Graph Toolkit uses the standard [`EventTarget.dispatchEvent()`](https://developer.mozilla.org/docs/Web/API/EventTarget/dispatchEvent) function to emit custom events in its components. To attach an event handler to a custom event emitted by a toolkit's component, use the standard [`EventTarget.addEventListener()`](https://developer.mozilla.org/docs/Web/API/EventTarget/addEventListener) function.
+
+For example, to handle the `itemClick` event emitted by the File list component, add the following to your code.
+
+```javascript
+document.querySelector('mgt-file-list').addEventListener('itemClick' e => {
+  // your event handler code goes here
+});
+```
+
+### Access additional information exposed by the event
+
+Some events emitted by Microsoft Graph Toolkit contain additional information relevant to the event. For example, the `itemClick` event, emitted by the File list component, contains information about the file that was clicked in the file list. To see if the particular event contains additional information, see the **Events** section of the documentation for the corresponding component.
+
+You can access the additional information exposed by an event through the `details` property of the `event` object passed into your event handler, as shown in the following example.
+
+```javascript
+document.querySelector('mgt-file-list').addEventListener('itemClick', e => {
+  const clickedFile = e.details;
+});
+```