Cómo diagnosticar errores en plantillas Word - DocxParser

Cuando una plantilla Word no muestra datos o ignora condiciones, normalmente el origen está en cómo Athento transforma los metadatos en variables de contexto antes de renderizar el documento. Este artículo explica cómo funciona el parser DocxParser y cómo usar esa información para resolver errores comunes.

Cómo funciona el parser

Athento usa DocxParser (basado en docxtpl) para procesar plantillas .docx.
Este parser crea un contexto Jinja a partir de los metadatos del documento:

• Cada metadato se añade al contexto usando su slug como nombre (sustituyendo guiones por guiones bajos).

• El valor se transforma según su tipo:

  • Texto → Listing (objeto especial de docxtpl)

  • Área de texto → Listing con saltos de línea

  • JSON → diccionario o lista Python (usando ast.literal_eval)

  • Booleano → <slug>_boolean + valor lógico

  • Imagen → InlineImage

Esto significa que no todos los valores son cadenas, y eso afecta a las comparaciones o transformaciones dentro de la plantilla.

🧩 Cómo depurar en la plantilla

Cuando una condición o bucle no funciona, imprime los valores y su tipo real:

Valor: {{ metadata_tipodepersona }}
Tipo: {{ metadata_tipodepersona.__class__ }}

Esto mostrará algo como:

Valor: Persona Física
Tipo: <class 'docxtpl.listing.Listing'>

Si ves <class 'docxtpl.listing.Listing'>, significa que el valor no es una cadena, sino un objeto envoltorio.
Debes convertirlo a string antes de usarlo:

{% set tipo = metadata_tipodepersona|string|trim|lower %}

🧪 Tipos comunes que puedes encontrar

Checklist para evitar errores frecuentes

• Usa comillas rectas ' o ", nunca “tipográficas”.
• Usa siempre |string|trim|lower al comparar textos.
• En tablas:
  • los bucles se hace con {%tr for %} , no te dejes el tr fuera
  • Coloca {%tr for %} y {%tr endfor %} dentro de filas, no fuera.