You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: packages/mgt-components/README.md
+179-1Lines changed: 179 additions & 1 deletion
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -41,7 +41,7 @@ The components can be used on their own, but they are at their best when they ar
41
41
```html
42
42
<script type="module">
43
43
import {Providers} from '@microsoft/mgt-element';
44
-
import {MsalProvider} from '@microsoft/mgt-msal-provider';
44
+
import {Msal2Provider} from '@microsoft/mgt-msal2-provider';
45
45
46
46
// import the components
47
47
import '@microsoft/mgt-components';
@@ -55,6 +55,184 @@ The components can be used on their own, but they are at their best when they ar
55
55
<mgt-agenda group-by-day></mgt-agenda>
56
56
```
57
57
58
+
59
+
## <a id="disambiguation">Disambiguation</a>
60
+
61
+
MGT is built using [web components](https://developer.mozilla.org/en-US/docs/Web/Web_Components). Web components use their tag name as a unique key when registering within a browser. Any attempt to register a component using a previously registered tag name results in an error being thrown when calling `CustomElementRegistry.define()`. In scenarios where multiple custom applications can be loaded into a single page this created issues forMGT, most notablyin developing solutions using SharePoint Framework.
62
+
63
+
To mitigate this challenge we built the [`mgt-spfx`](https://github.com/microsoftgraph/microsoft-graph-toolkit/tree/main/packages/mgt-spfx) package. Using `mgt-spfx` developers can centralize the registration of MGT web components across all SPFx solutions deployed on the tenant. By reusing MGT components from a central location web parts from different solutions can be loaded into a single page without throwing errors. When using `mgt-spfx` all MGT based web parts in a SharePoint tenant use the same version of MGT.
64
+
65
+
To allow developers to build web parts using the latest version of MGT and load them on pages along with web parts that use v2.x of MGT, we've added a new disambiguation feature to MGT. Using this feature developers can specify a unique string to add to the tag name of all MGT web components in their application.
66
+
67
+
### Usage in standard HTML and JavaScript
68
+
69
+
The earlier example can be updated to use the disambiguation feature as follows:
70
+
71
+
```html
72
+
<script type="module">
73
+
import { Providers, customElementHelper } from '@microsoft/mgt-element';
74
+
import { Msal2Provider } from '@microsoft/mgt-msal2-provider';
> Note: the `import` of `mgt-components` must use a dynamic import to ensure that the disambiguation is applied before the components are imported.
91
+
92
+
To simplify this pattern when developing SharePoint Framework web parts we have provided helper utilities in the [`mgt-spfx-utils`](https://github.com/microsoftgraph/microsoft-graph-toolkit/tree/main/packages/mgt-spfx-utils) package. Example usages are provided below.
93
+
94
+
### Usage in a SharePoint web part with no framework
95
+
96
+
The `importMgtComponentsLibrary` helper function wraps a dynamic import of the `@microsoft/mgt-components` library.
97
+
98
+
A more complete example is available in the [No Framework Web Part Sample](https://github.com/microsoftgraph/microsoft-graph-toolkit/blob/main/samples/sp-mgt/src/webparts/helloWorld/HelloWorldWebPart.ts).
99
+
100
+
```ts
101
+
import { BaseClientSideWebPart } from '@microsoft/sp-webpart-base';
102
+
import { Providers } from '@microsoft/mgt-element';
103
+
import { SharePointProvider } from '@microsoft/mgt-sharepoint-provider';
104
+
import { customElementHelper } from '@microsoft/mgt-element/dist/es6/components/customElementHelper';
105
+
import { importMgtComponentsLibrary } from '@microsoft/mgt-spfx-utils';
106
+
107
+
export default class MgtWebPart extends BaseClientSideWebPart<Record<string, unknown>> {
108
+
private _hasImportedMgtScripts = false;
109
+
private _errorMessage = '';
110
+
111
+
protected onInit(): Promise<void> {
112
+
if (!Providers.globalProvider) {
113
+
Providers.globalProvider = new SharePointProvider(this.context);
The `lazyLoadComponent` helper function leverages `React.lazy` and `React.Suspense` to asynchronously load the components which have a direct dependency on `@microsoft/mgt-react` from the top level web part component.
157
+
158
+
A complete example is available in the [React SharePoint Web Part Sample](https://github.com/microsoftgraph/microsoft-graph-toolkit/blob/main/samples/sp-webpart/src/webparts/mgtDemo/MgtDemoWebPart.ts).
159
+
160
+
```ts
161
+
// [...] trimmed for brevity
162
+
import { Providers } from '@microsoft/mgt-element/dist/es6/providers/Providers';
163
+
import { customElementHelper } from '@microsoft/mgt-element/dist/es6/components/customElementHelper';
164
+
import { SharePointProvider } from '@microsoft/mgt-sharepoint-provider/dist/es6/SharePointProvider';
165
+
import { lazyLoadComponent } from '@microsoft/mgt-spfx-utils';
166
+
167
+
// Async import of a component that uses the @microsoft/mgt-react Components
// set the disambiguation before initializing any webpart
174
+
customElementHelper.withDisambiguation('bar');
175
+
176
+
export default class MgtDemoWebPart extends BaseClientSideWebPart<IMgtDemoWebPartProps> {
177
+
// set the global provider
178
+
protected async onInit() {
179
+
if (!Providers.globalProvider) {
180
+
Providers.globalProvider = new SharePointProvider(this.context);
181
+
}
182
+
}
183
+
184
+
public render(): void {
185
+
const element = lazyLoadComponent(MgtDemo, { description: this.properties.description });
186
+
187
+
ReactDom.render(element, this.domElement);
188
+
}
189
+
190
+
// [...] trimmed for brevity
191
+
}
192
+
```
193
+
194
+
### Dynamic imports aka Lazy Loading
195
+
196
+
Using dynamic imports you can load dependencies asynchronously. This pattern allows you to load dependencies only when needed. For example, you may want to load a component only when a user clicks a button. This is a great way to reduce the initial load time of your application. In the context of disambiguation, you need to use this technique because components register themselves in the browser when they are imported.
197
+
198
+
**Important:** If you import the components before you have applied the disambiguation, the disambiguation will not be applied and using the disambiguated tag name will not work.
199
+
200
+
When using an `import` statement the import statement is hoisted and executed before any other code in the code block. To use dynamic imports you must use the `import()` function. The `import()` function returns a promise that resolves to the module. You can also use the `then` method to execute code after the module is loaded and the `catch` method to handle any errors if necessary.
201
+
202
+
#### Example using dynamic imports
203
+
204
+
```typescript
205
+
// static import via a statement
206
+
import { Providers, customElementHelper } from '@microsoft/mgt-element';
207
+
import { Msal2Provider } from '@microsoft/mgt-msal2-provider';
Helper functions to simplify lazy loading of Microsoft Graph Toolkit components when using disambiguated web components in SharePoint Framework web parts. For more information on disambiguation in MGT see https://github.com/microsoftgraph/microsoft-graph-toolkit/tree/main/packages/mgt-components#disambiguation
8
+
9
+
## Installation
10
+
11
+
To lazy load Microsoft Graph Toolkit components from the library, add the `@microsoft/mgt-spfx-utils` package as a dependency to your SharePoint Framework project. If you use React, also add the `@microsoft/mgt-react` package:
Disambiguation is intended to provide developers with a mechanism to use a specific version of MGT in their solution without encountering collisions with other solutions that may be using MGT. `mgt-spfx` will allow all SPFx solutions in a tenant to use a single shared version, either v2.x or v3.x, of MGT. Currently multiple versions of `mgt-spfx` cannot be used in the same tenant. This is a limitation of the SharePoint Framework.
38
+
39
+
By disambiguating tag names of Microsoft Graph Toolkit components, you can use your own version of MGT rather than using the centrally deployed `@microsoft/mgt-spfx` package. This allows you to avoid colliding with SharePoint Framework components built by other developers. When disambiguating tag names, MGT is included in the generated SPFx bundle, increasing its size. It is strongly recommended that you use a disambiguation value unique to your organization and solution to avoid collisions with other solutions, e.g. `contoso-hr-extensions`.
40
+
41
+
> **Important:** Since a given web component tag can only be registered once these approaches **must** be used along with the `customElementHelper.withDisambiguation('foo')` approach as this allows developers to create disambiguated tag names.
42
+
43
+
### When using no framework web parts
44
+
45
+
When building SharePoint Framework web parts without a JavaScript framework the `@microsoft/mgt-components` library must be asynchronously loaded after configuring the disambiguation setting. The `importMgtComponentsLibrary` helper function wraps this functionality. Once the `@microsoft/mgt-components` library is loaded you can load components directly in your web part.
46
+
47
+
Below is a minimal example web part that demonstrates how to use MGT with disambiguation in SharePoint Framework Web parts. A more complete example is available in the [No Framework Web Part Sample](https://github.com/microsoftgraph/microsoft-graph-toolkit/blob/main/samples/sp-mgt/src/webparts/helloWorld/HelloWorldWebPart.ts).
When building SharePoint Framework web parts using React any component that imports from the `@microsoft/mgt-react` library must be asynchronously loaded after configuring the disambiguation setting. The `lazyLoadComponent` helper function exists to facilitate using `React.lazy` and `React.Suspense` to lazy load these components from the top level web part.
107
+
108
+
Below is a minimal example web part that demonstrates how to use MGT with disambiguation in React based SharePoint Framework Web parts. A complete example is available in the [React SharePoint Web Part Sample](https://github.com/microsoftgraph/microsoft-graph-toolkit/blob/main/samples/sp-webpart/src/webparts/mgtDemo/MgtDemoWebPart.ts).
const element =lazyLoadComponent(MgtDemo, { description: this.properties.description });
137
+
138
+
ReactDom.render(element, this.domElement);
139
+
}
140
+
141
+
// [...] trimmed for brevity
142
+
}
143
+
```
144
+
145
+
The underlying components can then use MGT components from the `@microsoft/mgt-react` package as usual. Because of the earlier setup steps the the MGT React components will render html using the disambiguated tag names:
0 commit comments