-imagePath

(As of 3.1.002.06)

Specify the locations where Merge should look for image files. It is also used for locating text resources.

Syntax

-imagePath foldername [;foldername2...] 

Description

Specify the folders where Merge is to look for image files identified in the data stream or via script settings. If your Form design defines a Field with a Display As type of Image, then the data found for such a Field is expected to be a file name. That image file name may or may not be fully qualified.

foldername, foldername2, ... identify the locations where the image files may reside.

When Merge is looking for a referenced image file it tries to find it in multiple ways. The algorithm used depends on whether the reference is for a field or for a label. It also depends on the type of image file name specification.

There are 4 types of image file references:

1. Absolute L:\BigImageBin\Logo.jpg
2. Relative: ./subsidiary/A/B/C/Logo.jpg (with or without the ./)
3. Naked: Logo.jpg

4. http[s]://–..Logo.jpg (This quickly turns into a temp file name, and thus a case 1).

An example of a common -imagePath specification is:

-imagePath $$F;$U/Images

BTW: Using . in the -imagePath is not recommended. It is meaningless. You really don't know what the current directory will be at the time that image selection is called upon.

Similarly, using $$D is frowned upon since a filtering operation may be performed independently before Merge is run and thus the data file that Merge processes is actually in the "temp" folder. You can use $$D but you are at risk.

As of 3.1.002.06

As of 3.1.002.06, we have attempted to make image file selection more definitive or at least more definitively explained.

Fields

If the image file specification contains an absolute path:

1. Try it as is, if found, use it
2. Strip all pathing off; get down to a leaf file name and extension.
   We strip off all pathing since the data stream may have been for an old Central system or for dev/test vs prod. Setting the -imagePath properly will overcome these situations.
   Append that leaf file name to each element of the -imagePath, if found, use it.
3. Not found – Issue an error message, identifying the field, and image. Note that only one error message will be issued per failing image file spec, regardless of how many times that same failing spec occurs in the run.

If the image file specification contains a relative path:

1. DO NOT try it as is. The user has no believable concept of what the current directory is.
2. Append that relative path to each element of the -imagePath, if found use it (e.g. we want it to find $U/Images/./subsidiary/A/B/C/Logo.jpg)
3. Strip all pathing off; get down to a leaf file name and extension. Append that leaf file name to each element of the -imagePath, if found, use it
4. Not found – Issue an error message, identifying the field, and image.

If the image file specification is a naked name:

1. DO NOT try it as is. The user has no believable concept of what the current directory is.
2. Append that leaf file name to each element of the -imagePath, if found, use it
3. Not found – Issue an error message, identifying the field, and image.

Labels

Typically label images are defined at Design time and remain static. The actual image is stored in the XATW and an _imageName property relates all instances of the image label to its stored image data.

However, a user could use script this._imageName = "[pathing/]xxxx.yy";. In which case, Merge must effect a correlation between the dynamically assigned _imageName and actual image data.

1. If there is an exact (case sensitive) full name match to any of the names in the XATW, we use it - we're done. This is expected to take care of 99.992% of the cases.
2. If scripting has occurred such that the above fails to find an exact match, then:
   1. Follow the same process as for fields for absolute paths and relative paths. -imagePath applies.
   2. For naked names, look in the XATW for imageData names that end in that naked name. Partial paths are not considered. The matching is case-sensitive, even on Windows.
   3. If not found yet, use the naked name as per the processing of a Field. -imagePath applies.
   4. Not found -- Issue an error message identifying the field and _imageName.

Note to Linux users. The Design tool is Windows-only and hence the image file paths that are browsed to will have Windows syntax. If you wish to refer to them via scripting be sure to use that Windows syntax to effect a match. BTW, you are in the .008% (or less) club.

Prior to 3.1.002.06

If the object being processed is a field or -preferImages is set to fromDisk the search order becomes:

1. Look for a file on disk with the exact name specified in the data file
2. Look for the file in each folder specified in -imagePath for the image file
3. Look in the list of embedded images in the form file for the image file (only the file name and extension count)

Otherwise, the search order becomes:

1. Look in the list of embedded images in the form file for the image file (only the file name and extension is considered)
2. Look for a file on disk with the exact name specified in the data file
3. Look for the file in each folder specified in -imagePath for the image file

See Also

-preferImages
HTML Image Embedding