Variabili e riuso multi-sito

Sono le variabili a trasformare un template in una rete. Se il disegno delle variabili è giusto, 100 siti si rendono da un’unica sorgente. Se è sbagliato, finite a incollare testo a mano in ogni preset.

Tre sorgenti, un unico ambito

Al momento del render, la maggior parte dei motori unisce le variabili di tre provenienze in un’unica tabella di ricerca. Quando il template legge %SomeName%, il resolver percorre quella tabella e sostituisce il valore.

1. Helper locali al template, dichiarati con #set o #def dentro il corpo.
2. Variabili di sito, definite per tenant — un record per sito, condiviso da tutti i template di quel sito.
3. Variabili di runtime, passate al resolver al momento della chiamata (contesto dell’articolo, di sistema, dell’utente).

Le decisioni di scrittura si riducono a stabilire quale livello possiede ciascun dato.

Helper locali con #set

Usate #set per helper di breve durata dentro un solo template:

#set %Lead% = {Welcome|Greetings|Hello}
%Lead% to %brand_name%!

Usi buoni:

• helper di un singolo template, che altrimenti riempirebbero il corpo di ripetizioni;
• frasi lunghe usate più volte nello stesso template;
• leggibilità, quando l’annidamento diventa abbastanza profondo da stancare l’occhio.

Usi cattivi:

• dati specifici di un tenant — quelli appartengono alle variabili di sito;
• tutto ciò che il runtime già fornisce — un #set locale perde la sfida di precedenza.

Regole di sintassi su cui tutti inciampano

• I nomi delle variabili non distinguono maiuscole e minuscole.
• Solo ASCII: lettere, cifre, underscore. Niente spazi, niente trattini.
• #set funziona solo a inizio riga.
• I commenti si scrivono /# ... #/ e vengono rimossi prima dell’elaborazione.
• Le variabili sconosciute restano letterali. %MissingVar% viene reso come %MissingVar%, non come stringa vuota né come errore. Trattate i residui come un difetto di QA.

Variabili di sito — il moltiplicatore multi-sito

Le variabili di sito sono il motivo per cui un template condiviso può servire molti siti senza leggersi uguale su ogni dominio.

Un preset di sito generico si presenta così:

#set %BrandTone% = {practical|no-nonsense|straightforward}
#set %Industry% = SaaS analytics
#set %TopFeatures% = [<minsize=3;maxsize=4;sep=", ";lastsep=" and ">dashboards|alerting|audit logs|SSO|role-based access]
#set %Audience% = {teams|product leads|operations}

Ora ogni template condiviso può leggere %BrandTone%, %TopFeatures% e così via, e l’output cambia da sito a sito senza che nessuno tocchi il template.

Quando creare una variabile di sito

Variabili di runtime

Le variabili di runtime arrivano dal contesto chiamante: l’articolo in fase di render, l’utente corrente, l’orologio di sistema. Prevalgono sulle variabili di sito e sugli helper locali con lo stesso nome.

Variabili di runtime comuni tra i motori (i nomi dipendono dalla vostra implementazione):

• %year% — anno corrente
• %lang% — codice lingua corrente
• %site_domain% — host del sito corrente
• %brand_name%, %product_name% — marchio/prodotto di cui parla l’articolo
• %article_topic%, %category% — metadati a livello di articolo

Non si assegnano mai da un template. Basta leggerle.

Precedenza delle variabili

Quando lo stesso nome esiste su più livelli, vince la priorità più alta. Un ordine standard, dal più forte al più debole:

1. Variabili di runtime
2. Variabili di sito
3. Variabili di sistema
4. #set locale al template

Conseguenza pratica: #set %brand_name% = Demo dentro un template non fa nulla se il runtime passa %brand_name%. Vince il runtime. Scegliete nomi di helper che non oscurino quelli del runtime.

Convenzioni di denominazione

La coerenza dentro un preset conta più di qualunque stile particolare. Detto questo, un default ragionevole:

• Variabili di runtime: di solito lowercase_snake_case. Esistono fuori dal vostro controllo.
• Variabili di sito: PascalCase per le stringhe normali, PascalCaseConSuffisso per le varianti grammaticali.
• Variabili di elenco: al plurale (%TopFeatures%, %SupportedLanguages%).
• Helper locali: corti e parlanti — %Lead%, %Closing%.

Variabili composte

Le variabili di sito possono riferirsi tra loro. Il resolver del preset sostituisce prima i riferimenti tra variabili, lasciando grezzo lo spintax annidato, così i ri-tiraggi successivi continuano a funzionare:

#set %FoundedLine% = launched in %FoundedYear%, based in %HQ%
#set %Pitch% = {fast|lightweight|self-hosted} %ProductCategory%

Usate le composte per assemblare una sola volta i dati ricorrenti e riusarli tra i template.

La trappola del ri-tiraggio

È di gran lunga la maggiore fonte di confusione per chi inizia. Se una variabile contiene spintax grezzo, ogni occorrenza viene ri-tirata in modo indipendente.

#set %Tone% = {safe|trusted}
%Tone% and %Tone%

Output possibile:

Safe and trusted

Non date per scontato che una variabile #set si risolva una volta e poi si limiti a ripetersi. Se vi servono due aggettivi diversi, usate due variabili.

Quando serve una ripetizione esatta: #def

La regola qui sopra riguarda #set, che è una macro. La sorella #def ha la stessa forma e fa l’opposto: risolve il proprio valore una volta per render e consegna lo stesso risultato a ogni riferimento.

#def %Tone% = {safe|trusted|secure}

%Tone% and %Tone%

Adesso i due punti concordano sempre — «safe and safe», «trusted and trusted» — perché il tiraggio è avvenuto una volta sola, prima che qualunque riferimento venisse riempito. È tutta qui la differenza tra le due direttive; il resto (ancorata alla riga, una per riga, rimossa dall’output, stesse regole sui nomi) è identico.

Ricorrete a #def quando un valore deve restare stabile in tutto il template: un numero che alimenta un blocco {plural}, un sostantivo estratto da uno spazio di forma plurale, o qualsiasi frase che ripetete di proposito. Ricorrete a #set quando la variazione la volete, che nel corpo del testo è il caso normale.

Una precisazione da dire chiaramente: #def rende una variabile coerente con se stessa. Non correla due variabili diverse — ogni #def tira per conto proprio, quindi %Noun% e %NounGenitive% possono comunque cadere su parole diverse. Quando due valori devono concordare tra loro, legateli in un’unica enumerazione invece che in due variabili.

Frammenti opzionali

Un ramo vuoto in un’enumerazione produce un frammento opzionale:

{|official }website
{fast|secure|} withdrawals

Mettete lo spazio dentro il ramo opzionale quando il frammento può sparire, altrimenti ottenete spazi doppi o parole attaccate. Per un elenco opzionale (una permutazione che può restare vuota), avvolgete l’intera permutazione:

{|[<minsize=2;maxsize=3;sep=", ";lastsep=" and ">Slack|Jira|Linear]}

Il motore non può scegliere zero elementi da una permutazione. Avvolgerla è l’unico modo per rendere possibile «nessun elenco».

Collisioni di separatore

Un difetto di render classico: la variabile di elenco contiene già un and, e il testo attorno ne aggiunge un altro.

%Integrations% and other tools

Se %Integrations% si risolve in Slack, Jira, and Linear, il testo finale diventa:

Slack, Jira, and Linear and other tools

Rimedi:

• inserire una virgola: %Integrations%, and other tools;
• ristrutturare: {Besides|Along with} %Integrations%, other tools...;
• togliere la congiunzione finale e usare due punti o lineetta.

Stesso problema con una permutazione che ha lastsep=" and " seguita da testo fisso che inizia con and. Guardate qualche variante in anteprima prima di pubblicare.

Variabili o spintax inline

Regola pratica: estraete in variabili le frasi ripetute e sensibili alla grammatica prima di aggiungere piccoli spazi di sinonimo inline. La variabile vi dà un solo posto in cui correggere gli errori. L’inline li sparpaglia.

Errori frequenti con le variabili

Checklist per il disegno delle variabili

• Ogni dato specifico di un tenant vive in una variabile di sito, non nel template condiviso.
• Ogni dato specifico dell’articolo vive in una variabile di runtime, non in un #set.
• Nessun nome di helper #set oscura una variabile di runtime.
• I nomi delle variabili sono ASCII, senza spazi né trattini.
• Ogni variabile ripetuta è stata verificata per l’effetto di ri-tiraggio.
• Ogni frammento opzionale gestisce i propri spazi dentro il ramo.
• Ogni variabile di elenco seguita da una congiunzione è stata controllata contro le collisioni di separatore.
• Cinque campioni risolti non lasciano alcun %...%.

Pronti per la struttura? La guida successiva copre le permutazioni in pratica — dove la varietà vive davvero.

Continua la serie