pom_get_available_mergetags: listar las etiquetas de combinación
Qué etiquetas de combinación son válidas en el contexto de una plantilla. Las etiquetas de combinación son la manera en que una plantilla incorpora valores dinámicos, y una no válida falla silenciosamente — así que esta es la llamada que evita toda una clase de errores invisibles.
Argumentos
| Argumento | Obligatorio | Significado |
|---|---|---|
context |
Sí | archive, single o feed |
Un contexto no reconocido recurre a single en lugar de devolver un error, así que comprueba que el campo context de la respuesta coincide con lo que pediste.
Permisos
mcp:read y pom_theme:read, con edit_theme_options.
Ten en cuenta el requisito más alto: este es un permiso del tema, no de contenido. Un cliente que puede editar páginas no necesariamente puede leer las etiquetas de combinación.
Qué devuelve
| Campo | Significado |
|---|---|
context |
El contexto resuelto |
mergetags |
Todas las etiquetas válidas para él |
rules |
Las reglas de sintaxis |
Cada etiqueta incluye su forma literal tag, su name, una description y su comportamiento de escaping.
Las tres reglas que devuelve
Usa llaves dobles. {{tag_name}}.
Usa %%…%% dentro de los atributos para texto largo, texto entrecomillado, fragmentos de HTML o etiquetas de combinación anidadas. Las llaves dobles dentro de un atributo de shortcode rompen el análisis del atributo; la forma con porcentaje existe exactamente para ese caso.
No inventes etiquetas de combinación. Valida antes de guardar.
La segunda regla es la que no se puede adivinar. Un asistente tenderá a usar {{…}} en todas partes, y producirá atributos de shortcode rotos.
El contexto importa
Cada contexto tiene su propio catálogo. Una etiqueta válida en una plantilla individual no es necesariamente válida en un archivo, y usarla allí es un error en lugar de una representación vacía.
Lee el contexto para el que realmente estás construyendo. Los tres contextos se describen en pom_get_template_schema.
Etiquetas disponibles en todas partes
Algunas etiquetas aparecen en todos los contextos, incluidas {{icon}} para representar un icono SVG y {{translatable_string}} para registrar y representar texto traducible.
La segunda importa en sitios multilingües: el texto codificado en una plantilla no es traducible, y {{translatable_string}} es la manera de que lo sea.
Bloques condicionales
Tres etiquetas de control gestionan los condicionales: {{if}}, {{else}} y {{/if}}.
{{if}} acepta los atributos meta y value:
{{if meta="meta-key" value="not_empty"}}El validador avisa cuando {{if}} se usa sin ambos, y devuelve un error ante un {{else}} o {{/if}} sin su pareja, o un {{if}} sin cerrar. Consulta pom_validate_template_markup.
Escapado
Cada etiqueta informa de su escaping. Eso te dice si el valor se representa como HTML o se escapa como texto — lo que determina si una etiqueta es segura para colocar dentro de un atributo, y si el HTML del valor subyacente se representará o se mostrará como marcado.
Cómo usarla bien
Obtén las etiquetas de combinación disponibles para el contexto de archivo y muéstrame cuáles se relacionan con el bucle de resultados.
Enumera las etiquetas de combinación del contexto individual con su comportamiento de escapado.
Antes de componer:
Lee el esquema de la plantilla y las etiquetas de combinación disponibles para este contexto, después compón el marcado y valídalo antes de escribir.
Por qué las etiquetas no válidas son peligrosas
Una etiqueta de combinación que el tema no reconoce no genera un error. Se representa como texto literal o como nada, en cada página que cubre la plantilla.
Esa combinación — silenciosa y multiplicada por muchas páginas — es la razón por la que el validador trata una etiqueta de combinación desconocida como un error en lugar de un aviso, y por la que merece la pena llamar a esta herramienta en cada ocasión.