Modelli

I modelli vengono utilizzati per personalizzare i messaggi che appaiono nei raid e negli annunci. In questo modo, puoi aggiungere alcuni dati che non vengono mostrati di default, come i PL massimi o le forme dei Pokémon, cambiare la disposizione/l’ordine degli elementi esistenti, oppure utilizzare dei modelli immagine.

Modelli di testo

Ci sono due modelli completamente indipendenti tra loro: il modello raid, che viene modificato con /raidtemplate, e il modello di annuncio, che viene modificato con /announcetemplate. Inoltre, i raid possono contenere del testo dopo l’elenco degli allenatori segnati, che può essere impostato con /raidfootertemplate.

Inviando questi comandi senza argomenti, viene mostrato il codice del modello corrente. Per modificare un modello, puoi copiarlo e incollarlo con le modifiche desiderate. Ad esempio:

/raidtemplate <b>{Pokemon}</b> Raid {{il <b>{weekday_day_month}</b> }}alle {timewarn_icon_}<b>{raidtime}</b> presso {gym_icon}{gym}<br>{{<em>Disponibile dalle {opentime} alle {endtime}</em><br>}}<em>Organizzato da </em>{organizer}{_edited_icon}{_refloated_icon}

Per tornare al modello predefinito, devi inserire un trattino -, come segue:

/raidtemplate - 

⚠️ Ti sembra molto complicato? Inizia inserendo il comando /raidtemplate e guarda il modello raid corrente. Copia, incolla e apporta una piccola modifica. Pian piano poi prova ad aggiungere nuovi parametri.

Modelli predefiniti

Oltre al modello predefinito, ci sono alcuni modelli predefiniti aggiuntivi. Per utilizzarli, è necessario specificare il loro nome invece di inserire il modello completo. Ad esempio:

/raidtemplate maxcp
/announcetemplate maxcp 

I modelli predefiniti disponibili sono:

Variabili

In ogni modello troverai del testo tra parentesi {} che sono variabili che verranno poi sostituite dai dati dei raid e degli annunci. Ad esempio, {gym} viene sostituito dal nome della palestra, con un collegamento per raggiungerla se la posizione è stata impostata.

Questo elenco indica tutte le variabili disponibili. Alcune sono già utilizzate nel modello predefinito o in uno dei modelli predefiniti, ma altre non lo sono. Per appunto, le parentesi {} non compaiono nell’elenco.

Formato con HTML

I modelli possono essere formattati con HTML semplice, con le solite restrizioni di Telegram:

• I tag validi sono <i></i> (corsivo), <b></b> (grassetto), <u></u> (sottolineato), <s></s> (barrato), <code></code> (testo copiabile con click da cellulare) e <a href=""></a> (collegamento).
• Se si desidera che i caratteri <, > e & vengano visualizzati, è necessario utilizzare le entità <, > e &.
• È possibile inserire, ad esempio, testo in grassetto e sottolineato contemporaneamente, annidando correttamente le etichette. <u><b>Bene</b></u> è corretto, ma <u><b>Male</u></b> è sbagliato e non funzionerà
• Le interruzioni di riga (gli “invii” praticamente) dovrebbero essere indicate con <br>. Puoi separare gli elementi mettendone diversi in fila, ad esempio <br><br> aggiungerà due invii quindi una riga vuota.

Ricorda che stai specificando il codice per il modello e il formato che applichi direttamente verrà ignorato. Cioè, se vuoi che qualcosa venga mostrato in grassetto, devi metterlo <b>in questo modo</b>, e non usare il grassetto di Telegram.

Varianti di variabili

Per aiutare a costruire messaggi migliori ci sono versioni delle variabili con spazi all’inizio, con spazi alla fine, in lettere maiuscole… Queste sono le varianti disponibili:

• {VARIABILE}: contiene la {variabile} in maiuscolo.
• {Variabile}: contiene la {variabile} forzando la prima lettera maiuscola.
• {_variabile}: contiene la {variabile} con uno spazio all’inizio.
• {variabile_}: contiene la {variabile} con uno spazio alla fine.
• {_variabile_}: contiene la {variabile} con uno spazio all’inizio e uno alla fine.

Varianti di variabili con collegamenti

Le variabili che riportano Link nella colonna HTML contengono collegamenti. Cioè, {pokemon_gameinfo} verrà visualizzato come nome del Pokémon con un collegamento a Gameinfo.

Questo tipo di variabile può essere scomposto per visualizzare in modo indipendente solo il testo, aggiungendo _text alla fine, o solo l’URL, aggiungendo _link alla fine.

Ad esempio, la variabile {pokemon_gameinfo_text} conterrà il testo con il nome del Pokémon e {pokemon_gameinfo_link} conterrà l’URL.

Blocchi condizionali

Esistono due tipi di blocchi condizionali, che consentono di mostrare o nascondere parti dei modelli a seconda della situazione.

Blocco condizionale semplice

Questo blocco condizionale più semplice è scritto semplicemente così: {{testo {variabile} e altro testo }}.

In questo caso, il contenuto tra doppie parentesi graffe verrà mostrato solo se tutte le variabili utilizzate all’interno sono definite o sono vere.

Ci sono diversi esempi di questo tipo di blocco nel modello predefinito, dove viene visualizzato solo un pezzo di testo se la variabile weekend_day_month è definita e un altro se sono definiti opentime e endtime.

Blocco condizionale con condizioni

L’altro tipo di blocco condizionale consente di utilizzare condizioni complesse ed è scritto in questo modo: [condizioni]{{testo {variabile} e altro testo}}.

In questo caso, il contenuto tra doppie parentesi graffe verrà visualizzato solo se le condizioni definite tra “[]” sono vere. Non importa se le variabili all’interno delle doppie parentesi graffe ` {{}}` sono indefinite o false, il contenuto viene comunque visualizzato.

Le condizioni possono essere semplicemente variabili come opentime o isegg. Possono anche essere negate mettendo un “!” davanti. Per esempio:

[opentime]{{<em>Aperto dalle {opentime} alle {endtime}</em><br>}}
[!isegg]{{🐒 Raid di <b>{pokemon_kingcasualbot} ({maxcp}/{maxcp_boosted})}}

All’interno delle condizioni è possibile utilizzare comparatori matematici comuni: minore di <, maggiore di >, uguale a ==, diverso di !=, minore o uguale a <= e maggiore o uguale a >=. Possono essere utilizzati per confrontare valori variabili con valori arbitrari, ad esempio:

[opentime>20:00]{{🌚 Stai attento, fa buio!}}
[minutestoend<5]{{⛔️ C'è pochissimo tempo per fare il raid, anticipalo!!}}
[tier==ex]{{🎟 'Ricorda che hai bisogno di un pass speciale per poter fare il raid, non iscriverti se non lo hai!}}

Puoi anche usare le congiunzioni logiche: e && e o ||. In questo modo si possono unire più condizioni per renderne una più complessa, ad esempio:

[isegg && minutesfromstart<10]{{<em>🥚🚫 Possono schiudersi diversi Pokémon e hai impostato l'ora molto vicina al tempo di schiusa. Se puoi, modifica l'ora per un po 'più tardi.}}
[raidispending && trainerscount_remote > 5]{{⛔️💌 <u>Vietato invitare chiunque non sia registrato!!</u> }}

In caso di utilizzo di più di due condizioni && e ||, tieni conto che le condizioni vengono sempre valutate da sinistra verso destra e questo ordine di valutazione non può essere modificato.

Variabili da utilizzare nei blocchi condizionali

Tutte le variabili descritte nella tabella sopra possono essere utilizzate come condizioni. Nel caso in cui abbiano un valore definito, la condizione sarà vera. Nel caso in cui non abbiano un valore definito, la condizione sarà falsa.

Inoltre, ci sono alcune variabili appositamente indicate da utilizzare come condizioni, che non mostrano nulla anche se sono vere:

Modelli immagine

I modelli immagine ti consentono di aggiungere immagini ai sondaggi raid, che possono essere personalizzati con le informazioni di ogni singolo annuncio/raid. Sono disabilitati per impostazione predefinita. Per attivarli o cambiarli, usa il comando /imagetemplate. Ad esempio, per utilizzare il modello default:

/imagetemplate default

Per vedere i modelli disponibili o scaricare il modello attualmente in uso, usa /imagetemplate senza parametri. Per smettere di usare i modelli immagine, usa il parametro -, ovvero:

/imagetemplate -

I modelli immagine possono essere personalizzati. Sono file SVG con una dimensione compresa tra 600x300 pixel e 600x400 pixel. All’interno, contengono elementi di testo e immagine che vengono interpretati e sostituiti dal bot con i dati effettivi del raid o dell’annuncio. Si consiglia di utilizzare Inkscape per la modifica (richiede un computer Linux, Windows o Mac).

Per iniziare a utilizzare un modello personalizzato, invia il file SVG del modello al gruppo, inserendo /imagetemplate nella descrizione. Il bot ti risponderà che il modello è stato caricato.

Puoi iniziare un modello completamente da zero, ma la cosa più semplice da fare è iniziare prendendo un modello già esistente, modificandolo. Con il comando /imagetemplate puoi scaricare il modello immagine corrente e apportare modifiche per usarlo in seguito come modello personalizzato.

Se apri un modello, le immagini collegate verranno visualizzate con un errore poiché il file di riferimento non esiste (leggi la sezione immagini di seguito). Per evitare ciò, puoi scaricare questo pacchetto di immagini e decomprimerlo nella stessa directory in cui hai il tuo modello, il che faciliterà la modifica avendo un’idea migliore di come sarà l’immagine una volta finita.

Per interpretare gli elementi del modello, vengono usate le proprietà id, class e alcune proprietà che iniziano con data-, in base all’elemento. Per visualizzare e modificare queste proprietà è necessario attivare l’editor XML di Inkscape. Abilitalo nel menu Edit » XML Viewer….

Sostituzioni negli elementi di testo

Gli elementi di testo possono essere interpretati, come se fossero normali modelli di testo. Non puoi usare blocchi condizionali di alcun tipo. Perché un elemento di testo possa essere interpretato, deve avere una class chiamata parsetext.

Tieni presente che l’HTML non può essere utilizzato nelle immagini, quindi le variabili che contengono collegamenti visualizzeranno il codice HTML diretto. Ad esempio, la variabile {gym}. Per impedire la visualizzazione dell’HTML, è possibile utilizzare la variante di solo testo, ovvero {gym_text}.

Condizionali

Utilizzando i condizionali possono essere mostrati e nascosti interi blocchi di elementi. Perché i condizionali di un elemento possano essere interpretati, devono avere una class chiamata parseconditions.

Le condizioni devono essere impostate come valore di un attributo chiamato data-conditions. Possono essere utilizzate tutte le condizioni descritte nella sezione dei modelli di testo, come isegg && minutestoend<10.

Immagini

In un file SVG puoi incorporare (embed) immagini o collegare (link) immagini esterne. Se trascini un file immagine in Inkscape, devi dirgli quale dei due vuoi fare. Se desideri includere la tua immagine (ad esempio, un’immagine di sfondo o il logo del gruppo), dovrai incorporarla. Al contrario, se vuoi che l’immagine venga sostituita da una di quelle disponibili nel bot, devi collegarla.

Il bot può sostituire le immagini collegate per mostrare Pokémon, tipi dei Pokémon (fuoco, erba, ecc.) e altre cose. Per specificare quale immagine si desidera sostituire, è necessario specificare l’identificatore corretto nell’attributo id, secondo la seguente tabella:

Se un’immagine collegata è definita con uno di questi id e l’immagine non esiste, viene automaticamente nascosta. Ad esempio, se il Pokémon ha un solo tipo ma vengono utilizzate immagini che si riferiscono al secondo tipo. Le immagini collegate che non hanno nessuno di questi ID verranno ignorate e mostreranno errori nel modello.

Posizione e dimensione del testo

Gli elementi di testo possono essere riposizionati verticalmente o ridimensionati in base alla lunghezza del testo, per facilitare l’inserimento del testo nei modelli. Adattare il testo a lunghezza variabile è complicato e utilizzando queste tecniche è difficile ottenere risultati perfetti quando si utilizzano caratteri a larghezza variabile, ma con un po’ di tentativi (ed errori) è possibile ottenere buoni risultati.

Per cambiare la dimensione del carattere in base alla lunghezza del testo, l’elemento deve avere una class chiamata resizetext. Puoi specificare la lunghezza da cui partire per ridimensionare inserendo la lunghezza come valore di un attributo chiamato data-resizetext-length e la dimensione desiderata in data-resizetext-size. La dimensione deve essere specificata in unità e verrà applicata nella proprietà CSS font-size. Per esempio:

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

Per cambiare la posizione verticale del testo in base alla sua lunghezza, l’elemento deve avere una class chiamata movetext. Puoi specificare la lunghezza dalla quale il testo deve essere riposizionato inserendo la lunghezza come valore di un attributo chiamato data-movetext-length e la dimensione desiderata in data-movetext-distance. La distanza deve essere specificata senza unità e verrà applicata come attributo y dell’elemento. Per esempio:

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

Immagini delle palestre

Affinché le immagini della palestra funzionino, il gruppo deve avere un foglio di calcolo definito e le palestre vengono caricate. Fatto ciò, devi ottenere le immagini e inviarle al bot all’interno di un file ZIP inserendo la descrizione /gymimages.

Le immagini devono essere in formato JPEG e devono essere chiamate come il nome della palestra (prima colonna) nel foglio di calcolo, con l’estensione .jpg o .jpeg alla fine. Inoltre, ogni immagine non può superare i 300 kB di dimensione e il file ZIP non può superare i 5 MB. Lo ZIP non deve contenere sottodirectory, le immagini devono essere nella directory principale. Vengono elaborati un massimo di 300 file, quindi se hai più palestre nel tuo gruppo, dovrai limitarti a 300 di esse.

Le immagini ricevute vengono accettate solo se è presente una palestra precaricata con quel nome. Una volta accettate, vengono ridimensionate e tagliate in un riquadro di 250x250 pixel, indipendentemente dal formato dell’immagine originale.

Limitazioni

A differenza dei modelli di testo, i modelli immagine non vengono aggiornati ogni volta che il messaggio viene aggiornato, ma solo quando cambiano i dati base del raid, come: il Pokémon, l’orario, la palestra, ecc. Questo è il motivo per cui le variabili e le condizioni che si riferiscono al numero di allenatori registrati non dovrebbero essere utilizzate nel modello dell’immagine, poiché l’immagine non verrà aggiornata correttamente.

I caratteri che possono essere utilizzati sono tutti inclusi in questa raccolta di Google Fonts. Se utilizzi caratteri non supportati, noterai subito che sembrano “errati”. Per risolvere questo problema, puoi convertire quei testi in percorsi. Ciò non può essere fatto se si desidera che le variabili vengano interpretate all’interno del testo, poiché quando le si converte in percorsi smettono di comportarsi come testi.

Gli ID elemento non possono essere ripetuti, quindi quando si utilizza l’attributo id per specificare il tipo di immagine, non è possibile inserire due volte la stessa immagine collegata nello stesso modello. Per risolvere questo problema, puoi aggiungere delle linee basse _ alla fine, e il bot lo capirà comunque. Cioè, pokemon_img_ e pokemon_img__ funzionano allo stesso modo di pokemon_img.

La generazione dei messaggi con immagini richiede più tempo e, a seconda del carico del server, ciò può causare problemi. Dovresti provare a utilizzare modelli il più semplici possibile e, se incorpori immagini, prima comprimerle a una dimensione adeguata. I modelli più grandi di 400 elementi o di dimensioni 2 MB vengono automaticamente rifiutati.

I messaggi con immagini su Telegram hanno un massimo di 1024 caratteri, mentre i messaggi normali hanno un massimo di 4096 caratteri. Con modelli di testo non eccessivi e un massimo di 20 allenatori segnati per raid non dovrebbero esserci problemi, ma se non limiti il numero di allenatori nel tuo gruppo o metti testi molto lunghi nei modelli, potresti raggiungere quel limite e il sondaggio raid smetterà di funzionare. Puoi copiare e incollare il testo di un raid con molti allenatori segnati in uno strumento come charactercountonline.com per vedere il numero di caratteri che usi abitualmente. Tieni presente che volendo, i dati mostrati nell’immagine, potrebbero benissimo essere omessi dal sondaggio raid, risparmiando così caratteri utili.

Testare i modelli

Per rendere più facile lo sviluppo dei modelli, puoi inviare i file SVG dei modelli insieme alla descrizione /testimagetemplate per testarli privatamente (non in un gruppo). Il bot eseguirà il rendering del modello in diverse situazioni in modo da poter controllare come appare e correggere gli errori.