This command enables the insertion of graphics from a file into the merged document.
The picture is inserted into the document at the point where the command is encountered, and the size of the image is included in the command. Use IncludePicture when you know the name of the graphic you need to include, and use InsertPicture when you need to provide a variable file name and dimensions.
Often the file name of the image file is not known until the interview has been completed and the merged document is being created. Typically, the user might select one or more people from a personnel database and will know from that the file name of a picture of that person. If the data element containing the file name is, say, PictureFile, then the following will include that picture in the merged document:
«InsertPicture(PictureFile,0.8in,1in)»
or, if the picture file is based on the person’s name:
«InsertPicture(concat(PersonName,'.jpg'),0.8in,1in)»
The width and height can also be supplied via a data elements or even function calls – for example where the pictures may have different dimensions and these are provided in data read from a database:
«InsertPicture(concat(CompanyName,'.jpg'),Width,Height)»
If the Width and Height data elements contain the width and height values in centimetres (the default is inches), then the following would work:
«InsertPicture(concat(CompanyName,'.jpg'),concat(Width,'cm'),concat(Height,'cm'))»
Aspect Ratio
Regardless of the dimensions specified in the IncludePicture command, XpressDox will maintain the aspect ratio (ratio between Width and Height) of the original image. This will ensure that the image will always fit into the rectangle in the document which is defined by the Width and Height arguments in the command, but it will nonetheless maintain its original aspect ratio, and not be stretched or compressed “out of shape”.
Note that if the picture file can’t be found, then this is not regarded as an error – the command is then ignored.
The dimensions of the picture must be supplied in a format conforming to the regional settings of the computer on which the template is run. If this means that the decimal separator is a comma, for instance, then the first example would have to be «IncludePicture(images:Logo.jpg,'0,8in','0,8in')». If a template is to be run from the same location but by users with different number formats for their regional settings, then it should be run for the first time by a user with the “correct” regional settings for the number format used in the template. See Understanding XpressDox Artefacts for an explanation.
