Modelos no Microsoft Graph Toolkit

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

Todos os componentes Web suportam 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 estiver a utilizar os componentes do Microsoft Graph Toolkit React, pode utilizar React para criar modelos. Para obter detalhes, consulte Utilizar o toolkit com React.

Tipo de dados

Cada componente pode ter várias partes que podem ser modelo. Por exemplo, no mgt-agenda componente, pode modelar eventos individuais, cabeçalhos de secção individuais, vista de carregamento, sem vista de dados e muito mais. Para indicar o modelo, utilize o data-type atributo num modelo. Por exemplo, para criar um modelo para cada evento no mgt-agenda, utilize o event tipo de dados, conforme mostrado.

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

Se não data-type for especificado nenhum, todo o componente será substituído pelo modelo. Também pode utilizar data-type="default" para o mesmo fim.

Vincular dados

Muitos modelos permitem o enlace de dados transmitidos ao modelo como contexto de dados. Por exemplo, o event modelo no mgt-agenda componente transmite um {event} objeto que pode ser utilizado diretamente no modelo. Para expandir uma expressão, como event.subject, utilize os parênteses duplos.

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

Este formato também pode ser utilizado dentro de atributos:

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

Nota: Também pode expandir objetos como {{event}} ou {{this}} e estes serão compostos como cadeias JSON. Isto pode ser útil quando estiver a desenvolver os modelos.

Alterar sintaxe de enlace

Por predefinição, para expandir uma expressão, utilize parênteses retos duplos ( {{expression}} ). No entanto, pode alterar esta sintaxe para ambientes em que a sintaxe do parêntese reto duplo já é utilizada. Por exemplo, o exemplo seguinte utiliza parênteses retos duplos ( [[expression]] ).

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

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

Propriedades do programa auxiliar de contexto de dados

As seguintes propriedades também podem ser utilizadas com o objeto de contexto de dados nos seus modelos.

O exemplo seguinte mostra como utilizar a $index propriedade num ciclo 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}}

Para ajudar a depurar o contexto de dados, pode utilizar this nas expressões de enlace. A forma mais simples é adicionar {{this}} em qualquer parte do seu modelo.

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

Uma vez que pode utilizar JavaScript nas expressões de enlace, também tem acesso ao console objeto que lhe permite utilizar console.log(this) (ou qualquer outra console API) nos seus modelos.

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

Composição condicional

Só poderá querer compor elementos quando uma condição for verdadeira ou falsa com base no contexto de dados. Os data-if atributos e data-else só podem avaliar uma expressão e compor se forem verdadeiros ou falsos.

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

Ciclos

Haverá casos em que o objeto de contexto de dados contém um ciclo e terá de repetir os dados. Neste cenário, utilize 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 precisa de converter dados nos seus enlaces, vincular a eventos ou apenas utilizar dados externos nos enlaces de modelos, os modelos suportam o enlace ao contexto de dados externos. Pode adicionar contexto de modelo adicional de duas formas:

1. Diretamente no componente.

   Cada componente define a templateContext propriedade, que pode utilizar para transmitir dados adicionais a 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 estarão agora disponíveis para serem utilizadas nas expressões de enlace 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 globalmente disponíveis 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, poderá querer transformar os dados antes de os apresentar no modelo. Por exemplo, poderá querer formatar corretamente uma data antes de ser composta. Nestes casos, poderá querer utilizar um conversor de modelos.

Para utilizar um conversor de modelos, primeiro tem de definir uma função que fará a conversão. Por exemplo, pode definir uma função para converter um objeto de evento num 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 utilizar o conversor no seu modelo, utilize-o como se utilizasse uma função no código subjacente.

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

Enlace de eventos ou propriedades

O data-props atributo permite-lhe adicionar um serviço de escuta de eventos ou definir um valor de propriedade diretamente nos seus modelos.

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

Os adereços de dados aceitam uma cadeia delimitada por vírgulas para cada processador de propriedades ou eventos que possa querer definir.

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

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

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

}

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

Os args de eventos, o contexto de dados e o elemento raiz do modelo são transmitidos ao processador de eventos como parâmetros.

Evento composto por modelo

Em determinados casos, poderá querer obter uma referência para o elemento composto. Isto pode ser útil se quiser processar a composição do conteúdo por si próprio ou se pretender modificar o elemento composto.

Neste cenário, pode utilizar o templateRendered evento, que é acionado após a composição do modelo.

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

Os detalhes do evento irão conter uma referência ao elemento que está a ser composto, 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 modelados normalmente através de CSS, uma vez que são compostos fora do dom sombra.