SDK de plantillas de tarjetas adaptables

Artículo
08/28/2023

Los SDK de plantillas de tarjetas adaptables simplifican el proceso de rellenar una plantilla de tarjeta con datos reales en cualquier plataforma compatible.

Sigue leyendo para obtener una introducción a las plantillas de tarjetas adaptables.

Importante

Cambios importantes en la versión candidata para lanzamiento de mayo de 2020

Nos hemos estado esforzando para poder publicar las plantillas y, finalmente, ya nos encontramos en la recta final. Tuvimos que realizar algunos cambios menores importantes antes de completar la versión.

Cambios importantes de mayo de 2020

La sintaxis de enlace se cambió de {...} a ${...}.
- Por ejemplo, "text": "Hello {name}" se convierte en "text": "Hello ${name}".
La API de JavaScript ya no contiene un objeto EvaluationContext. Basta con pasar los datos a la función expand. Consulta la página del SDK para obtener la información completa.
La API de .NET se ha rediseñado para coincidir más estrechamente con la API de JavaScript. A continuación, encontrarás todos los detalles.

JavaScript

La biblioteca adaptivecards-templating está disponible en npm y a través de CDN. Consulta el vínculo del paquete para ver la documentación completa.

npm

npm install adaptivecards-templating

CDN

<script src="https://unpkg.com/adaptivecards-templating/dist/adaptivecards-templating.min.js"></script>

Uso

En el ejemplo siguiente, se supone que también has instalado la biblioteca adaptivecards para representar la tarjeta.

Si no tienes previsto representar la tarjeta, puedes quitar el código de parse y render.

import * as ACData from "adaptivecards-templating";
import * as AdaptiveCards from "adaptivecards";
 
// Define a template payload
var templatePayload = {
    "type": "AdaptiveCard",
    "version": "1.0",
    "body": [
        {
            "type": "TextBlock",
            "text": "Hello ${name}!"
        }
    ]
};
 
// Create a Template instance from the template payload
var template = new ACData.Template(templatePayload);
 
// Expand the template with your `$root` data object.
// This binds it to the data and produces the final Adaptive Card payload
var cardPayload = template.expand({
   $root: {
      name: "Matt Hidinger"
   }
});
 
// OPTIONAL: Render the card (requires that the adaptivecards library be loaded)
var adaptiveCard = new AdaptiveCards.AdaptiveCard();
adaptiveCard.parse(cardPayload);
document.getElementById('exampleDiv').appendChild(adaptiveCard.render());

.NET

dotnet add package AdaptiveCards.Templating

Uso

// Import the library 
using AdaptiveCards.Templating;

var templateJson = @"
{
    ""type"": ""AdaptiveCard"",
    ""version"": ""1.2"",
    ""body"": [
        {
            ""type"": ""TextBlock"",
            ""text"": ""Hello ${name}!""
        }
    ]
}";

// Create a Template instance from the template payload
AdaptiveCardTemplate template = new AdaptiveCardTemplate(templateJson);

// You can use any serializable object as your data
var myData = new
{
    Name = "Matt Hidinger"
};

// "Expand" the template - this generates the final Adaptive Card payload
string cardJson = template.Expand(myData);

Funciones personalizadas

Las funciones personalizadas se pueden agregar a la biblioteca de expresiones adaptables además de a las funciones precompiladas.

En el ejemplo siguiente, se agrega la función personalizada stringFormat y se usa para dar formato a una cadena.

string jsonTemplate = @"{
    ""type"": ""AdaptiveCard"",
    ""version"": ""1.0"",
    ""body"": [{
        ""type"": ""TextBlock"",
        ""text"": ""${stringFormat(strings.myName, person.firstName, person.lastName)}""
    }]
}";

string jsonData = @"{
    ""strings"": {
        ""myName"": ""My name is {0} {1}""
    },
    ""person"": {
        ""firstName"": ""Andrew"",
        ""lastName"": ""Leader""
    }
}";

AdaptiveCardTemplate template = new AdaptiveCardTemplate(jsonTemplate);

var context = new EvaluationContext
{
    Root = jsonData
};

// a custom function is added
AdaptiveExpressions.Expression.Functions.Add("stringFormat", (args) =>
{
    string formattedString = "";

    // argument is packed in sequential order as defined in the template
    // For example, suppose we have "${stringFormat(strings.myName, person.firstName, person.lastName)}"
    // args will have following entries
    // args[0]: strings.myName
    // args[1]: person.firstName
    // args[2]: strings.lastName
    if (args[0] != null && args[1] != null && args[2] != null) 
    {
        string formatString = args[0];
        string[] stringArguments = {args[1], args[2] };
        formattedString = string.Format(formatString, stringArguments);
    }
    return formattedString;
});

string cardJson = template.Expand(context);

Solución de problemas

P. ¿Por qué obtengo una excepción AdaptiveTemplateException al llamar a expand()?
A. Si el mensaje de error tiene un aspecto similar a "<elemento incorrecto>" en la línea, el valor "<número de línea>" tiene un formato incorrecto para "$data : ' pair".
Asegúrese de que el valor proporcionado para "$data" sea un valor de JSON válido, como un número, un booleano, un objeto y una matriz, o que siga la sintaxis correcta para el lenguaje de las plantillas adaptables, y que la entrada exista en el contexto de datos en el número de línea.

P. ¿Por qué obtengo una excepción ArgumentNullException al llamar a expand()?
A. Si el mensaje de error es similar a "Check if parent data context is set, or please enter a non-null value for '<offending item>' at line, '<line number>'" (Compruebe si el contexto de datos primario está establecido o escriba un valor que no sea nulo para el valor "" de la línea "").
Indica que no existe el contexto de datos del enlace de datos solicitado. Asegúrate de que el contexto de datos raíz esté establecido (en caso de que exista) y de que todos los contextos de datos estén disponibles para el enlace actual según lo indique el número de línea.

P. ¿Por qué la fecha y hora en formato RFC 3389, por ejemplo, "2017-02-14T06:08:00Z", cuando se usa con una plantilla no funciona con las funciones de fecha y hora?
A. La versión de NuGet 1.0.0-RC.0 del SDK de .NET presenta este comportamiento. Este comportamiento se ha corregido en las versiones posteriores. El comportamiento predeterminado del deserializador json.Net cambiaba la cadena de formato de fecha y hora y se ha deshabilitado para las versiones posteriores. Utilice la función formatDateTime() para dar formato a la cadena de fecha y hora en RFC 3389 como puede ver en este ejemplo, o bien omita las funciones de fecha y hora y simplemente use formatDateTime(). Para obtener más información sobre formatDateTime (), vaya aquí.

Compartir a través de