Plantillas en microsoft Graph Toolkit

La mayoría de Graph Toolkit microsoft 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 plantillas de creación. Para obtener más información, consulte Use the toolkit with React.

Tipo de datos

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

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

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

Datos de enlace

Muchas plantillas permiten el enlace de datos que se pasan a la plantilla como contexto de datos. Por ejemplo, la event plantilla del componente mgt-agenda 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}} se representarán como cadenas JSON. Esto puede ser útil al desarrollar las plantillas.

Cambiar sintaxis de enlace

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

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

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

Propiedades auxiliares de contexto de datos

Las siguientes propiedades 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 hace un bucle con data-for.
$parent	Si una plantilla se representa dentro de otra plantilla, esta propiedad le permite tener acceso al contexto de datos primario.

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>

{{this}}

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

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

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

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

Representación condicional

Es posible que solo desee representar elementos cuando una condición es true o false en función del contexto de datos. Los data-if atributos and 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 los datos en bucle. 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 externos. Puede agregar contexto de plantilla adicional de dos maneras:

1. 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 objeto templateContext ahora estarán disponibles para usarse en las expresiones de enlace de la plantilla.

2. Globalmente para todos los componentes.

   La TemplateHelper clase expone el objeto globalContext 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 presentarlo en la plantilla. Por ejemplo, es posible que desee 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>

Los datos props aceptan una cadena delimitada por comas para cada propiedad o controlador de eventos que desee establecer.

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

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

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

}

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

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

Evento representado de plantilla

En algunos 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 evento templateRendered , que se dispara después de representar la plantilla.

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

Los detalles del evento contendrán una referencia al elemento que se está representando, 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 crear con estilo normalmente a través de CSS, ya que se representan fuera del dom de sombra.