Planner component in Microsoft Graph Toolkit
The Planner component enables the user to view, add, remove, complete, or edit tasks from Microsoft Planner.
In addition, a user is able to assign a single or multiple Microsoft Graph users to a task. For more information about Microsoft Graph assignments, see plannerAssignments.
Important
With the release of @microsoft/mgt-components version 4, the planner component replaces the old task component and no longer supports using Outlook Tasks as a data source.
Example
The following example displays the signed-in user's Microsoft Planner tasks using the mgt-planner component. You can use the code editor to see how properties change the behavior of the component.
Properties
| Attribute | Property | Description |
|---|---|---|
| read-only | readOnly | A Boolean to set the task interface to be read only (no adding or removing tasks). Default is false. |
| hide-header | hideHeader | A Boolean to show or hide the header of the component. Default is false. |
| hide-options | hideOptions | A Boolean to show or hide the options in tasks. Default is false. |
| initial-id="planner_id/folder_id" | initialId | A string ID to set the initially displayed plan to the provided ID. |
| initial-bucket-id="bucket_id" | initialBucketId | A string ID to set the initially displayed bucket to the provided ID. |
| target-id="planner_id/folder_id" | targetId | A string ID to lock the tasks interface to the provided plan ID. |
| target-bucket-id="bucket_id" | targetBucketId | A string ID to lock the tasks interface to the provided bucket ID. |
| group-id | groupId | A string ID to lock the tasks interface to the group ID. |
| - | isNewTaskVisible | Determines whether new task view is visible at render. |
| - | taskFilter | An optional function to filter which tasks are shown to the user. |
The following example shows only tasks from Planner with ID 12345 and doesn't allow the user to create new tasks.
<mgt-planner read-only initial-id="12345"></mgt-planner>
The following example shows how to filter tasks that have only category3 set.
let taskView = document.querySelector("mgt-planner");
taskView.taskFilter = (task) => task.appliedCategories.category3 === true;
Custom CSS variables
<mgt-planner class="tasks"></mgt-planner>
.tasks {
--tasks-header-padding: 28px 14px;
--tasks-header-margin: 0 14px;
--tasks-header-font-size: large;
--tasks-header-font-weight: 800;
--tasks-header-text-color: blue;
--tasks-header-text-hover-color: gray;
--tasks-new-button-width: 300px;
--tasks-new-button-height: 50px;
--tasks-new-button-text-color: orange;
--tasks-new-button-text-font-weight: 400;
--tasks-new-button-background: black;
--tasks-new-button-border: 2px dotted golden;
--tasks-new-button-background-hover: gray;
--tasks-new-button-background-active: red;
--task-add-new-button-width: 60px;
--task-add-new-button-height: 35px;
--task-add-new-button-text-color: orange;
--task-add-new-button-text-font-weight: 400;
--task-add-new-button-background: black;
--task-add-new-button-border: 2px dotted white;
--task-add-new-button-background-hover: gray;
--task-add-new-button-background-active: red;
--task-cancel-new-button-width: 60px;
--task-cancel-new-button-height: 35px;
--task-cancel-new-button-text-color: yellow;
--task-cancel-new-button-text-font-weight: 400;
--task-cancel-new-button-background: red;
--task-cancel-new-button-border: 2px dashed white;
--task-cancel-new-button-background-hover: brown;
--task-cancel-new-button-background-active: red;
--task-complete-checkbox-background-color: red;
--task-complete-checkbox-text-color: yellow;
--task-incomplete-checkbox-background-color: orange;
--task-incomplete-checkbox-background-hover-color: yellow;
--task-title-text-font-size: large;
--task-title-text-font-weight: 500;
--task-complete-title-text-color: green;
--task-incomplete-title-text-color: purple;
--task-icons-width: 32px;
--task-icons-height: 32px;
--task-icons-background-color: purple;
--task-icons-text-font-color: black;
--task-icons-text-font-size: 16px;
--task-icons-text-font-weight: 400;
--task-complete-background-color: powderblue;
--task-incomplete-background-color: salmon;
--task-complete-border: 2px dashed green;
--task-incomplete-border: 2px double red;
--task-complete-border-radius: 8px;
--task-incomplete-border-radius: 12px;
--task-complete-padding: 8px;
--task-incomplete-padding: 12px;
--tasks-gap: 8px;
--tasks-background-color: violet;
--tasks-border: 2px dashed green;
--tasks-border-radius: 12px;
--tasks-padding: 16px;
/** affects the date picker and the text-input field **/
--task-new-input-border: 2px solid green;
--task-new-input-border-radius: 8px;
--task-new-input-background-color: yellow;
--task-new-input-hover-background-color: yellowgreen;
--task-new-input-placeholder-color: black;
/** affects the date picker and the text-input field **/
--task-new-dropdown-border: 2px solid green;
--task-new-dropdown-border-radius: 8px;
--task-new-dropdown-background-color: yellow;
--task-new-dropdown-hover-background-color: yellowgreen;
--task-new-dropdown-placeholder-color: red;
--task-new-dropdown-option-text-color: blue;
--task-new-dropdown-list-background-color: yellow;
--task-new-dropdown-option-hover-background-color: yellowgreen;
--task-new-person-icon-text-color: blue;
--task-new-person-icon-color: blue;
/** affects the options menu */
--dot-options-menu-background-color: yellow;
--dot-options-menu-shadow-color: yellow;
--dot-options-menu-item-color: maroon;
--dot-options-menu-item-hover-background-color: white;
}
To learn more, see styling components.
Events
| Event | When is it emitted | Custom data | Cancelable | Bubbles | Works with custom template |
|---|---|---|---|---|---|
taskAdded |
Fires when a new task is created | Newly created plannerTask | No | No | Yes |
taskChanged |
Fires when task metadata is changed, such as marking completed | Updated a plannerTask | No | No | No |
taskClick |
Fires when the user selects a task | task property with the selected plannerTask |
No | No | No |
taskRemoved |
Fires when an existing task is deleted | task property with the selected plannerTask |
No | No | No |
For more information about handling events, see events.
Templates
The planner component supports several templates that allow you to replace certain parts of the component. To specify a template, include a <template> element inside a component and set the data-type property to one of the following values:
| Data type | Data context | Description |
|---|---|---|
| task | task: a planner task object | replaces the whole default task. |
| task-details | task: a planner task object | template replaces the details section of the task. |
The following example defines a template for the planner component.
<mgt-planner>
<template data-type="task-details">
<div>Owner: {{task.owner}}</div>
<div>Importance Level: {{task.importance}}</div>
</template>
</mgt-planner>
Microsoft Graph permissions
This control uses the following Microsoft Graph APIs and permissions. For each API called, the user must have at least one of the listed permissions.
| Configuration | Permission | API |
|---|---|---|
| in all configurations | User.Read, User.ReadWrite | /me |
| default behavior | Tasks.Read, Group.Read.All, Tasks.ReadWrite, Group.ReadWrite.All | /me/planner/plans, /planner/plans/${planId}/buckets, /planner/buckets/${bucketId}/tasks |
groupId set |
Tasks.Read, Group.Read.All, Tasks.ReadWrite, Group.ReadWrite.All | /groups/${group-id}/planner/plans, /planner/plans/${planId}/buckets, /planner/buckets/${bucketId}/tasks |
targetId set |
Tasks.Read, Group.Read.All, Tasks.ReadWrite, Group.ReadWrite.All | /planner/plans/${planId}, /planner/plans/${planId}/buckets, /planner/buckets/${bucketId}/tasks |
| create, update, or delete task | Tasks.ReadWrite, Group.ReadWrite.All | POST /planner/tasks, PATCH /planner/tasks/${taskId}, DELETE /planner/tasks/${taskId} |
Subcomponents
The mgt-tasks component consists of one or more subcomponents that might require other permissions than the ones listed previously. For more information, see the documentation for each subcomponent:
Authentication
The tasks component uses the global authentication provider described in the authentication documentation.
Cache
The mgt-tasks component doesn't cache any data.
Localization
The control exposes the following variables that can be localized. For details about localization, see Localizing components.
| String name | Default value |
|---|---|
| removeTaskSubtitle | Delete Task |
| cancelNewTaskSubtitle | Cancel |
| newTaskPlaceholder | Adding a task... |
| addTaskButtonSubtitle | Add |
| due | Due |
| addTaskDate | Add the task date |
| assign | Assign |
| planNotFound | Plan not found |
| plansSelfAssigned | All Plans |
| bucketNotFound | Bucket not found |
| bucketsSelfAssigned | All Tasks |
| baseSelfAssigned | Assigned to Me |