Templates

Templates are used to customize the messages that appear in raids and announcements. In this way, you can add some data that is not shown by default, such as the maximum CP or the types of the Pokémon, or you can also change the arrangement of the existing elements.

There are two completely independent templates: the raid template, which is changed with /raidtemplate, and the announcement template, which is changed with /announcetemplate. Also, raids can have content after the target list, which can be set with /raidfootertemplate.

By putting those commands without arguments, the current template code is displayed. To change a template, you can copy and paste that code with the desired modifications. For example:

/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}

To return to the default template, you must put a dash -, as follows:

/raidtemplate -

⚠️ Is everything very confusing? Start by putting the command /raidtemplate and look at the current raid template. Copy, paste it and make a little modification. Little by little, try new stuff.

Predefined templates

In addition to the default template, there are some additional predefined templates. To use them, you must specify their name instead of putting the complete template. For example:

/raidtemplate maxcp
/announcetemplate maxcp

The available predefined templates are:

Variables

In any template you will find text between brackets {} that are variables that will later be replaced by the data of the raids and announcements. For example, {gym} is replaced by the name of the gym, with a link if the location is known.

This list indicates all the available variables. Some are already used in the default template or in one of the predefined templates, but others are not. For clarity, the brackets {} do not appear in the list.

Format with HTML

Templates can be formatted with plain HTML, with the usual Telegram restrictions:

• Valid tags are <i></i> (italics), <b></b> (bold), <u></u> (underlined), <s></s> (crossed out), <code></code> (fixed-width text) and <a href=""></a>(link).
• If you want the characters <, > and & to be seen, the entities <, > and & must be used.
• You can put, for example, bold and underlined text at the same time, nesting the labels correctly. <u><b>Good</b></u> is correct, but <u><b>Bad</u></b> is wrong and will not work
• Line breaks should be indicated with <br>. You can separate the elements by putting several in a row, for example <br><br>.

Remember that you are specifying code for the template, and the format that you apply directly will be ignored. That is, if you want something to be shown in bold, you must put it <b>this way</b>, but not use the bold option integrated in Telegram.

Variants of variables

To help build better messages there are versions of the variables with spaces at the beginning, with spaces at the end, in capital letters… These are the available variants:

• {VARIABLE}: contains {variable} in uppercase.
• {Variable}: contains {variable} forcing the first capital letter.
• {_variable}: Contains {variable} with a leading space.
• {variable_}: contains {variable} with a space at the end.
• {_variable_}: contains {variable} with a space at the beginning and at the end.

Variants of variables with links

Variables that put Link in the HTML column contain links. That is, {pokemon_gameinfo} will be displayed as the name of the Pokémon with a link to Gameinfo.

This type of variable can be decomposed to independently display only the text, adding _text at the end, or just the URL, adding _link at the end.

For example, the variable {pokemon_gameinfo_text} will contain the text with the name of the Pokémon and {pokemon_gameinfo_link} will contain the URL.

Conditional blocks

There are two types of conditional blocks, which allow you to show or hide parts of the models depending on the situation.

Simple Conditional Block

The simplest conditional block is written like this: ` {{text {variables} and more text}}`.

In this case, the contents enclosed in square brackets will only be shown if all variables used inside are set or true.

There are several examples of this type of block in the default template, where only a part of the text is displayed if the variable weekday_day_month is set and another part if opentime and endtime are set.

Conditional block with conditions

The other type of conditional block allows you to use complex conditions and is written like this: [condiciones]{{text {variables} and more text}}.

In this case, the content between the tabs will be displayed as soon as the conditions defined between [] are true. It doesn’t matter if the variables inside the double braces {{}} are undefined or false, the content is still displayed.

Conditions can simply be variables like opentime or isegg. They can also refuse by putting one ! in front of. For example:

[opentime]{{<em>Open between {opentime} and {endtime}</em><br>}}
[!isegg]{{🐒 Raid of <b>{pokemon_kingcasualbot} ({maxcp}/{maxcp_boosted})}}

Within the conditions, common mathematical comparators can be used: less than <, greater than >, equal to ==, different than !=, Less than or equal to <= and greater than or equal to >=. They can be used to compare variable values ​​against arbitrary values, for example:

[opentime>20:00]{{🌚 Watch out!, night raid!}}
[minutestoend<5]{{⛔️ There is very little time to make the raid, put it a little earlier!!}}
[tier==ex]{{🎟' Remember that you need a special pass to be able to do the raid, do not sign up if you do not have it!}}

The logical conjunctions can also be used: and && and or ||. In this way, several conditions can be joined to make a more complex one, for example:

[isegg && minutesfromstart<10]{{<em>🥚🚫 Several Pokémon can come out and you have set the time very close to hatching time. If you can, change the time for a little later}}
[raidispending && trainerscount_remote > 5]{{⛔️💌 <u>It is forbidden to invite anyone who is not registered!</u> }}

In case of using more than two conditions and mixing && and ||, keep in mind that they are always evaluated from left to right and this order of evaluation cannot be altered.

Variables to use in conditional blocks

All the variables described in the table above can be used as conditions. In case they have a defined value, the condition will be true. In case they do not have a defined value, the condition will be false.

In addition, there are some variables specially indicated to use as conditions, which do not print anything even if they are true:

Images Templates

Image templates allow you to add images to raids, which can be customized with information from each raid. They are disabled by default. To activate them or change them to others, use the /imagetemplate command. For example, to use the default template:

/imagetemplate default

To see the available templates or download the current template, use /imagetemplate without parameters. To stop using image templates, use the - parameter, that is:

/imagetemplate -

Image templates can also be customized. They are SVG files with a size between 600x300 pixels and 600x400 pixels. Inside, they contain text and image elements that are interpreted and replaced by the bot with the actual data from the raid or announce. Inkscape is recommended for editing (requires a Linux, Windows, or Mac computer).

To start using a custom template, send the SVG file of the template to the group, putting /imagetemplate in the description.

You can start a template from scratch, but the easiest thing is to start by taking an existing template and modifying it. With the command /imagetemplate you can download the current image template and make modifications and then use it as a custom template.

If you open a template, the linked images will show an error as the referenced file does not exist (see the section on images below). To avoid this, you can download this image pack and unzip it in the same directory where you have the template, which will facilitate editing by getting a better idea of ​​how the images look while editing.

To interpret the elements of the template, the properties id, class and some properties that start with data-, specific for each case, are used. In order to view and edit these properties you need to activate the Inkscape XML editor. Enable it in the Edit »XML Viewer… menu.

Replacements in text elements

Text elements can be interpreted, as if they were normal text templates. You cannot use conditionals of any kind. For a text element to be interpreted, it must have a class called parsetext.

Note that HTML cannot be used in images, so variables that contain links will display the HTML code. For example, the variable {gym}. To prevent the HTML from being displayed, you can use the text-only variant, ie {gym_text}.

Conditionals

Entire elements can be shown and hidden using conditionals. For an element’s conditionals to be interpreted, it must have a class called parseconditions.

Conditions must be set as the value of an attribute called data-conditions. All the conditions described in the text templates section can be used, such as isegg && minutestoend <10.

Images

In an SVG file you can embed images or link external images. If you drag an image file into Inkscape, you must tell it which of the two you want to do. If you want to include your own image (for example, a background image, or the group logo), you will want to embed it. On the contrary, if you want the image to be replaced by one of those available in the bot, you must link it.

The bot can substitute linked images to show Pokémon, Pokémon types, and more. To specify which image you want to replace, you must specify the correct identifier in the id attribute, according to the following table:

If a linked image is defined with one of these id and the image does not exist, it is automatically hidden. For example, if the Pokémon only has one type but images that refer to the second type are used. Linked images that do not have any of these ids will be ignored and will show errors in the template.

Text position and size

Text elements can be repositioned vertically or resized based on the length of your text, to help accommodate text in templates. Accommodating variable-length text is tricky, and using these techniques it is difficult to achieve perfect results when using variable-width fonts, but with a little trial and error you can get good results.

To change the font size based on the length of the text, the element must have a class called resizetext. You can specify the length from which to resize by putting the length as the value of an attribute called data-resizetext-length and the desired size in data-resizetext-size. The size must be specified in units and will be applied in the CSS font-size property. For exemple:

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

To change the vertical position of the text based on its length, the element must have a class called movetext. You can specify the length from which the text is to be repositioned by putting the length as the value of an attribute called data-movetext-length and the desired size in data-movetext-distance. The distance must be specified without units and will be applied as the y attribute of the element. For exemple:

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

Gym images

For the gym images to work, the group needs to have a spreadsheet defined and the gyms are loaded. Once that is done, you have to get the images and send them through the group within a ZIP file by putting the /gymimages command in the comment.

The images must be in JPEG format and be named as the name of the gym (first column) in the spreadsheet is set, with the extension .jpg or .jpeg at the end. Also, each image cannot exceed 300kB in size and the ZIP file cannot exceed 5MB. The ZIP file must not contain subdirectories: the images must all be in the main directory. A maximum of 300 files are processed, so if you have more gyms in your group, you will have to limit yourself to 300 of them.

Images received are only accepted if there is a gym pre-loaded with that name. Once accepted, they are resized and cut to a centered 250x250 pixel square, regardless of the original image format.

If you want to upload more images later, you have to resend them all since, each time a new ZIP file is received, all the previous ones are deleted first.

Limitations

Unlike text templates, image templates are not refreshed every time the message is updated, they are only updated when basic data of the raid changes, such as: the Pokémon, time, gym, etc. That is why variables and conditionals that refer to the number of registered trainers should not be used in the image template, since the image will not be updated properly.

The fonts that can be used are all included in this collection of Google Fonts. If you use unsupported fonts, they will look incorrect. To fix this, you can convert those texts to paths. This cannot be done if you want variables to be interpreted within the text, since when converting them to paths they stop behaving like texts.

Element ids cannot be repeated, so when using the id attribute to specify the image type, you cannot put the same linked image twice in the same template. To fix this, you can add underline _ at the end and the bot will understand it the same. That is, pokemon_img_ and pokemon_img__ work the same as pokemon_img.

Images messages take longer to generate, and depending on the server load this can spell trouble. You should try to use templates as simple as possible and, if you embed images, compress them to a suitable size first. Templates larger than 400 items or 2MB in size are automatically rejected.

Images messages on Telegram have a maximum of 1024 characters, while normal messages have a maximum of 4096 characters. With not very excessive text templates and a maximum of 20 points per raid there should be no problem, but if you don’t limit the targets in your group or put large texts in the templates, you could reach that limit and the raid would stop working. You can copy and paste the text of a raid with many points in a tool like charactercountonline.com to see the number of characters that you usually use. Keep in mind that if you put information in the image, you usually don’t want to have it duplicated in text as well, so you can remove duplicate information from text templates to save characters.

Test the templates

To facilitate template development, the SVG files of the templates can be submitted along with the description /testimagetemplate for private testing (not in a group). The bot will render the template in several different situations so you can check how it looks and correct errors.