Components

All Microsoft Graph Toolkit components are Web Components. Because Web Components are a set of web standards supported by all major web browsers out of the box, the toolkit components have the benefit of being framework agnostic and work in any web app out of the box, regardless of what web framework is used.

The toolkit components are built on top of lit-element. If you are contributing to the toolkit, we recommend you read through the getting started guide for lit-element to get familiar with the basics of creating Web Components.

The Base Component

To simplify and unify common business logic for all mgt components, all components extend the MgtBaseComponent abstract class. This class extends LitElement and handles all of the magic of talking to the authentication providers and it exposes additional lifecycle methods the components can implement.

loadState

This method is called whenever a provider state changes. This method should be implemented in your class and used to fetch initial Microsoft Graph state - this method is where most of your Microsoft Graph calls will happen. Ex:

protected async loadState() {
    const provider = Providers.globalProvider;
    if (provider && provider.state === ProviderState.SignedIn) {
        // call graph and setup your state
    }
}

clearState

This method is called whenever a user logs out. This method should be implemented in your class and used to clear any user data/state. Ex

protected clearState(): void {
    this.data = null;
}

requestStateUpdate(force: boolean)

Call this method whenever you need to reload the Microsoft Graph state based on a property change. This method should be called instead of calling loadState directly because requestStateUpdate batches multiple requests and ensures the loadState method is not called multiple times. This method is mostly used in property setters.

For example, here is how it's used in the person component whenever the userId is changed:

@property({
    attribute: 'user-id'
})
public get userId(): string {
    return this._userId;
}
public set userId(value: string) {
    if (value === this._userId) {
        return;
    }

    this._userId = value;
    this.personDetails = null;
    this.requestStateUpdate();
}

fireCustomEvent(eventName: string, detail: any)

Use this method to fire any events from your components. Use the detail parameter to pass data through the event. Ex:

const data: DetailType = { event: clickedEvent }
this.fireCustomEvent('eventClick', data);

Make sure to document the event in the jsdoc above your class, including the type of any data passed, this ensures that the React wrapper library gets the typings for any event bindings correct. Ex:

/**
 * ...
 * @fires eventClick - {CustomEvent<DetailType>} Fired when user clicks an event
 * ...

React components

The toolkit auto-generates a React component by wrapping your web component and parsing its source. There are few things you should consider when building your component.

1. Properly document all methods and properties. Be specific with types.
2. When documenting MicrosoftGraph and MicrosoftGraphBeta types, use the format MicrosoftGraph.User or MicrosoftGraphBeta.Presence. This allows the generator to know what types to export from what package.
3. Document any events using the @fires jsdoc at the top of the class

The React components are generated whenever the toolkit is built using yarn build.