advicedocs

Image

An image field renders a real image at the placeholder location at document-fill time. It is detected by the substring image in the field name — just like a graph field, but for images. Images are inserted inline, sized according to the configuration, and silently skipped if no value is supplied.

How to write an image placeholder

The placeholder is a plain {{ field_name }}. Any name containing image qualifies. The image substitution rule requires the placeholder to be the only content in its paragraph — don’t mix the placeholder with surrounding text on the same line.

Valid image placeholders

{{ profile_image }}

{{ adviser_signature_image }}

{{ company_logo_image }}

Placeholder must be alone in the paragraph

Image substitution looks for a paragraph that contains only the placeholder. Mixing prose and the placeholder on the same line silently fails.
Wrong vs right

Wrong:

Logo: {{ company_logo_image }}

 

Right:

Logo:

{{ company_logo_image }}

Configuration after upload

Open the field configuration modal for an image field. You will see:

  • Width — in pixels, slider range 50–800.
  • Height — in pixels, slider range 50–600.
  • Use natural size — clears both width and height so the image renders at its intrinsic dimensions.
  • Preview toggle — an A4 mockup so you can sanity-check sizing.

There is no colour picker, font controls, or chart-type selector for image fields — those are graph-only.

How image data flows at fill time

At fill time AdviceDocs accepts image data in two shapes:

  • S3 reference (preferred) — { "type": "s3_image", "s3_key": "path/to/image.png" }. The renderer downloads the bytes from S3.
  • Raw bytes — passed through directly to the docx renderer.

Plain strings (a path, URL, or filename) are not supported — the renderer logs a warning and treats the field as empty.

Supported formats

  • PNG — preferred for transparent backgrounds.
  • JPEG — preferred for photos.
  • SVG — supported; auto-converted to PNG before embedding.
  • GIF — supported as a static image.

Missing or invalid image

If the field has no value, or the S3 download fails, the placeholder paragraph is silently cleared. No error is raised in the document; a warning is logged on the server. The surrounding paragraphs are left untouched.

Common pitfalls

Placeholder mixed with text

The most common cause of a missing image is a placeholder that shares a paragraph with prose. Move the placeholder onto its own line.

Only one of width/height

Setting only width or only height causes the rendered image to use a fallback aspect ratio. Either set both, or click Use natural size to let the image render at its own dimensions.

External URLs not supported

AdviceDocs does not fetch from arbitrary HTTP URLs. Upload the image to your AdviceDocs S3 bucket (or supply raw bytes) instead.

Header and footer images use a different path

Image fields placed in document headers and footers are processed by a separate XML path. Treat them as experimental: test renders on a sample template before relying on them in production.

Pre-optimise large images

AdviceDocs will auto-shrink an oversized image to fit the configured dimensions, but the original bytes still travel through the pipeline. Pre-optimise large source images for performance.

Syntax to copy

Standalone image placeholders

{{ profile_image }}

{{ adviser_signature_image }}

{{ company_logo_image }}

{{ portfolio_chart_image }}

With a caption underneath (each on its own line)

{{ company_logo_image }}

Figure 1 — Company logo