Modèles dans le Kit de ressources Microsoft Graph

La plupart des composants du Kit de ressources Microsoft Graph prennent en charge l’utilisation de modèles personnalisés pour modifier le contenu d’un composant.

Tous les composants web prennent en charge les modèles basés sur l’élément <template> . Par exemple, pour remplacer le modèle d’un composant, ajoutez un <template> élément à l’intérieur d’un composant.

<mgt-agenda>
  <template data-type="event">
      <div>{{event.subject}}</div>
      <div data-for='attendee in event.attendees'>
          <mgt-person person-query="{{attendee.emailAddress.name}}">
            <template>
              <div data-if="person.image">
                <img src="{{person.image}}" />
              </div>
              <div data-else>
                {{person.displayName}}
              </div>
            </template>
          </mgt-person>
      </div>
  </template>
</mgt-agenda>

Si vous utilisez les composants microsoft Graph Toolkit React, vous pouvez utiliser React pour créer des modèles. Pour plus d’informations, consultez Utiliser le kit de ressources avec React.

Type de données

Chaque composant peut avoir plusieurs parties qui peuvent être modèles. Par exemple, dans le composant, vous pouvez créer des mgt-agenda modèles d’événements individuels, d’en-têtes de section individuels, de vue de chargement, d’aucune vue de données, etc. Pour indiquer le modèle, utilisez l’attribut data-type sur un modèle. Par exemple, pour créer un modèle pour chaque événement dans , mgt-agendautilisez le event type de données, comme indiqué.

<mgt-agenda>
  <template data-type="event"> </template>
</mgt-agenda>

Si aucun n’est data-type spécifié, l’intégralité du composant est remplacée par le modèle. Vous pouvez également utiliser data-type="default" dans le même but.

Liaison de données

De nombreux modèles autorisent la liaison de données qui sont passées au modèle en tant que contexte de données. Par exemple, le event modèle dans le mgt-agenda composant transmet un {event} objet qui peut être utilisé directement dans le modèle. Pour développer une expression, telle que event.subject, utilisez les accolades doubles.

<template data-type="event">
  <div>{{event.subject}}</div>
</template>

Ce format peut également être utilisé dans les attributs :

<template data-type="event">
  <a href="{{ event.onlineMeetingUrl }}" />
</template>

Note: Vous pouvez également développer des objets tels que {{event}} ou {{this}} et ils seront affichés sous forme de chaînes JSON. Cela peut être utile lorsque vous développez les modèles.

Modifier la syntaxe de liaison

Par défaut, pour développer une expression, vous utilisez des accolades doubles ( {{expression}} ). Toutefois, vous pouvez modifier cette syntaxe pour les environnements où la syntaxe entre accolades doubles est déjà utilisée. Par exemple, l’exemple suivant utilise des crochets doubles ( [[expression]] ).

import { TemplateHelper } from '@microsoft/mgt';

TemplateHelper.setBindingSyntax('[[', ']]');

Propriétés d’assistance du contexte de données

Les propriétés suivantes peuvent également être utilisées avec l’objet de contexte de données dans vos modèles.

Propriété	Description
$index	Index numérique de l’élément en cours de rendu lors d’une boucle avec data-for.
$parent	Si un modèle est affiché à l’intérieur d’un autre modèle, cette propriété vous permet d’accéder au contexte de données parent.

L’exemple suivant montre comment utiliser la $index propriété dans une boucle data-for.

<mgt-person>
  <mgt-person-card>
    <template data-type="additional-details">
      <span data-for="language in languages">
        {{ language.displayName }}<span data-if="$index < languages.length - 1">, </span>
      </span>
    </template>
  </mgt-person-card>
</mgt-person>

{{this}}

Pour faciliter le débogage du contexte de données, vous pouvez utiliser this dans vos expressions de liaison. Le formulaire le plus simple consiste à ajouter {{this}} n’importe où dans votre modèle.

<template data-type="event">
  <div>
    {{this}}
  </div>
</template>

Étant donné que vous pouvez utiliser JavaScript dans vos expressions de liaison, vous avez également accès à l’objet console qui vous permet d’utiliser console.log(this) (ou toute autre console API) dans vos modèles.

<template data-type="event">
  <div>
    {{console.log(this)}}
  </div>
</template>

Rendu conditionnel

Vous souhaiterez peut-être afficher des éléments uniquement lorsqu’une condition est true ou false en fonction du contexte de données. Les data-if attributs et data-else peuvent évaluer une expression et ne sont affichés que si la valeur est true ou false.

<mgt-person person-query="john doe">
  <template>
    <div data-if="person.image">
      <img src="{{ person.image }}" />
    </div>
    <div data-else>
      {{ person.displayName }}
    </div>
  </template>
</mgt-person>

Boucle

Dans certains cas, l’objet de contexte de données contient une boucle et vous devez effectuer une boucle sur les données. Pour ce scénario, utilisez l’attribut data-for .

<template data-type="event">
  <ul>
    <li data-for='attendee in event.attendees'>
      {{ attendee.displayName }}
    </li>
  </ul>
</template>

Contexte du modèle

Dans les scénarios où vous devez convertir des données dans vos liaisons, lier à des événements ou simplement utiliser des données externes dans vos liaisons de modèles, les modèles prennent en charge la liaison à un contexte de données externe. Vous pouvez ajouter un contexte de modèle supplémentaire de deux manières :

1. Directement sur le composant.

   Chaque composant définit la templateContext propriété , que vous pouvez utiliser pour passer des données supplémentaires à n’importe quel modèle dans le composant.

   document.querySelector('mgt-agenda').templateContext = {
   
     someObject: {},
     formatDate: (date: Date) => { /* format date and return */ },
     someEventHandler: (e) => { /* handleEvent */  }
   
   }
   

   Les propriétés de l’objet templateContext seront désormais disponibles pour être utilisées dans les expressions de liaison dans le modèle.

2. Globalement pour tous les composants.

   La TemplateHelper classe expose l’objet globalContext pour ajouter des données ou des fonctions qui doivent être globalement disponibles pour tous les composants.

   import { TemplateHelper } from '@microsoft/mgt';
   
   TemplateHelper.globalContext.someObject = {};
   TemplateHelper.globalContext.formatDate = (date: Date) => { /* format date and return */ };
   TemplateHelper.globalContext.someEventHandler = (e) => { /* handleEvent */  }
   

Convertisseurs

Dans de nombreux cas, vous pouvez transformer les données avant de les présenter dans le modèle. Par exemple, vous souhaiterez peut-être mettre en forme correctement une date avant qu’elle ne soit rendue. Dans ce cas, vous pouvez utiliser un convertisseur de modèle.

Pour utiliser un convertisseur de modèle, vous devez d’abord définir une fonction qui effectuera la conversion. Par exemple, vous pouvez définir une fonction pour convertir un objet d’événement en intervalle de temps mis en forme.

document.querySelector('mgt-agenda').templateContext = {

  getTimeRange: (event) => {
    // TODO: format a string from the event object as you wish
    // timeRange = ...

    return timeRange;
  }

}

Pour utiliser le convertisseur dans votre modèle, utilisez-le comme si vous utilisiez une fonction dans code behind.

<template data-type="event">
  <div>{{ getTimeRange(event) }}</div>
</template>

Liaison d’événement ou de propriété

L’attribut data-props vous permet d’ajouter un écouteur d’événements ou de définir une valeur de propriété directement dans vos modèles.

<template>
    <button data-props="{{@click: myEvent, myProp: value}}"></button>
</template>

Data-props accepte une chaîne délimitée par des virgules pour chaque propriété ou gestionnaire d’événements que vous souhaiterez peut-être définir.

Pour ajouter un gestionnaire d’événements, préfixez le nom de l’événement avec @. Le gestionnaire d’événements doit être disponible dans le templateContext de l’élément .

document.querySelector('mgt-agenda').templateContext = {

  someEventHandler: (e, context, root) => { /* handleEvent */  }

}

<template>
    <button data-props="{{@click: someEventHandler}}"></button>
</template>

Les arguments d’événement, le contexte de données et l’élément racine du modèle sont passés au gestionnaire d’événements en tant que paramètres.

Événement rendu par modèle

Dans certains cas, vous souhaiterez peut-être obtenir une référence à l’élément rendu. Cela peut être utile si vous souhaitez gérer le rendu du contenu vous-même ou modifier l’élément rendu.

Dans ce scénario, vous pouvez utiliser l’événement templateRendered , qui se déclenche après le rendu du modèle.

let agenda = document.querySelector('mgt-agenda');
agenda.addEventListener('templateRendered', (e) => { });

Les détails de l’événement contiennent une référence à l’élément en cours de rendu, à l’objet de contexte de données et au type du modèle.

agenda.addEventListener('templateRendered', (e) => {
  let templateType = e.detail.templateType;
  let dataContext = e.detail.context;
  let element = e.detail.element;

  if (templateType === 'event') {
    element.querySelector('.some-button').addEventListener('click', () => {});
  }
});

Style

Les modèles peuvent être stylés normalement via CSS, car ils sont affichés en dehors du dom d’ombre.