Document Builder Background Images and Text Overlays

Document Builder background images and text overlays

Use a banner image behind text to preserve a branded quote header. Keep the logo and artwork in the image. Keep quote numbers, customer numbers, and other Salesforce merge fields as HTML text.

Release status: Positioning support awaits server deployment. The assistant guidance also requires publication of the updated agent packages and activation of their registry entries. Live org and PDF acceptance remain unconfirmed. Earlier server versions remove these positioning styles when you save or generate a PDF.

How Document Builder supports background images

The supported pattern uses a normal managed <img> as the visual background. A surrounding block sets position: relative. Text blocks inside it set position: absolute with offsets. This places text over the image.

This pattern does not use CSS background-image. The saved source does not support background-image: url(...). Asset resolution looks for <img data-xp-asset-id="...">; it does not resolve image URLs in CSS.

The image stays in normal document flow. Its height reserves space for the header, so the next document section starts below it. The text remains editable and searchable in the generated PDF.

Add a managed banner image

  1. Open Assets in the left navigation.
  2. Upload a PNG or JPEG image, up to 1 MB. Upload saves the asset but does not insert it.
  3. Select Insert for that asset.
  4. Open the HTML source and keep the inserted image's data-xp-asset-id.
  5. Put the image and text blocks inside one relative-positioned wrapper, as shown below.

The asset ID identifies an image registered with the active document or template. Do not invent an asset ID or copy one from a different document. The runtime resolves that ID to an image delivery URL for preview and PDF output.

Canonical source can omit src for a registered managed image. Do not replace the asset ID with a temporary preview URL or a signed URL. Keep the ID when you change the layout.

Assets is the supported managed path. Managed images can also come from assistant-generated images, charts, or diagrams, and from imported or copied templates.

The current editor and source save also accept external HTTP(S) <img src="..."> images without an asset ID. These images are not automatically added to Assets. Rendering still depends on the external URL being accessible.

Document template package export requires each image to reference a selected registered asset. To package an external image, upload it to Assets and insert the managed copy.

Ask the assistant to place images and text

For an uploaded image, use Assets → Insert first. Then ask the assistant to change its placement or add text. The assistant can reuse the inserted artwork; moving or resizing it does not require image generation.

Examples:

  • "Add a caption below the selected image. Keep the image unchanged."
  • "In this Data Merge template, place Quote Number and Customer ID over the existing banner. Keep the DCD merge fields and artwork."
  • "Move the quote fields to the upper-right area of the banner. Keep the rest of the header."
  • "Resize the existing logo to 120 pixels wide. Keep its proportions."

New artwork requires a request to generate it. The assistant saves generated artwork to Assets and places it only when you request placement. New foreground logos and artwork use transparent PNG backgrounds by default; a complete banner can use the background requested by the user. Uploading an image alone does not authorize replacement artwork.

After a placement change, check the canvas and PDF. A saved source change does not prove the final visual position or contrast.

Example: quote fields over a banner

This example assumes a dark banner that is 1920 × 616 pixels. Replace the asset placeholder with the real ID from your inserted image. Keep your own image dimensions if they differ.

The example also assumes your Data Context Definition (DCD) exposes quote.QuoteNumber and account.AccountNumber. Use the exact aliases and fields from your DCD; they are case-sensitive.

<div style="position: relative; width: 100%; background-color: #1f2937;">
  <img data-xp-asset-id="REPLACE_WITH_YOUR_ASSET_ID"
       alt="Company quote banner" width="1920" height="616"
       style="display: block; width: 100%; height: auto;" />
  <div style="position: absolute; left: 6.5%; top: 47%;
              width: 34%; color: #ffffff; font-size: 10pt;">
    Company name<br />
    Sales contact details
  </div>
  <div style="position: absolute; right: 7%; top: 43%;
              width: 38%; color: #ffffff; text-align: right;
              font-size: 10pt;">
    Quote #: {{ quote.QuoteNumber }}<br />
    Customer ID: {{ account.AccountNumber }}
  </div>
</div>
<p>Document content starts below the banner.</p>

Percentage offsets use the wrapper's dimensions. top: 43% measures down from the wrapper's top. right: 7% measures in from its right edge. Keep the image inside the wrapper and in normal flow so the wrapper has height.

Long field values can wrap or extend beyond the banner. Test realistic values and adjust the text block width, offsets, font size, or banner height. Check the selected PDF page size and margins.

For white text, use a dark solid fallback color on the wrapper behind the image, as shown above. The fallback can show through transparent areas or when the image is missing. It does not darken opaque artwork. Check the actual image and text contrast; move the text to a darker area or choose a readable text color when needed.

Partial rgba(...) colors and CSS opacity are not consistently supported in PDF output. Use solid hexadecimal colors for layout styling. Transparent PNG artwork is separate from CSS opacity.

Supported positioning styles after release

Style Allowed values
position relative or absolute
top, left, right Nonnegative px, pt, or % values; unitless 0
Offset limits Percentages up to 100%; pixel or point values up to 2000

Use these styles inline in the HTML source. bottom, z-index, fixed, sticky, negative offsets, expressions such as calc(...), and CSS image URLs are not supported by this pattern.

Troubleshooting

  • CSS stripped on save; text appears below the image: Compare source before saving with source after reopening. Confirm the updated server is deployed and that the styles use the allowed values above.
  • White text disappears: The text can be below the banner or outside it. Check the wrapper, saved positioning styles, offsets, and text color.
  • Image is missing: Confirm the asset is registered with this document or template and the image keeps its original data-xp-asset-id.
  • Merge field is blank: Check the DCD alias, included field, and Salesforce record value. Image placement does not supply missing data.
  • Merge tags appear as text: Confirm this is a Data Merge template and that generation uses the selected DCD and record.
  • Preview differs from PDF: Check the exported PDF with realistic data, page size, margins, and font settings. Browser preview alone is not final PDF validation.

Moving a Word DOCX header to HTML

A Word image behind text does not automatically become an HTML background. Upload the original artwork as an asset, insert it as an image, then recreate the text overlay in HTML. Keep dynamic fields out of the bitmap so they can merge and remain searchable.

For a layout that works before positioning support is deployed, use a borderless table with a separate logo, colored cells, and merge fields. This can require changes to the decorative artwork.

See Document Builder Template Tags for DCD aliases and merge syntax. HTML PDF Document Templates describes the separate Salesforce Flow file-template workflow.

Generated 2026-11-14T00:11:19.096211Z
DialogueOne Agent

Ask about this page, related knowledge or specific DialogueOne product and support features.