Variables y reutilización multisitio

Las variables son lo que convierte una plantilla en una red. Si el diseño de variables está bien, 100 sitios se renderizan desde una sola fuente. Si está mal, acabas pegando texto a mano en cada preajuste.

Tres fuentes, un solo ámbito combinado

Al renderizar, la mayoría de motores combinan variables de tres orígenes en una única tabla de consulta. Cuando la plantilla lee %SomeName%, el resolutor recorre esa tabla y sustituye el valor.

1. Ayudantes locales de la plantilla, declarados con #set o #def dentro del cuerpo.
2. Variables de sitio, definidas por inquilino — un registro por sitio, compartido por todas las plantillas de ese sitio.
3. Variables de runtime, pasadas al resolutor en el momento de la llamada (contexto del artículo, del sistema, del usuario).

Las decisiones al escribir se reducen a qué capa es dueña de cada hecho.

Ayudantes locales con #set

Usa #set para ayudantes de vida corta dentro de una plantilla:

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

Buenos usos:

• ayudantes de una sola plantilla, que si no llenarían el cuerpo de repetición;
• frases largas repetidas varias veces dentro de la misma plantilla;
• legibilidad, cuando el anidamiento se hace tan profundo que cansa la vista.

Malos usos:

• hechos propios de un inquilino — esos van en variables de sitio;
• cualquier cosa que el runtime ya provee — un #set local pierde la pelea de precedencia.

Reglas de sintaxis con las que todo el mundo tropieza

• Los nombres de variable no distinguen mayúsculas de minúsculas.
• Solo ASCII: letras, números, guion bajo. Sin espacios, sin guiones.
• #set solo funciona al principio de línea.
• Los comentarios se escriben /# ... #/ y se eliminan antes del procesado.
• Las variables desconocidas quedan literales. %MissingVar% se renderiza como %MissingVar%, no como cadena vacía ni como error. Trata los restos como un fallo de QA.

Variables de sitio — el multiplicador multisitio

Las variables de sitio son la razón de que una plantilla compartida sirva a muchos sitios sin leerse igual en todos los dominios.

Un preajuste de sitio genérico se ve así:

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

Ahora cualquier plantilla compartida puede leer %BrandTone%, %TopFeatures%, etc., y la salida cambia por sitio sin que nadie toque la plantilla.

Cuándo crear una variable de sitio

Variables de runtime

Las variables de runtime vienen del contexto que llama: el artículo que se renderiza, el usuario actual, el reloj del sistema. Ganan a las variables de sitio y a los ayudantes locales con el mismo nombre.

Variables de runtime comunes entre motores (los nombres dependen de tu implementación):

• %year% — año actual
• %lang% — código de idioma actual
• %site_domain% — host del sitio actual
• %brand_name%, %product_name% — marca/producto del que habla el artículo
• %article_topic%, %category% — metadatos del artículo

Nunca se asignan desde una plantilla. Basta con leerlas.

Precedencia de variables

Cuando el mismo nombre existe en varias capas, gana la de mayor prioridad. Un orden estándar, de más fuerte a más débil:

1. Variables de runtime
2. Variables de sitio
3. Variables de sistema
4. #set local de la plantilla

Consecuencia práctica: #set %brand_name% = Demo dentro de una plantilla no hace nada si el runtime pasa %brand_name%. Gana el runtime. Elige nombres de ayudante que no tapen los del runtime.

Convenciones de nombres

La coherencia dentro de un preajuste importa más que cualquier estilo concreto. Aun así, un valor por defecto razonable:

• Variables de runtime: normalmente lowercase_snake_case. Están fuera de tu control.
• Variables de sitio: PascalCase para cadenas normales, PascalCaseConSufijo para variantes gramaticales.
• Variables de lista: en plural (%TopFeatures%, %SupportedLanguages%).
• Ayudantes locales: cortos y descriptivos — %Lead%, %Closing%.

Variables compuestas

Las variables de sitio pueden referenciarse entre sí. El resolutor del preajuste sustituye primero las referencias entre variables y deja el spintax anidado en crudo, para que las re-tiradas posteriores sigan funcionando:

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

Usa las compuestas para montar una vez los hechos repetidos y reutilizarlos entre plantillas.

La trampa de la re-tirada

Es de lejos la mayor fuente de confusión al empezar. Si una variable contiene spintax en crudo, cada aparición vuelve a tirar de forma independiente.

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

Salida posible:

Safe and trusted

No des por hecho que una variable de #set se resuelve una vez y luego se repite. Si necesitas dos adjetivos distintos, usa dos variables.

Cuando sí necesitas repetición exacta: #def

La regla de arriba es sobre #set, que es una macro. Su hermana #def tiene la misma forma y hace lo contrario: resuelve su valor una vez por render y entrega ese mismo resultado a todas las referencias.

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

%Tone% and %Tone%

Ahora los dos huecos siempre concuerdan — «safe and safe», «trusted and trusted» — porque la tirada ocurrió una vez, antes de rellenar ninguna referencia. Esa es toda la diferencia entre ambas directivas; el resto (anclada a la línea, una por línea, eliminada de la salida, mismas reglas de nombre) es idéntico.

Recurre a #def cuando un valor debe mantenerse estable en toda la plantilla: un número que alimenta un bloque {plural}, un sustantivo sacado de un hueco de forma plural, o cualquier frase que repites a propósito. Recurre a #set cuando quieres la variación, que es lo habitual en el cuerpo del texto.

Una salvedad que conviene decir claro: #def hace que una variable sea coherente consigo misma. No correlaciona dos variables distintas — cada #def tira por su cuenta, así que %Noun% y %NounGenitive% pueden caer en palabras diferentes. Cuando dos valores deben concordar entre sí, átalos en una sola enumeración en vez de en dos variables.

Fragmentos opcionales

Una rama vacía en una enumeración da un fragmento opcional:

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

Pon el espacio dentro de la rama opcional cuando el fragmento pueda desaparecer; si no, salen espacios dobles o palabras pegadas. Para una lista opcional (una permutación que puede quedar vacía), envuelve la permutación entera:

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

El motor no puede elegir cero elementos de una permutación. Envolver es la única forma de que «ninguna lista» sea un desenlace posible.

Colisiones de separador

Un fallo de render habitual: la variable de lista ya contiene un and, y el texto de alrededor añade otro.

%Integrations% and other tools

Si %Integrations% se resuelve a Slack, Jira, and Linear, el texto final queda:

Slack, Jira, and Linear and other tools

Arreglos:

• meter una coma: %Integrations%, and other tools;
• reestructurar: {Besides|Along with} %Integrations%, other tools...;
• quitar la conjunción final y usar dos puntos o raya.

Lo mismo pasa con una permutación con lastsep=" and " seguida de texto fijo que empieza por and. Previsualiza unas cuantas variantes antes de publicar.

Variables o spintax en línea

Regla práctica: extrae a variables las frases repetidas y sensibles a la gramática antes de añadir pequeños huecos de sinónimo en línea. La variable te da un solo sitio donde corregir errores. El inline los dispersa.

Errores frecuentes con variables

Checklist de diseño de variables

• Todo hecho propio de un inquilino vive en una variable de sitio, no en la plantilla compartida.
• Todo hecho propio del artículo vive en una variable de runtime, no en un #set.
• Ningún nombre de ayudante #set tapa una variable de runtime.
• Los nombres de variable son ASCII, sin espacios ni guiones.
• Cada variable repetida se ha revisado por el efecto de re-tirada.
• Cada fragmento opcional resuelve sus espacios dentro de la rama.
• Cada variable de lista seguida de conjunción se ha comprobado contra colisión de separador.
• Cinco muestras resueltas no dejan ningún %...%.

¿Listo para la estructura? La siguiente guía cubre las permutaciones en la práctica — donde vive de verdad la variedad.

Continuar la serie