Insert Images - Dynamic Image Guide

PDF4me enables dynamic image insertion within generated documents, allowing you to populate templates with logos, photographs, charts, diagrams, and other visual content from your data sources. Images can be provided via public URLs or Base64-encoded strings.

---

Image Syntax Requirements

The image syntax must be placed inside a Text Box in Word for proper image population. Create a text box at the desired location in your template before adding image merge fields.

---

Image Insertion Methods

PDF4me supports two methods for providing image data to templates:

Method 1: Public Image URL

Use publicly accessible image URLs to insert images from web sources.

Syntax:

<<image [imageUrl]>>

Data Example:

{
  "imageUrl": "https://public-url/image.png"
}

Use Cases:

• Company logos hosted on public servers
• Product images from e-commerce platforms
• Charts and graphs generated and hosted online
• Public resource images

---

Method 2: Base64 Encoded Images

Insert images using Base64-encoded string representation of the image file.

Syntax:

<<image [imageBase64]>>

Data Example:

{
  "imageBase64": "iVBORw0KGgoAAAANSUhEUgAAAfQAAAH0CAYAAADL1t+KAAAACXBIWXMAABcSAAAXEgFnn9JSAACU6ElEQVR4nOz953tjR5bn+34jtoMn6D2ZSaaRL5lSmR5z5t5/+9xzZqZ7qktSeksmvfcG3mzsveO+2ACVUklKUspMksj1eZ7qqpZECCCZ+CEiVqyljDEGIYQQQlxr+rKfgBBCCCH+OAl0IYQQogtIoAshhBBdQAJdCCGE6AIS6EIIIUQXkEAXQggh..."
}

Advantages:

• Works without internet connectivity
• Secure - no external dependencies
• Complete control over image data
• Suitable for sensitive documents

---

Image Formatting Options

Control how images fit within text boxes using formatting switches. These options determine image sizing and aspect ratio behavior.

Keep Aspect Ratio

Syntax: <<image [imageUrl] -keepRatio>>

Behavior:

• Preserves the text box size
• Scales image to fit within text box bounds
• Maintains original image aspect ratio
• Image may not fill entire text box if ratios differ

Best For: Logos, icons, and images where distortion must be avoided

---

Fit Height

Syntax: <<image [imageUrl] -fitHeight>>

Behavior:

• Preserves text box width
• Adjusts text box height to match image aspect ratio
• Image fills text box completely
• Text box dimensions change to accommodate image

Best For: Variable-height images in flexible layouts

---

Fit Width

Syntax: <<image [imageUrl] -fitWidth>>

Behavior:

• Preserves text box height
• Adjusts text box width to match image aspect ratio
• Image fills text box completely
• Text box width changes to accommodate image

Best For: Horizontal banners, headers with fixed heights

---

Fit Size

Syntax: <<image [imageUrl] -fitSize>>

Behavior:

• Changes text box dimensions to match image size
• Uses original image dimensions
• Image displays at actual size
• Text box resizes to exact image dimensions

Best For: When original image size should be preserved exactly

---

Fit Size Limited

Syntax: <<image [imageUrl] -fitSizeLim>>

Behavior:

• Adjusts text box to image size
• Will not increase beyond original text box dimensions
• Can shrink text box if image is smaller
• Prevents text box enlargement

Best For: Constraining maximum image size while allowing smaller images

---

Formatting Comparison

Format Option	Width	Height	Aspect Ratio	Text Box Size
-keepRatio	Fixed	Fixed	Preserved	Unchanged
-fitHeight	Fixed	Variable	Preserved	Height changes
-fitWidth	Variable	Fixed	Preserved	Width changes
-fitSize	Variable	Variable	Preserved	Both change
-fitSizeLim	Variable	Variable	Preserved	Constrained

---

Practical Examples

Example 1: Company Logo

Template:

[Create a text box in header]
<<image [companyLogo] -keepRatio>>

Data:

{
  "companyLogo": "https://company.com/images/logo.png"
}

---

Example 2: Product Images

Template:

<<foreach [product in products]>>
Product: <<[product.name]>>
[Text box:] <<image [product.imageUrl] -fitHeight>>
Price: $<<[product.price]>>

<</foreach>>

Data:

{
  "products": [
    {
      "name": "Laptop Pro",
      "imageUrl": "https://example.com/laptop.jpg",
      "price": "1299.99"
    },
    {
      "name": "Wireless Mouse",
      "imageUrl": "https://example.com/mouse.jpg",
      "price": "29.99"
    }
  ]
}

---

Example 3: Signature Image (Base64)

Template:

Authorized Signature:
[Text box:] <<image [signatureBase64] -fitSizeLim>>

Name: <<[signatoryName]>>
Date: <<[signatureDate]:"dd.MM.yyyy">>

Data:

{
  "signatureBase64": "iVBORw0KGgoAAAANSUhEUgA...[truncated]",
  "signatoryName": "John Smith",
  "signatureDate": "2024/01/15"
}

---

Image in Tables

Combine image insertion with table structures for organized visual presentations.

Product Catalog Table

Template:

Product | Image | Price
<<foreach [item in catalog]>>
<<[item.name]>> | [Text box: <<image [item.imageUrl] -keepRatio>>] | $<<[item.price]>>
<</foreach>>

---

Conditional Image Insertion

Insert images only when image data is available.

Optional Logo Example

Template:

<<if [logoUrl != null]>>
[Text box:] <<image [logoUrl] -keepRatio>>
<</if>>

Default Image Fallback

Template:

<<if [productImage != null]>>
[Text box:] <<image [productImage] -fitHeight>>
<<else>>
[Text box:] <<image [defaultProductImage] -fitHeight>>
<</if>>

---

Multiple Images in Document

Generate documents with multiple dynamic images from a single data source.

Example: Report with Charts

Template:

Sales Report - <<[reportMonth]:"MMMM yyyy">>

Revenue Chart:
[Text box:] <<image [revenueChartUrl] -fitWidth>>

Expense Chart:
[Text box:] <<image [expenseChartUrl] -fitWidth>>

Growth Chart:
[Text box:] <<image [growthChartUrl] -fitWidth>>

---

Image Quality Considerations

Best Practices for Image URLs

1. Use HTTPS - Secure URLs prevent security warnings
2. Permanent URLs - Ensure URLs remain accessible
3. Appropriate size - Use images sized appropriately for output
4. Format compatibility - Common formats: PNG, JPG, GIF
5. CDN hosting - Use reliable content delivery networks

Best Practices for Base64 Images

1. Optimize file size - Compress images before encoding
2. Use appropriate resolution - Match intended output resolution
3. Consider data size - Large Base64 strings increase payload size
4. Format selection - PNG for transparency, JPG for photographs
5. Encoding quality - Ensure proper Base64 encoding

---

Text Box Setup in Word

Creating Image Placeholders

1. Insert Text Box:

   • Word Ribbon → Insert → Text Box
   • Draw text box at desired location
   • Size text box to approximate image dimensions

2. Configure Text Box:

   • Remove text box borders if desired
   • Set text box fill to "No Fill" for transparency
   • Configure text wrapping as needed

3. Add Image Syntax:

   • Click inside text box
   • Type image merge field syntax
   • Add appropriate formatting option

---

Troubleshooting Image Insertion

Common Issues

Issue: Image doesn't appear in generated document
Solution: Verify image syntax is inside a text box, not regular paragraph

Issue: Image appears distorted
Solution: Use -keepRatio to preserve aspect ratio

Issue: Image too large or too small
Solution: Adjust text box size or use appropriate fit option

Issue: Base64 image fails to load
Solution: Verify Base64 encoding is complete and valid

Issue: URL image doesn't load
Solution: Check URL accessibility, ensure HTTPS, verify image format

Issue: Image position incorrect
Solution: Reposition text box in Word template

---

Advanced Image Techniques

Responsive Image Sizing

For documents that may be viewed at different sizes:

[Large text box:] <<image [headerImage] -fitSizeLim>>

This allows the image to shrink if needed but won't expand beyond the text box bounds.

Image with Caption

Template:

[Text box:] <<image [chartUrl] -fitWidth>>

Figure <<[$index + 1]>>: <<[chartTitle]>>
Source: <<[chartSource]>>

Conditional Image Formatting

Choose formatting based on data properties:

<<if [imageOrientation == "landscape"]>>
[Wide text box:] <<image [imageUrl] -fitWidth>>
<<else>>
[Tall text box:] <<image [imageUrl] -fitHeight>>
<</if>>

---

Complete Example: Product Sheet

Template:

<<[productName]:caps>>

Product Image:
[Text box 300x300:] <<image [productImageUrl] -keepRatio>>

Specifications:
• Model: <<[modelNumber]>>
• Category: <<[category]>>
• Price: $<<[price]:"F2">>

Additional Images:
<<foreach [img in additionalImages]>>
[Text box 150x150:] <<image [img.url] -keepRatio>>
<<[img.caption]>>
<</foreach>>

Company Logo:
[Text box 200x60:] <<image [companyLogoBase64] -fitHeight>>

---

Image Optimization

For best results, optimize images before including them in your data source. Resize images to appropriate dimensions and compress them to reduce file size while maintaining quality.

Text Box Requirement

Images MUST be inserted inside Text Boxes in Word templates. Image syntax in regular paragraphs will not render images correctly. Always create a text box placeholder for each dynamic image location.