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: The positioning support described below is implemented locally and awaits server deployment. It is not yet confirmed in a live org. 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
- Open Assets in the left navigation.
- Upload a PNG or JPEG image, up to 1 MB. Upload saves the asset but does not insert it.
- Select Insert for that asset.
- Open the HTML source and keep the inserted image's
data-xp-asset-id. - 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.
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%;">
<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.
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.