Modelos no Microsoft Graph Toolkit

A maioria dos componentes do Microsoft Graph Toolkit suporta o uso de modelos personalizados para modificar o conteúdo de um componente.

Todos os componentes da web oferecem suporte a modelos com base no <template> elemento. Por exemplo, para substituir o modelo de um componente, adicione um <template> elemento dentro de um componente.

<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>

Se você estiver usando os componentes do React do Microsoft Graph Toolkit, poderá usar o React para criar modelos. Para obter detalhes, consulte Usar o kit de ferramentas com o React.

Tipo de dados

Cada componente pode ter várias partes que podem ser modeladas. Por exemplo, no mgt-agenda componente, você pode modelar eventos individuais, cabeçalhos de seção individuais, exibição de carregamento, nenhuma exibição de dados e muito mais. Para indicar o modelo, use o data-type atributo em um modelo. Por exemplo, para usar o mgt-agendamodelo de cada evento no , use o event tipo de dados, como mostrado.

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

Se no data-type for especificado, todo o componente será substituído pelo modelo. Você também pode usar data-type="default" para a mesma finalidade.

Dados de associação

Muitos modelos permitem a associação de dados que são passados para o modelo como contexto de dados. Por exemplo, o event modelo no mgt-agenda componente passa um {event} objeto que pode ser usado diretamente no modelo. Para expandir uma expressão, como event.subject, use as chaves duplas.

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

Esse formato também pode ser usado dentro de atributos:

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

Observação: Você também pode expandir objetos como {{event}} ou {{this}} e eles serão renderizados como cadeias de caracteres JSON. Isso pode ser útil quando você está desenvolvendo os modelos.

Alterar a sintaxe de associação

Por padrão, para expandir uma expressão, você usa chaves duplas ( {{expression}} ). No entanto, você pode alterar essa sintaxe para ambientes em que a sintaxe de colchete duplo já é usada. Por exemplo, o exemplo a seguir usa colchetes duplos ( [[expression]] ).

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

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

Propriedades da Ajuda de Contexto de Dados

As propriedades a seguir também podem ser usadas com o objeto de contexto de dados em seus modelos.

O exemplo a seguir mostra como usar a $index propriedade em um loop 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>

{{isso}}

Para ajudar a depurar o contexto de dados, você pode usar this em suas expressões de associação. A forma mais simples é adicionar {{this}} em qualquer lugar do seu modelo.

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

Como você pode usar JavaScript console em suas expressões de associação, você também tem acesso ao objeto que permite usar console.log(this) (ou qualquer outra console API) em seus modelos.

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

Renderização condicional

Talvez você só queira renderizar elementos quando uma condição for verdadeira ou falsa com base no contexto de dados. Os data-if atributos and data-else podem avaliar uma expressão e renderizar somente se verdadeiro ou falso.

<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>

Looping

Haverá casos em que o objeto de contexto de dados conterá loop e você precisará fazer um loop sobre os dados. Para esse cenário, use o data-for atributo.

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

Contexto do modelo

Em cenários em que você precisa converter dados em suas associações, associar a eventos ou apenas usar dados externos em suas vinculações de modelos, os modelos dão suporte à vinculação ao contexto de dados externos. Você pode adicionar contexto de modelo adicional de duas maneiras:

1. Diretamente no componente.

   Cada componente define a templateContext propriedade, que você pode usar para passar dados adicionais para qualquer modelo no componente.

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

   As propriedades no templateContext objeto agora estarão disponíveis para serem usadas nas expressões de associação no modelo.

2. Globalmente para todos os componentes.

   A TemplateHelper classe expõe o globalContext objeto para adicionar dados ou funções que devem estar disponíveis globalmente para todos os componentes.

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

Conversores

Em muitos casos, talvez você queira transformar os dados antes de apresentá-los no modelo. Por exemplo, talvez você queira formatar adequadamente uma data antes de renderizá-la. Nesses casos, você pode usar um conversor de modelos.

Para usar um conversor de modelos, primeiro você precisa definir uma função que fará a conversão. Por exemplo, você pode definir uma função para converter um objeto de evento em um intervalo de tempo formatado.

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

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

    return timeRange;
  }

}

Para usar o conversor em seu modelo, use-o como se você usaria uma função em code-behind.

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

Associação de evento ou propriedade

O data-props atributo permite que você adicione um ouvinte de eventos ou defina um valor de propriedade diretamente em seus modelos.

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

As propriedades de dados aceitam uma cadeia de caracteres delimitada por vírgula para cada propriedade ou manipulador de eventos que você deseja definir.

Para adicionar um manipulador de eventos, prefixe o nome do evento com @. O manipulador de eventos precisará estar disponível no templateContext do elemento.

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

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

}

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

Os argumentos de evento, o contexto de dados e o elemento raiz do modelo são passados para o manipulador de eventos como parâmetros.

Evento renderizado pelo modelo

Em certos casos, talvez você queira obter uma referência ao elemento rendered. Isso pode ser útil se você quiser lidar com a renderização do conteúdo por conta própria ou modificar o elemento renderizado.

Nesse cenário, você pode usar o templateRendered evento, que é acionado depois que o modelo é renderizado.

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

Os detalhes do evento conterão uma referência ao elemento que está sendo renderizado, ao objeto de contexto de dados e ao tipo do modelo.

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', () => {});
  }
});

Estilo

Os modelos podem ser estilizados normalmente via CSS, pois são renderizados fora do shadow dom.