Plantillas

Las plantillas sirven para personalizar los mensajes que aparecen en las incursiones y los anuncios. De esta forma, se pueden añadir algunos datos que por defecto no se muestran, como el PC máximo o los tipos de los Pokémon, se puede cambiar la disposición de los elementos existentes, o se puede añadir una imagen personalizable.

Plantillas de texto

Existen dos plantillas completamente independientes: la plantilla de incursiones, que se cambia con /raidtemplate, y la de anuncios, que se cambia con /announcetemplate. Además, las incursiones pueden tener contenido después de la lista de apuntados, que se puede poner con /raidfootertemplate.

Al poner esos comandos sin argumentos, se muestra el código de la plantilla actual. Para cambiar una plantilla, se puede copiar y pegar ese código con las modificaciones deseadas. Por ejemplo:

/raidtemplate <b>{Pokemon}</b> Raid {{on <b>{weekday_day_month}</b> }}at {timewarn_icon_}<b>{raidtime}</b> in {gym_icon}{gym}<br>{{<em>Available from {opentime} to {endtime}</em><br>}}<em>Organized by </em>{organizer}{_edited_icon}{_refloated_icon}

Para volver a la plantilla por defecto, se debe poner un guión -, de la siguiente forma:

/raidtemplate -

⚠️ ¿Te resulta todo muy confuso? Comienza poniendo el comando /raidtemplate y mira la plantilla actual de incursiones. Copia, pégala y haz una pequeña modificación. Poco a poco, vete probando cosas nuevas.

Plantillas predefinidas

Además de la plantilla que viene por defecto, hay algunas plantillas predefinidas adicionales. Para utilizarlas, se debe especificar su nombre en lugar de poner la plantilla completa. Por ejemplo:

/raidtemplate maxcp
/announcetemplate maxcp

Las plantillas predefinidas disponibles son las siguientes:

Variables

En cualquier plantilla encontrarás texto entre corchetes {} que son variables que posteriormente se reemplazarán por los datos de las incursiones y los anuncios. Por ejemplo, {gym} se reemplaza por el nombre del gimnasio, con un enlace en caso de que se conozca la ubicación.

En esta lista se indican todas las variables disponibles. Algunas ya se utilizan en la plantilla por defecto o en alguna de las plantillas predefinidas, pero otras no. Por claridad, en la lista no aparecen los corchetes {}.

Formato con HTML

Las plantillas se pueden formatear con HTML sencillo, con las restricciones de Telegram habituales:

• Las etiquetas válidas son <i></i> (cursiva), <b></b> (negrita), <u></u> (subrayado), <s></s> (tachado), <code></code> (texto de ancho fijo) y <a href=""></a> (enlace).
• Si quieres que se vean los caracteres <, > y & se deben usar las entidades <, > y &.
• Se puede poner, por ejemplo, texto en negrita y subrayado al mismo tiempo, anidando las etiquetas correctamente. Es decir <u><b>bien</b></u> es correcto, pero <u><b>mal</u></b> no es correcto y no funcionará
• Los saltos de línea deben indicarse con <br>. Se pueden separar los elementos poniendo varios seguidos, por ejemplo <br><br>.

Recuerda que estás especificando código para la plantilla, y el formato que apliques directamente se ignorará. Es decir, si quieres que algo se muestre en negrita, debes ponerlo <b>de esta manera</b>, pero no utilizar la opción de negrita integrada en Telegram.

Variantes de las variables

Para ayudar a construir mejores mensajes hay versiones de las variables con espacios al principio, con espacios al final, en mayúsculas… Estas son las variantes disponibles:

• {VARIABLE}: contiene {variable} en mayúsculas.
• {Variable}: contiene {variable} forzando la primera letra mayúscula.
• {_variable}: contiene {variable} con un espacio al principio.
• {variable_}: contiene {variable} con un espacio al final.
• {_variable_}: contiene {variable} con un espacio al principio y al final.

Variantes de las variables con enlaces

Las variables que ponen Enlace en la columna HTML contienen enlaces. Es decir, {pokemon_gameinfo} se mostrará como el nombre del Pokémon con un enlace a Gameinfo.

Este tipo de variables se pueden descomponer para mostrar de manera independiente solo el texto, añadiendo _text al final, o solo la URL, añadiendo _link al final.

Por ejemplo, la variable {pokemon_gameinfo_text} contendrá el texto con el nombre del Pokémon y {pokemon_gameinfo_link} contendrá la URL.

Bloques condicionales

Hay dos tipos de bloques condicionales, que permiten mostrar o esconder porciones de las plantillas según la situación.

Bloque condicional simple

Este bloque condicional más simple se escribe simplemente así: {{texto {variables} y más texto }}.

En este caso, el contenido entre llaves dobles se mostrará únicamente si todas las variables que se utilizan dentro están definidas o son verdaderas.

Hay varios ejemplos de este tipo de bloque en la plantilla por defecto, donde solo se muestra una porción de texto si está definida la variable weekday_day_month y otro si están definidas opentime y endtime.

Bloque condicional con condiciones

El otro tipo de bloque conditional permite usar condiciones complejas y se escribe así: [condiciones]{{texto {variables} y más texto}}.

En este caso, el contenido entre llaves dobles se mostrará únicamente si las condiciones definidas entre [] resultan verdaderas. No importa si las variables dentro de las llaves dobles {{}} no están definidas o son falsas, el contenido se muestra igualmente.

Las condiciones pueden ser simplemente variables como opentime o isegg. También pueden negarse poniendo una ! delante. Por ejemplo:

[opentime]{{<em>Abre entre {opentime} y {endtime}</em><br>}}
[!isegg]{{🐒 Incursión de <b>{pokemon_kingcasualbot} ({maxcp}/{maxcp_boosted})}}

Dentro de las condiciones pueden usarse comparadores matemáticos habituales: menor que <, mayor que >, igual que ==, diferente que !=, menor o igual que <= y mayor o igual que >=. Pueden usarse para comparar valores de variables contra valores arbitrarios, por ejemplo:

[opentime>20:00]{{🌚 ¡¡Ten cuidado, que se hace de noche!}}
[minutestoend<5]{{⛔️ ¡¡Hay muy poco tiempo para hacer la incursión, ponla un poco antes!!}}
[tier==ex]{{🎟 '¡Recuerda que necesitas un pase especial para poder hacer la incursión, no te apuntes si no lo tienes!}}

También pueden usarse las conjunciones lógicas: and && y or ||. De esta forma puden unirse varias condiciones para hacer una más compleja, por ejemplo:

[isegg && minutesfromstart<10]{{<em>🥚🚫 Pueden salir varios Pokémon y has puesto la hora muy cerca de la hora de eclosión. Si puedes, cambia la hora para un poco para más tarde.}}
[raidispending && trainerscount_remote > 5]{{⛔️💌 <u>¡Prohibido invitar a nadie que no esté apuntado!</u> }}

En caso de usar más de dos condiciones y mezclar && y ||, ten en cuenta que siempre se evalúan de izquierda a derecha y este orden de evaluación no puede alterarse.

Variables específicas para usar en los bloques condicionales

Todas las variables descritas en la tabla anterior pueden usarse como condiciones. En caso de que tengan un valor definido, la condición será verdadera. En caso de que no tengan un valor definido, la condición será falsa.

Además, hay algunas variables especialmente indicadas para utilizar como condiciones, que no imprimen nada aunque sean verdaderas:

Plantillas de imagen

Las plantillas de imagen permiten añadir imágenes a las incursiones, que se pueden personalizar con información de cada incursión. Están desactivadas por defecto. Para activarlas o cambiarlas por otras, se utiliza el comando /imagetemplate. Por ejemplo, para utilizar la plantilla default:

/imagetemplate default

Para ver las plantillas disponibles o descargar la plantilla actual, utiliza /imagetemplate sin parámetros. Para dejar de usar plantillas de imagen, utiliza el parámetro -, es decir:

/imagetemplate -

Las plantillas de imagen también se pueden personalizar. Son archivos SVG con un tamaño de entre 600x300 píxeles y 600x400 píxeles. Dentro, contienen elementos de texto e imágenes que son interpretados y reemplazados por el bot por los datos reales de la incursión o el anuncio. Se recomienda utilizar Inkscape para editarlas (es necesario un ordenador con Linux, Windows o Mac).

Para comenzar a utilizar una plantilla personalizada, se debe enviar el archivo SVG de la plantilla al grupo, poniendo /imagetemplate en la descripción.

Puedes empezar una plantilla de cero, pero lo más sencillo es comenzar cogiendo una plantilla preexistente y modificarla. Con el comando /imagetemplate puedes descargar la plantilla de imagen actual y hacer modificaciones para después usarla como plantilla personalizada.

Si abres una plantilla, las imágenes enlazadas se mostrarán con un error al no existir el archivo referenciado (lee debajo la sección sobre imágenes). Para evitar esto, puedes descargar este pack de imágenes y descomprimirlo en el mismo directorio donde tengas la plantilla, lo que facilitará la edición al hacerte una mejor idea de cómo quedan las imágenes mientras editas.

Para interpretar los elementos de la plantilla se utilizan las propiedades id, class y algunas propiedades que comienzan por data-, específicas para cada caso. Para poder ver y editar estas propiedades necesitas activar el editor XML de Inkscape. Habilítalo en el menú Editar » Visor XML….

Reemplazos en los elementos de texto

Los elementos de texto pueden interpretarse, como si fueran plantillas de texto normales. No se pueden utilizar condicionales de ningún tipo. Para que un elemento de texto se interprete, debe tener un class llamado parsetext.

Ten en cuenta que en las imágenes no se puede utilizar HTML, por lo que las variables que contienen enlaces mostrarán el código HTML. Por ejemplo, la variable {gym}. Para evitar que se muestre el código HTML, puedes usar la variante de sólo texto, es decir, {gym_text}.

Condicionales

Se pueden mostrar y esconder elementos completos utilizando los condicionales. Para que se interpreten los condicionales de un elemento, debe tener un class llamado parseconditions.

Las condiciones deben ponerse como valor de un atributo llamado data-conditions. Pueden usarse todas las condiciones descritas en la sección de plantillas de texto, como por ejemplo isegg && minutestoend<10.

Imágenes

En un archivo SVG se pueden incrustar (embed) imágenes o enlazar (link) imágenes externas. Si arrastras un archivo de imagen a Inkscape, debes decirle cuál de las dos cosas quieres hacer. Si quieres incluir una imagen propia (por ejemplo, una imagen de fondo, o el logotipo del grupo), querrás incrustarla. Por el contrario, si quieres que la imagen se sustituya por una de las disponibles en el bot, debes enlazarla.

El bot puede sustituir imágenes enlazadas para mostrar los Pokémon, los tipos de los Pokémon y algunas cosas más. Para especificar por qué imagen se desea sustituir, hay que especificar el identificador correcto en el atributio id, según la siguiente tabla:

Si se define una imagen enlazada con uno de estos id y la imagen no existe, se esconde automáticamente. Por ejemplo, si el Pokémon solo tiene un tipo pero se utilizan imágenes que hagan referencia al segundo tipo. Las imágenes enlazadas que no tengan ninguno de estos ids serán ignoradas y mostrarán errores en la plantilla.

Posición y tamaño del texto

Los elementos de texto se pueden reposicionar verticalmente o cambiar su tamaño en función de la longitud de su texto, para ayudar a acomodar el texto en las plantillas. Acomodar texto de longitud variable es complicado, y usando estas técnicas es difícil conseguir un resultado perfecto al utilizar tipos de letra de ancho variable, pero con un poco de prueba y error se pueden obtener buenos resultados.

Para cambiar el tamaño del tipo de letra en función de la longitud del texto, el elemento debe tener un class llamado resizetext. Se puede especificar la longitud a partir de la cual se va a redimensionar poniendo la longitud como valor de un atributo llamado data-resizetext-length y el tamaño deseado en data-resizetext-size. El tamaño debe especificarse con unidades y se aplicará en la propiedad CSS font-size. Por ejemplo:

class: resizetext
data-resizetext-length: 30
data-resizetext-size: 8px

Para cambiar la posición vertical del texto en función de su longitud, el elemento debe tener un class llamado movetext. Se puede especificar la longitud a partir de la cual se va a reposicionar el texto poniendo la longitud como valor de un atributo llamado data-movetext-length y el tamaño deseado en data-movetext-distance. La distancia debe especificarse sin unidades y se aplicará como el atributo y del elemento. Por ejemplo:

class: movetext
data-movetext-length: 25
data-movetext-distance: -5

Imágenes de gimnasio

Para que funcionen las imágenes de gimnasio, es necesario que el grupo tenga definida una hoja de cálculo y los gimnasios estén cargados. Una vez esté eso hecho, hay que obtener las imágenes y enviarlas por el grupo dentro de un archivo ZIP poniendo en el comentario el comando /gymimages.

Las imágenes deben estar en formato JPEG y llamarse tal cual está puesto el nombre del gimnasio (primera columna) en la hoja de cálculo, con la extensión .jpg o .jpeg al final. Además, cada imagen no puede superar los 300kB de tamaño y el archivo ZIP no puede superar los 5MB. El archivo ZIP no debe contener subdirectorios: las imágenes deben estar todas en el directorio principal. Se procesan un máximo de 300 archivos, por lo que si tienes más gimnasios en tu grupo, tendrás que limitarte a 300 de ellos.

Las imágenes recibidas solo se aceptan si hay un gimnasio cargado previamente con ese nombre. Una vez aceptadas, se redimensionan y se cortan a un cuadrado centrado de 250x250 píxeles, independientemente del formato de imagen original.

Si se quiere subir más imágenes más tarde, hay que volver a enviarlas todas ya que, cada vez que se recibe un nuevo archivo ZIP, primero se borran todas las anteriores.

Limitaciones

Al contrario que ocurre con las plantillas de texto, las plantillas de imagen no se refrescan cada vez que se actualiza el mensaje, tan solo se actualizan cuando cambian datos básicos de la incursión, como: el Pokémon, hora, gimnasio, etc. Es por eso que en la plantilla de imagen no se deberían usar variables y condicionales que hagan referencia al número de entrenadores inscritos, ya que la imagen no se va a actualizar adecuadamente.

Los tipos de letra que pueden utilizarse son todos los incluidos en esta colección de Google Fonts. Si utilizas tipos de letra no soportados, se verán de manera incorrecta. Para solucionar esto, puedes convertir esos textos a paths. Esto no puede hacerse si pretendes que se interpreten variables dentro del texto, ya que al convertirlos a paths dejan de comportarse como textos.

Los ids de los elementos no pueden repetirse, por lo que al usar el atributo id para especificar el tipo de imagen, no se puede poner la misma imagen enlazada dos veces en la misma plantilla. Para solucionar esto, puedes añadir barras bajas _ al final y el bot lo entenderá igual. Es decir, pokemon_img_ y pokemon_img__ funcionan igual que pokemon_img.

Los mensajes con imagen tardan más en generarse, y según la carga del servidor esto puede significar problemas. Debes intentar utilizar plantillas lo más sencillas posible y, si incrustas imágenes, comprimirlas antes en un tamaño adecuado. Las plantillas de más de 400 elementos o de 2MB de tamaño son rechazadas automáticamente.

Los mensajes con imagen en Telegram tienen un máximo de 1024 caracteres, mientras que los mensajes normales tienen un máximo de 4096 caracteres. Con unas plantillas de texto no muy excesivas y un máximo de 20 apuntados por incursión no debería haber problema, pero si no limitas los apuntados en tu grupo o pones grandes textos en las plantillas, podrías alcanzar ese límite y la incursión dejaría de funcionar. Puedes copiar y pegar el texto de una incursión con muchos apuntados en alguna herramienta como charactercountonline.com para ver el número de caracteres que utilizas habitualmente. Ten en cuenta que, si pones información en la imagen, normalmente no querrás tenerla duplicada también en texto, por lo que puedes eliminar la información duplicada de las plantillas de texto para ahorrar caracteres.

Probar las plantillas

Para facilitar el desarrollo de plantillas, se pueden enviar los archivos SVG de las plantillas junto con la descripción /testimagetemplate para probarlas por privado (no en un grupo). El bot renderizará la plantilla en varias situaciones diferentes para que puedas comprobar cómo queda y corregir errores.