Servicio HTML: HTML basado en plantillas

Puedes usar plantillas para combinar código de Google Apps Script y HTML para crear páginas dinámicas con un mínimo esfuerzo. Si usaste lenguajes de plantillas que combinan código y HTML, como PHP, ASP o JSP, la sintaxis te resultará familiar.

Scriptlets

Las plantillas de Apps Script pueden contener tres etiquetas especiales llamadas scriptlets. Dentro de un scriptlet, puedes escribir cualquier código que funcione en un archivo normal de Apps Script: los scriptlets pueden llamar a funciones definidas en otros archivos de código, hacer referencia a variables globales o usar cualquiera de las APIs de Apps Script. Incluso puedes definir funciones y variables dentro de los scriptlets, con la advertencia de que las funciones definidas en archivos de código o en otras plantillas no pueden llamarlas.

Si pegas el siguiente ejemplo en el editor de secuencias de comandos, el contenido de la <?= ... ?> etiqueta (un scriptlet de impresión) aparecerá en cursiva. Este código se ejecuta en el servidor antes de que se entregue la página al usuario. Debido a que el código del scriptlet se ejecuta antes de que se entregue la página, solo se puede ejecutar una vez por página. A diferencia de las funciones de JavaScript o Apps Script del cliente que llamas a través de google.script.run, los scriptlets no se pueden volver a ejecutar después de que se carga la página.

Code.gs

function doGet() {
  return HtmlService
      .createTemplateFromFile('Index')
      .evaluate();
}

Index.html

<!DOCTYPE html>
<html>
  <head>
    <base target="_top">
  </head>
  <body>
    Hello, World! The time is <?= new Date() ?>.
  </body>
</html>

Ten en cuenta que la función doGet para HTML con plantilla difiere de los ejemplos para crear y entregar HTML básico. La función que se muestra aquí genera un HtmlTemplate objeto a partir del archivo HTML y, luego, llama a su método evaluate para ejecutar los scriptlets y convertir la plantilla en un objeto HtmlOutput que la secuencia de comandos puede entregar al usuario.

Scriptlets estándar

Los scriptlets estándar, que usan la sintaxis <? ... ?>, ejecutan código sin generar contenido de forma explícita en la página. Sin embargo, como se muestra en este ejemplo, el resultado del código dentro de un scriptlet aún puede afectar el contenido HTML fuera del scriptlet:

Code.gs

function doGet() {
  return HtmlService
      .createTemplateFromFile('Index')
      .evaluate();
}

Index.html

<!DOCTYPE html>
<html>
  <head>
    <base target="_top">
  </head>
  <body>
    <? if (true) { ?>
      <p>This is always served!</p>
    <? } else  { ?>
      <p>This is never served.</p>
    <? } ?>
  </body>
</html>

Los scriptlets de impresión, que usan la sintaxis <?= ... ?>, generan los resultados de su código en la página mediante el escape contextual.

El escape contextual significa que Apps Script realiza un seguimiento del contexto del resultado en la página (dentro de un atributo HTML, dentro de una etiqueta script del cliente o en cualquier otro lugar) y agrega automáticamente caracteres de escape para protegerse contra los ataques de secuencias de comandos entre sitios (XSS).

En este ejemplo, el primer scriptlet de impresión genera una cadena directamente; le sigue un scriptlet estándar que configura un array y un bucle, seguido de otro scriptlet de impresión para generar el contenido del array.

Code.gs

function doGet() {
  return HtmlService
      .createTemplateFromFile('Index')
      .evaluate();
}

Index.html

<!DOCTYPE html>
<html>
  <head>
    <base target="_top">
  </head>
  <body>
    <?= 'My favorite Google products:' ?>
    <? var data = ['Gmail', 'Docs', 'Android'];
      for (var i = 0; i < data.length; i++) { ?>
        <b><?= data[i] ?></b>
    <? } ?>
  </body>
</html>

Ten en cuenta que un scriptlet de impresión solo genera el valor de su primera instrucción; las instrucciones restantes se comportan como si estuvieran contenidas en un scriptlet estándar. Por ejemplo, el scriptlet <?= 'Hello, world!'; 'abc' ?> solo imprime "Hello, world!"

Scriptlets de impresión forzada

Los scriptlets de impresión forzada, que usan la sintaxis <?!= ... ?>, son como los scriptlets de impresión , excepto que evitan el escape contextual.

El escape contextual es importante si tu secuencia de comandos permite la entrada de usuarios no confiables. Por el contrario, deberás forzar la impresión si el resultado de tu scriptlet contiene intencionalmente HTML o secuencias de comandos que deseas insertar exactamente como se especificó.

Como regla general, usa scriptlets de impresión en lugar de scriptlets de impresión forzada, a menos que sepas que necesitas imprimir HTML o JavaScript sin cambios.

Código de Apps Script en scriptlets

Los scriptlets no se limitan a ejecutar JavaScript normal; también puedes usar cualquiera de las siguientes tres técnicas para darles a tus plantillas acceso a los datos de Apps Script.

Sin embargo, recuerda que, debido a que el código de la plantilla se ejecuta antes de que se entregue la página al usuario, estas técnicas solo pueden proporcionar contenido inicial a una página. Para acceder a los datos de Apps Script de una página de forma interactiva, usa la google.script.run API en su lugar.

Llama a funciones de Apps Script desde una plantilla

Los scriptlets pueden llamar a cualquier función definida en un archivo de código o biblioteca de Apps Script. En este ejemplo, se muestra una forma de extraer datos de una hoja de cálculo a una plantilla y, luego, crear una tabla HTML a partir de los datos.

Code.gs

function doGet() {
  return HtmlService
      .createTemplateFromFile('Index')
      .evaluate();
}

function getData() {
  return SpreadsheetApp
      .openById('1234567890abcdefghijklmnopqrstuvwxyz')
      .getActiveSheet()
      .getDataRange()
      .getValues();
}

Index.html

<!DOCTYPE html>
<html>
  <head>
    <base target="_top">
  </head>
  <body>
    <? var data = getData(); ?>
    <table>
      <? for (var i = 0; i < data.length; i++) { ?>
        <tr>
          <? for (var j = 0; j < data[i].length; j++) { ?>
            <td><?= data[i][j] ?></td>
          <? } ?>
        </tr>
      <? } ?>
    </table>
  </body>
</html>

Llama a las APIs de Apps Script directamente

También puedes usar el código de Apps Script directamente en los scriptlets. En este ejemplo, se logra el mismo resultado que en el ejemplo anterior cargando los datos en la plantilla en lugar de a través de una función separada.

Code.gs

function doGet() {
  return HtmlService
      .createTemplateFromFile('Index')
      .evaluate();
}

Index.html

<!DOCTYPE html>
<html>
  <head>
    <base target="_top">
  </head>
  <body>
    <? var data = SpreadsheetApp
        .openById('1234567890abcdefghijklmnopqrstuvwxyz')
        .getActiveSheet()
        .getDataRange()
        .getValues(); ?>
    <table>
      <? for (var i = 0; i < data.length; i++) { ?>
        <tr>
          <? for (var j = 0; j < data[i].length; j++) { ?>
            <td><?= data[i][j] ?></td>
          <? } ?>
        </tr>
      <? } ?>
    </table>
  </body>
</html>

Envía variables a plantillas

Por último, puedes enviar variables a una plantilla asignándolas como propiedades del HtmlTemplate objeto. Una vez más, este ejemplo logra el mismo resultado que los ejemplos anteriores.

Code.gs

function doGet() {
  var t = HtmlService.createTemplateFromFile('Index');
  t.data = SpreadsheetApp
      .openById('1234567890abcdefghijklmnopqrstuvwxyz')
      .getActiveSheet()
      .getDataRange()
      .getValues();
  return t.evaluate();
}

Index.html

<!DOCTYPE html>
<html>
  <head>
    <base target="_top">
  </head>
  <body>
    <table>
      <? for (var i = 0; i < data.length; i++) { ?>
        <tr>
          <? for (var j = 0; j < data[i].length; j++) { ?>
            <td><?= data[i][j] ?></td>
          <? } ?>
        </tr>
      <? } ?>
    </table>
  </body>
</html>

Depura plantillas

Las plantillas pueden ser difíciles de depurar porque el código que escribes no se ejecuta directamente. En cambio, el servidor transforma tu plantilla en código y, luego, ejecuta ese código resultante.

Si no es obvio cómo la plantilla interpreta tus scriptlets, dos métodos de depuración en la HtmlTemplate clase pueden ayudarte a comprender mejor lo que sucede.

La función getCode

La función getCode muestra una cadena que contiene el código que el servidor crea a partir de la plantilla. Si registras el código y, luego, lo pegas en el editor de secuencias de comandos, puedes ejecutarlo y depurarlo como el código normal de Apps Script.

Esta es la plantilla que muestra una lista de productos de Google nuevamente, seguida del resultado de getCode:

Code.gs

function myFunction() {
  Logger.log(HtmlService
      .createTemplateFromFile('Index')
      .getCode());
}

Index.html

<!DOCTYPE html>
<html>
  <head>
    <base target="_top">
  </head>
  <body>
    <?= 'My favorite Google products:' ?>
    <? var data = ['Gmail', 'Docs', 'Android'];
      for (var i = 0; i < data.length; i++) { ?>
        <b><?= data[i] ?></b>
    <? } ?>
  </body>
</html>

LOG (EVALUADO)

(function() { var output = HtmlService.initTemplate(); output._ =  '<!DOCTYPE html>\n';
  output._ =  '<html>\n' +
    '  <head>\n' +
    '    <base target=\"_top\">\n' +
    '  </head>\n' +
    '  <body>\n' +
    '    '; output._$ =  'My favorite Google products:' ;
  output._ =  '    ';  var data = ['Gmail', 'Docs', 'Android'];
        for (var i = 0; i < data.length; i++) { ;
  output._ =  '        <b>'; output._$ =  data[i] ; output._ =  '</b>\n';
  output._ =  '    ';  } ;
  output._ =  '  </body>\n';
  output._ =  '</html>';
  /* End of user code */
  return output.$out.append('');
})();

La función getCodeWithComments

La getCodeWithComments función es similar a getCode(), pero muestra el código evaluado como comentarios que aparecen uno al lado del otro con la plantilla original.

Revisa el código evaluado

Lo primero que notarás en cualquiera de las muestras de código evaluado es el objeto output implícito creado por el método HtmlService.initTemplate. Este método no está documentado porque solo las plantillas deben usarlo. output es un objeto HtmlOutput especial con dos propiedades con nombres inusuales, _ y _$, que son abreviaturas para llamar a append y appendUntrusted.

output tiene una propiedad especial más, $out, que hace referencia a un objeto HtmlOutput normal que no posee estas propiedades especiales. La plantilla muestra ese objeto normal al final del código.

Ahora que comprendes esta sintaxis, puedes seguir el resto del código. El contenido HTML fuera de los scriptlets (como la etiqueta b) se agrega con output._ = (sin escape contextual), y los scriptlets se agregan como JavaScript (con o sin escape contextual, según el tipo de scriptlet).

El código evaluado conserva los números de línea de la plantilla. Si recibes un error mientras ejecutas el código evaluado, la línea corresponde al contenido equivalente en la plantilla.

Jerarquía de comentarios

Debido a que el código evaluado conserva los números de línea, es posible que los comentarios dentro de los scriptlets comenten otros scriptlets e incluso código HTML. En estos ejemplos, se muestran algunos efectos sorprendentes de los comentarios:

<? var x; // a comment ?> This sentence won't print because a comment begins
inside a scriptlet on the same line.

<? var y; // ?> <?= "This sentence won't print because a comment begins inside
a scriptlet on the same line.";
output.append("This sentence prints because it's on the next line, even though
it's in the same scriptlet.") ?>

<? doSomething(); /* ?>
This entire block is commented out,
even if you add a */ in the HTML
or in a <script> */ </script> tag,
<? until you end the comment inside a scriptlet. */ ?>