{"id":4461,"date":"2020-04-22T11:14:08","date_gmt":"2020-04-22T18:14:08","guid":{"rendered":"https:\/\/officedevblogs.wpengine.com\/?p=4461"},"modified":"2020-04-22T11:14:08","modified_gmt":"2020-04-22T18:14:08","slug":"a-lap-around-microsoft-graph-toolkit-day-4-customizing-components","status":"publish","type":"post","link":"https:\/\/devblogs.microsoft.com\/microsoft365dev\/a-lap-around-microsoft-graph-toolkit-day-4-customizing-components\/","title":{"rendered":"A Lap around Microsoft Graph Toolkit Day 4 \u2013 Customizing Components"},"content":{"rendered":"

Updates (December 2020):<\/strong><\/p>\n

As of December 11th, 2020, the Microsoft Graph Toolkit team released version 2.0. You can now customize your components and apply dark theme by adding class=”mgt-dark”<\/strong> to your HTML. You can read more about this functionality here<\/a>.<\/p>\n

Author: <\/strong>Hugo Bernier, Microsoft Office Development MVP<\/p>\n

Welcome to Day 4 of the Microsoft Graph Toolkit blog series<\/a>!<\/span>\u00a0<\/span><\/p>\n

As\u00a0<\/span>you have<\/span>\u00a0seen in our previous blog\u00a0<\/span>posts,<\/span>\u00a0Microsoft Graph Toolkit is designed to make it easy to access and work with Microsoft Graph with a collection of framework-agnostic reusable web components.<\/span>\u00a0<\/span><\/p>\n

Not only are they easy to use, but they\u2019re also designed to look and feel as if they\u2019re out-of-the-box Microsoft\u00a0<\/span>365<\/span>\u00a0components.<\/span>\u00a0Your users will feel comfortable\u00a0<\/span>with\u00a0<\/span>the\u00a0<\/span>UI<\/span>\u00a0<\/span>components they already know and love.<\/span>\u00a0<\/span><\/p>\n

For example, these one of the images below is taken from SharePoint, while the other is using a custom\u00a0<\/span>web\u00a0<\/span>part\u00a0<\/span>using the Microsoft Graph Toolkit <mgt-person \/><\/span>\u00a0 component. Can you tell them apart? <\/span>\u00a0<\/span><\/p>\n

\"Alt-text:<\/p>\n

\"Alt-text:<\/p>\n

But what if you need to do something that doesn\u2019t look like \u201cout-of-the-box\u201d? What if you need your custom application to stand out?\u00a0Maybe you\u2019re integrating this experience into an existing application with your own established visual style?<\/p>\n

You\u2019re in for a treat then: the Microsoft Graph Toolkit components are easy to customize!<\/p>\n

In today\u2019s post, we\u2019ll show you how to customize the look and feel of the Microsoft Graph Toolkit components.<\/p>\n

Using the Microsoft Graph Toolkit Playground<\/h3>\n

The Microsoft Graph Toolkit Playground<\/a> is a great place to follow along with this post and start working with component customization. To use the playground, select a component from the list in the left navigation, then edit the HTML, JS, and\/or CSS panes on the right. As you make changes, you should see a preview of the results.<\/p>\n

Using Properties and Attributes<\/h3>\n

Most Microsoft Graph Toolkit components provide attributes and properties that you can use to change how the component will render.<\/p>\n

For example, you can use the <mgt-people\/><\/span>\u00a0 component default settings by simply using the HTML element as-is:<\/p>\n

<mgt-people><\/mgt-people><\/span>\u2026which will render the profile photos or initials of the first 3 people it finds, followed by a count indicating how many more people aren\u2019t shown in the list:<\/p>\n

\"mgt-people<\/p>\n

But if you can override the default settings. For example, if we wanted to show a maximum of 10 people, we\u2019d use the following HTML:<\/p>\n

<mgt-people show-max=\"10\"><\/mgt-people><\/pre>\n
\u2026which will render the following results:<\/p>\n
\"mgt-people<\/p>\n
The only thing I changed between the first and the second sample is that I set the show-max<\/strong> attribute to 10<\/strong>.<\/p>\n
Luckily, you don\u2019t have to guess which attributes are at your disposal, the Microsoft Graph Toolkit documentation<\/a> tells you which attributes are at your disposal with every control.<\/p>\n
For example, the <mgt-person\u00a0\/><\/span>\u00a0 component\u2019s default setting is to show only the person\u2019s photo or initials:<\/p>\n
<mgt-person\u00a0person-query=\"me\"><\/mgt-person><\/pre>\n
Which produces this:<\/p>\n
\"mgt-person<\/p>\n
But if you look at the attributes and properties<\/a> of the person component, you\u2019ll see that we can specify view=”twoLines”<\/strong> to change the default settings. So, this:<\/p>\n
<mgt-person person-query=\"me\" view=\"twoLines\"><\/mgt-person><\/pre>\n
\u2026will produce an image with the person\u2019s name and email address:<\/p>\n
\"mgt-person<\/p>\n
You can also dynamically change these settings using code. For example, the following HTML and JavaScript will produce the same results as above:<\/p>\n
HTML:<\/strong><\/p>\n
<mgt-person person-query=\"me\"><\/mgt-person>\n<\/pre>\n
JavaScript:<\/strong><\/p>\n
let person = document.querySelector('mgt-person');\nperson.view = \"twoLines\";<\/pre>\n
You may have noticed that when I changed the settings using HTML only, I used the HTML attribute<\/em>\u00a0view=”twoLines”<\/strong>, whereas in JavaScript, I used the view<\/b>\u00a0property. <\/em>You can control most components\u2019 settings by specifying the attributes in HTML, or the properties in JavaScript or both, depending on what you\u2019re trying to do.<\/p>\n
Again, each component\u2019s documentation page<\/a>\u00a0will give you the list of attributes and their matching properties, so you don\u2019t have to guess.<\/p>\n
Some components, like the <mgt-tasks \/><\/span>\u00a0 also expose more properties that don\u2019t have matching HTML attributes \u2013 partly because it wouldn\u2019t make sense to do so using HTML attributes.<\/p>\n
For example, using the <mgt-tasks \/><\/span>\u00a0 component, you can filter which tasks you wish to show:<\/p>\n
let taskView = document.querySelector('mgt-tasks');\ntaskView.taskFilter = task =>\n  task.appliedCategories.category1 === true\n  || task.appliedCategories.category2 === true\n  || task.appliedCategories.category3 === true;<\/pre>\n
Which will show you any task that belongs to category 1, 2, or 3 (See Try-It-Out sample here<\/a>), while the following code will show you only tasks that belong to categories 1, 2, and<\/strong> 3:<\/p>\n
let taskView = document.querySelector('mgt-tasks');\ntaskView.taskFilter = task =>\n  task.appliedCategories.category1 === true\n  && task.appliedCategories.category2 === true\n  && task.appliedCategories.category3 === true;<\/pre>\n
And if you wanted to filter any tasks where the title contains the word \u201cLaunch\u201d, you\u2019d use the following:<\/p>\n
let taskView = document.querySelector('mgt-tasks'); \ntaskView.taskFilter = task => task.title.indexOf('Launch') > -1;<\/pre>\n
Doing the same thing with HTML attributes would be exceedingly difficult to do. Trust me, I\u2019ve tried.<\/p>\n
Using Custom CSS Properties<\/h3>\n
So far, we\u2019ve used the attributes and properties to change the default settings of components. But what if you really want to change how the Microsoft Graph Toolkit components look, you can also use custom CSS properties. Most component expose custom CSS properties that you can override using plain old CSS to completely customize their looks. For example, you can use the <mgt-person\u00a0\/> component to show a standard profile card when you mouse over the name using the following HTML:<\/p>\n
<mgt-person\n  person-query=\"me\"\n  view=\"twoLines\"\n  person-card=\"hover\"><\/mgt-person><\/pre>\n
Which produces the following:<\/p>\n
\"mgt-person<\/p>\n
But if you add the following CSS to your page:<\/p>\n
mgt-person {\n  --person-card-display-name-font-size: 40px;\n  --person-card-display-name-color: #ffffff;\n  --person-card-title-font-size: 20px;\n  --person-card-title-color: #ffffff;\n  --person-card-subtitle-font-size: 10px;\n  --person-card-subtitle-color: #ffffff;\n  --person-card-details-title-font-size: 10px;\n  --person-card-details-title-color: #b3bf0a;\n  --person-card-details-item-font-size: 20px;\n  --person-card-details-item-color: #3abf0a;\n  --person-card-background-color: #000000;\n}<\/pre>\n
The same component will render the following:<\/p>\n
\"mgt-person<\/p>\n
These customizable styles are called CSS custom properties <\/em>because properties like –person-card-display-name-font-size don\u2019t exist in standard CSS \u2013 they\u2019re custom to the Microsoft Graph Toolkit component. (See this sample in Try-It-Out repo here<\/a>.)<\/p>\n
You can find the list of CSS custom properties on each component\u2019s respective documentation<\/a>.<\/p>\n
Using specific CSS<\/h3>\n
If you have multiple instances of a Microsoft Graph Toolkit component on a page and want to apply CSS custom properties on only one of them, you should use CSS selectors to control which instance will be modified.<\/p>\n
For example, let\u2019s pretend we have a bunch of person components on a page, as follows:<\/p>\n
<div class=\"team-list\">\n  <mgt-person class=\"first\" person-query=\"MeganB@M365x214355.onmicrosoft.com\" view=\"twoLines\"><\/mgt-person>\n  <mgt-person class=\"second\" person-query=\"IsaiahL@M365x214355.onmicrosoft.com\" view=\"twoLines\"><\/mgt-person>\n  <mgt-person class=\"third\" person-query=\"LynneR@M365x214355.onmicrosoft.com\" view=\"twoLines\"><\/mgt-person>\n  <mgt-person class=\"fourth\" person-query=\"bobk@tailspintoys.com\" view=\"twoLines\"l><\/mgt-person>\n  <mgt-person class=\"fifth\" person-query=\"alex@fineartschool.net\" view=\"twoLines\"><\/mgt-person>\n<\/div><\/pre>\n
If you define a CSS custom property as follows, you\u2019ll affect every persona control on the page:<\/p>\n
mgt-person {\n  --color: red;\n  --avatar-size: 72px;\n  --font-size: 24px;\n}\n<\/pre>\n
\"Five<\/p>\n
But if you use a CSS selector that is more specific, you can control which persona components are affected. For example, you could control individual styles by applying a custom CSS class name on each component and then applying the CSS custom properties on each component individually:<\/p>\n
mgt-person.first {\n  --color: red;\n\u00a0\u00a0--avatar-size: 72px;\n\u00a0\u00a0--font-size: 24px;\n}\n\nmgt-person.second {\n\u00a0\u00a0--color: green;\n\u00a0\u00a0--avatar-size: 72px;\n\u00a0\u00a0--font-size: 24px;\n}\n\nmgt-person.third {\n\u00a0\u00a0--color: orange;\n\u00a0\u00a0--avatar-size: 72px;\n\u00a0\u00a0--font-size: 24px;\n}\n\nmgt-person.fourth {\n\u00a0\u00a0--color: blue;\n\u00a0\u00a0--avatar-size: 72px;\n\u00a0\u00a0--font-size: 24px;\n}\n\nmgt-person.fifth {\n\u00a0\u00a0--color: purple;\n\u00a0\u00a0--avatar-size: 72px;\n\u00a0\u00a0--font-size: 24px;\n}<\/pre>\n
Which renders each component with a different style: (See this sample in Try-It-Out repo here<\/a>.)<\/p>\n
\"Five<\/p>\n
Putting it all together<\/h3>\n
You can combine all the techniques we discussed in today\u2019s post with along with regular HTML and CSS techniques to completely customize the look and feel of your components.<\/p>\n
For example, if you wanted to display the same list of team members so that it looks like a bunch of polaroids on a page, you could use the following custom CSS (inspired from this page<\/a>) :<\/p>\n
.team-list mgt-person {\n  --avatar-size: 72px;\n  --font-size: 24px;\n  width:300px;\n  padding: 12px;\n  transform: rotate(-2deg);\n  transition: -webkit-transform .15s linear;\n  box-shadow: 0 3px 6px rgba(0,0,0,.25);\n  background-color:white;\n  margin: 8px;\n}\n\n.team-list mgt-person:hover {\n  -webkit-transform: scale(1.25);\n  -moz-transform: scale(1.25);\n  position: relative;\n  z-index: 5;\n  box-shadow: 0 3px 6px rgba(0,0,0,.5);\n}\n\nmgt-person.second, mgt-person.fourth {\n  -webkit-transform: rotate(2deg);\n  -moz-transform: rotate(2deg);\n}\n\n\/* Don't rotate every third image, but offset its position *\/\nmgt-person.third {\n  -webkit-transform: none;\n  -moz-transform: none;\n  position: relative;\n  top: -5px;\n}\n\n\/* Rotate every fifth image by 5 degrees and offset it *\/\nmgt-person.fifth {\n  -webkit-transform: rotate(5deg);\n  -moz-transform: rotate(5deg);\n  position: relative;\n  right: 5px;\n}\n<\/pre>\n
Which produces the following results:<\/p>\n
\"Five<\/p>\n
With a cool hover effect: (See this sample in Try-It-Out repo here<\/a>.)<\/p>\n
\"Five<\/p>\n
Conclusion<\/h3>\n
In this post, we\u2019ve shown you how you can use attributes and properties to change the default settings of Microsoft Graph Toolkit components.<\/p>\n
You should use attributes within your HTML, and properties within your code.<\/p>\n
To completely change the look of a component, you can use the CSS custom properties within your CSS file (or <styles\/> element).<\/p>\n
But you can customize the components even more! In our next blog post, we\u2019ll show you how you can use templating to override the content inside of a component.<\/p>\n
Stay tuned for the next blog<\/a> in our series<\/a>! We will show you how to utilize templates to further customize toolkit component.<\/p>\n
 <\/p>\n","protected":false},"excerpt":{"rendered":"
In day 4 of A Lap around Microsoft Graph Toolkit, we will show you how to use attributes, properties, and CSS properties to customize the functionality and appearance of components. A cool demo of how to create a display of your team members that it looks like a bunch of polaroids!<\/p>\n","protected":false},"author":69077,"featured_media":25159,"comment_status":"closed","ping_status":"closed","sticky":false,"template":"","format":"standard","meta":{"_acf_changed":false,"footnotes":""},"categories":[3],"tags":[34],"class_list":["post-4461","post","type-post","status-publish","format-standard","has-post-thumbnail","hentry","category-microsoft-graph","tag-microsoft-graph-toolkit"],"acf":[],"blog_post_summary":"
In day 4 of A Lap around Microsoft Graph Toolkit, we will show you how to use attributes, properties, and CSS properties to customize the functionality and appearance of components. A cool demo of how to create a display of your team members that it looks like a bunch of polaroids!<\/p>\n","_links":{"self":[{"href":"https:\/\/devblogs.microsoft.com\/microsoft365dev\/wp-json\/wp\/v2\/posts\/4461","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/devblogs.microsoft.com\/microsoft365dev\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/devblogs.microsoft.com\/microsoft365dev\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/microsoft365dev\/wp-json\/wp\/v2\/users\/69077"}],"replies":[{"embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/microsoft365dev\/wp-json\/wp\/v2\/comments?post=4461"}],"version-history":[{"count":0,"href":"https:\/\/devblogs.microsoft.com\/microsoft365dev\/wp-json\/wp\/v2\/posts\/4461\/revisions"}],"wp:featuredmedia":[{"embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/microsoft365dev\/wp-json\/wp\/v2\/media\/25159"}],"wp:attachment":[{"href":"https:\/\/devblogs.microsoft.com\/microsoft365dev\/wp-json\/wp\/v2\/media?parent=4461"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/microsoft365dev\/wp-json\/wp\/v2\/categories?post=4461"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/microsoft365dev\/wp-json\/wp\/v2\/tags?post=4461"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}