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 para crear plantillas. Para obtener más información, vea Use the toolkit with React.

Tipo de datos

Cada componente puede tener varias partes que se pueden plantillar. Por ejemplo, en el componente, puede crear una plantilla de eventos individuales, encabezados de sección individuales, vista de mgt-agenda 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-agenda el , use el tipo de event 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 data-type="default" para 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 pasa un objeto que se puede usar directamente en la mgt-agenda {event} 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 this en las expresiones de enlace. El formulario más sencillo es agregar en {{this}} cualquier lugar 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 objeto que le permite usar (o cualquier otra console console.log(this) console 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 pueden evaluar una expresión y data-else 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 propiedad, que puede usar para pasar datos templateContext 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 ahora estarán disponibles para templateContext usarse en las expresiones de enlace de la plantilla.

  2. Globalmente para todos los componentes.

    La clase expone el objeto para agregar datos o funciones que deben estar TemplateHelper globalContext 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, que se dispara después de templateRendered 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.