Plantillas del kit de herramientas de Microsoft Graph

Article
03/26/2023

La mayoría de los componentes de Microsoft Graph Toolkit admiten el uso de plantillas personalizadas para modificar el contenido de un componente.

Todos los componentes web admiten plantillas basadas en el <template> elemento . Por ejemplo, para invalidar la plantilla de un componente, agregue un <template> elemento dentro de un 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>

Si usa los componentes de microsoft Graph Toolkit React, puede usar React para crear plantillas. Para obtener más información, consulte Uso del kit de herramientas con React.

Tipo de datos

Cada componente puede tener varias partes que se pueden crear como plantilla. Por ejemplo, en el mgt-agenda componente, puede crear plantillas de eventos individuales, encabezados de sección individuales, vista de carga, vista de datos, etc. Para indicar la plantilla, use el data-type atributo en una plantilla. Por ejemplo, para crear una plantilla de cada evento en mgt-agenda, use el event tipo de datos, como se muestra.

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

Si no se especifica ninguna data-type , todo el componente se reemplazará por la plantilla. También puede usar data-type="default" para el mismo propósito.

Enlace de datos

Muchas plantillas permiten el enlace de datos que se pasan a la plantilla como contexto de datos. Por ejemplo, la event plantilla del mgt-agenda componente pasa un {event} objeto que se puede usar directamente en la plantilla. Para expandir una expresión, como event.subject, use los corchetes dobles.

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

Este formato también se puede usar dentro de los atributos:

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

Nota: También puede expandir objetos como {{event}} o {{this}} y se representarán como cadenas JSON. Esto puede ser útil al desarrollar las plantillas.

Cambiar la sintaxis de enlace

De forma predeterminada, para expandir una expresión, se usan corchetes dobles ( {{expression}} ). Sin embargo, puede cambiar esta sintaxis para entornos en los que ya se usa la sintaxis de doble corchetes. Por ejemplo, en el ejemplo siguiente se usan corchetes dobles ( [[expression]] ).

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

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

Propiedades auxiliares del contexto de datos

Las propiedades siguientes también se pueden usar con el objeto de contexto de datos en las plantillas.

Propiedad	Descripción
$index	Índice numérico del elemento que se representa mientras se está en bucle con `data-for`.
$parent	Si una plantilla se representa dentro de otra plantilla, esta propiedad le permite acceder al contexto de datos primarios.

En el ejemplo siguiente se muestra cómo usar la $index propiedad en un bucle 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>

Para ayudar a depurar el contexto de datos, puede usar this en las expresiones de enlace. El formulario más sencillo es agregar {{this}} en cualquier parte de la plantilla.

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

Dado que puede usar JavaScript en las expresiones de enlace, también tiene acceso al console objeto que le permite usar console.log(this) (o cualquier otra console API) en las plantillas.

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

Representación condicional

Es posible que solo quiera representar elementos cuando una condición es true o false en función del contexto de datos. Los data-if atributos y data-else pueden evaluar una expresión y representarse solo si es true o 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>

Bucle

Habrá casos en los que el objeto de contexto de datos contenga un bucle y tendrá que recorrer en bucle los datos. Para este escenario, use el data-for atributo .

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

Contexto de plantilla

En escenarios en los que necesita convertir datos en los enlaces, enlazar a eventos o simplemente usar datos externos en los enlaces de plantillas, las plantillas admiten el enlace al contexto de datos externo. Puede agregar contexto de plantilla adicional de dos maneras:

Directamente en el componente.

Cada componente define la templateContext propiedad , que puede usar para pasar datos adicionales a cualquier plantilla del componente.
```
document.querySelector('mgt-agenda').templateContext = {

  someObject: {},
  formatDate: (date: Date) => { /* format date and return */ },
  someEventHandler: (e) => { /* handleEvent */  }

}
```
Las propiedades del templateContext objeto ahora estarán disponibles para usarse en las expresiones de enlace de la plantilla.

Globalmente para todos los componentes.

La TemplateHelper clase expone el globalContext objeto para agregar datos o funciones que deben estar disponibles globalmente para todos los componentes.

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

TemplateHelper.globalContext.someObject = {};
TemplateHelper.globalContext.formatDate = (date: Date) => { /* format date and return */ };
TemplateHelper.globalContext.someEventHandler = (e) => { /* handleEvent */  }

Convertidores

En muchos casos, es posible que desee transformar los datos antes de presentarlos en la plantilla. Por ejemplo, es posible que quiera dar el formato correcto a una fecha antes de que se represente. En estos casos, es posible que desee usar un convertidor de plantillas.

Para usar un convertidor de plantillas, primero debe definir una función que realizará la conversión. Por ejemplo, puede definir una función para convertir un objeto de evento en un intervalo de tiempo con formato.

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

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

    return timeRange;
  }

}

Para usar el convertidor en la plantilla, úselo como si usara una función en el código subyacente.

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

Enlace de eventos o propiedades

El data-props atributo permite agregar un agente de escucha de eventos o establecer un valor de propiedad directamente en las plantillas.

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

La propiedad data-props acepta una cadena delimitada por comas para cada propiedad o controlador de eventos que quiera establecer.

Para agregar un controlador de eventos, anteponga el nombre del evento a @. El controlador de eventos tendrá que estar disponible en el templateContext del elemento .

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

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

}

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

Los argumentos de evento, el contexto de datos y el elemento raíz de la plantilla se pasan al controlador de eventos como parámetros.

Evento representado por plantilla

En determinados casos, es posible que desee obtener una referencia al elemento representado. Esto puede ser útil si desea controlar la representación del contenido usted mismo o si desea modificar el elemento representado.

En este escenario, puede usar el templateRendered evento , que se desencadena después de que se haya representado la plantilla.

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

Los detalles del evento contendrá una referencia al elemento que se representa, el objeto de contexto de datos y el tipo de la plantilla.

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

Las plantillas se pueden aplicar estilo normalmente a través de CSS, ya que se representan fuera del dom de sombra.

Comparteix a través de