Images

In some cases you might want to replace images in your docx template. For example you might want to replace a logo with a customer specific logo. The standard mergefields within Word, do not offer a solution for this, but with LabraDocs you can replace images in your docx templates.

How to use it

You need to mark the image in your docx, so LabraDocs can match and map the image in the docx with the image in the data. You can do this by marking the image a name inside the "ALT TEXT" field.

note

The size and width of the image from the docx template will be used for the replacement image.

Data format

On the data side, you need to define the mappings between the image name you just provided, the image file itself and the alternative texts for accessibility support. Take a look at the following examples:

Single file

In case you prefer the single file format, everything is embedded in the JSON file, which is passed to the API endpoint. The JSON file contains the following fields:

{
    "template": { /* template data; see more info in the API reference*/ },
    "images": [
        {
            "name": "LOGO",
            "base64": "iVBORw0KGgoAAAANSUhEUgAAABQAAAAUCAYAAACNiR0NAAAABGdBTUEAALGPC/xhBQAAACBjSFJNAAB6JgAAgIQAAPoAAACA6AAAdTAAAOpgAAA6mAAAF3CculE8AAAABmJLR0QA/wD/AP+gvaeTAAAACXBIWXMAAAsTAAALEwEAmpwYAAAAB3RJTUUH5gkPDBsXekWXIQAAA2VJREFUOMttlE+IVlUYh5/33HPu/WYGGUehlTGbVqVlm4gWkgRBhEGuctMi+mMNSSVFmwqiEkGlCGpR2MoEoVIiB6KNi6JaaESrduFC6M+EYJ8zc855fy3u/eYbywtndeG5v/f3vPcYmx6dugscI9iiYD+wD9lOZNukRvLmT9X4k2o6q5rONWntSskdo2e/3mDYFLYbYBZ0AOyQ4A6gQQF5QN4gj6gmVFNWSRe9dMc9d+cs+Prc4TNToD7dDWIB9CZmT0l0/Vd6GGpQjahGvCZUW7y0KHfXvHQnfH3mKFbH8699jA3JZkBHMVuSCD3MkAJsJBtgpdUAMy8jPHfZS/dWvb7lnZBWSwCB6QBmT98cNk3Xjxt/xOOTXrovPXfF8ygpdy9hekg1ETEWwZ6fjmmgMIzbVHlzXgqX5Y2ppL0q7Vpdn1v20n7mefShl+6ASjuvml6oJX0XgEcRO6ewPl0vockovBdnry55nnnRy+iCl26PavpCNW73PHNSpV310uKlvVceH4hg+wRxIl3/sYpCXf1j8XbUHFdJd3rp8Nzd43l0TCWuDNZRTbPy5uEoseu/RvEIQ28oSJ62yps9XttZz92qarqomnbJ42299Yhqg7y5OwDb+jFt0hvyBh92zksyzy3KXX9q+hZ4xPPotGrqN8Aj8gbU3BLBlmCATWSomRiuePhVHh2Ph+TRUbiQr20PyPZO7NPDkAJRNZ6Vh7jxF5RhcXOHl06qzV/lnwWhZtlzG1TbRWRH5PE+eZyuVh/m94jsGNj9yBzZIMYm67OGwuNgGXEKbE6yeXnY0ncWN8OQ7FKUwkV585g8TlPWFu9/r1XVZqSSgtTcqppm+97S/2DIxsBXQR4/p8ZfVCMqCS8JL8PIucPLSF7b/t2NRsE3YAi+R3wT6nj+N6/pfdW02nfYotyi0g2nHXodYBtGJxINwVXEu2asBMxB4bRK+5GX1r10TM9wq3gPY7NRn8AsI04AyxKE0dIyZbz1utf4hpfuAy/dWj9quyndNNkNvWHXEEfAjoGVHScP9rfL3OEzlPHC36rpFZX2OdX2Z5W2ek2mmuwmRrOwHySeAHsbGO84+cyNNzbAyqsvM1q4bOOVxUWVbr/X9kE8vF7XZxOy83izKoVLKJyVOGcNV1RgxycHNxj/AigPt2r5yetCAAAAJXRFWHRkYXRlOmNyZWF0ZQAyMDI0LTAxLTE4VDE2OjAwOjM2KzAxOjAwG2NKsQAAACV0RVh0ZGF0ZTptb2RpZnkAMjAyMi0wOS0xNVQxMDoyNzoyMyswMjowMI5WCuMAAAAASUVORK5CYII=",
            "alt": "Pathfindr logo",
            "title": "Pathfindr \u00a9"
        }
    ],
    "data": {
        "HEADING": "This is a dynamic HEADING",
        /* ... */
    }
}

Separate files

Let's start with the generic.json file where we define the image mapping withing the other data fields

{
    "CUSTOMERNAME": "Jens Jensen",
    "CUSTOMERADDRESS": "...",   
    "LOGO": {
        "src": "logo.png",
        "alt": "Pathfindr logo",
        "title": "Pathfindr ©"
    }
    /** ... */
}

Naturally you also need to supply the logo.png itself when making the request

curl --location --request POST 'http://localhost:8000/docx2pdfua' \
     --form 'template=@"/home/pathfindr/example/generic.docx"' \
     --form 'data=@"/home/pathfindr/example/generic.json"' \
     --form 'images=@"/home/pathfindr/example/logo.png"' \
     --form 'images=@"/home/pathfindr/example/another-image.png"' 

note

You can supply multiple image files under the "images" field

For more examples, please take a look at the separate file examples or single file examples.

Missing images

If you want to remove the image placeholder, when the image is missing, you can use if conditions. For example:

«if someImage == True» {image placeholder} «endif»

someImage is the name the description of the image in the docx template.

note

The name of the image should not be defined in the data section of the docx2pdfua request. Valid image names are automatically inferred from images section of the request or from the image mapping in the single json file.

If you want to know more about conditions, please read the Conditions and loops chapter.