This refers to the mechanism for placing a code into the merged document to show those places where data elements do not have a value (or, rather, have an empty value). This code is called the Empty Marker.
- There is a tab panel in the Configuration form, currently called “Other Settings”, and the Empty Marker can be set there. This means that the Empty Marker will apply to all templates run from that folder or any sub-folder deeper in the folder hierarchy.
- If the Empty Marker contains the character “^”, then when the Empty Marker is applied, the “^” will be replaced with the data element name. If you want a caret (“^” ) to actually be part of the empty marker text and NOT be replaced with the data element name, then you must escape it – i.e. use “!^”.
- The Empty Marker can be overridden in any template by use of the
«SetEmptyMarker()»command. For example,«SetEmptyMarker(‘{^}’)»will set that Empty Marker for all empty data elements in the template, regardless of whether or not another Empty Marker has been set in the configuration. - The
«SetEmptyMarker()»command can also specify a list of data elements to which it applies. For example,«SetEmptyMarker(‘[*^*]’,Name,Address)»will apply that Empty Marker to the Name and Address data elements. «SetEmptyMarker(‘’)»will cancel any previous setting of the Empty Marker. For example, if an Empty Marker has been configured for the folder from which the template is run then«SetEmptyMarker(‘’)»will negate that. Following that with«SetEmptyMarker(‘[*^*]’,Name,Address)»will mean that only Name and Address will have the Empty Marker applied to them. All other empty data elements in that template will cause an empty value in the merged document.- Empty Markers are applied only to data elements where the entire contents of the fillpoint is that data element. In other words, an empty value for Name in the example above will place [*Name*] in the merged document for a fillpoint
«Name». But fillpoint«ToUpper(Name,1)»will render as empty for an empty value of Name. If you want to show the empty marker (with the ^ character replaced with the data element name) when the data element is used in a function when that function value becomes empty, then you can use the function ShowFormattedMarkerWhenEmpty (the formatted refers to replacing the ^ with the data element name). The data element name to be used to replace the ^ must be the second parameter to the function: e.g.«ShowFormattedMarkerWhenEmpty(ToUpper(Name),‘Name’)»will cause [*Name*] (assuming an Empty Marker value of [*^*] has been set) to show in the merged document when Name is empty, but when Name has a value, then the uppercase of that value will appear in the merged document. (Please see the note below about version 9.3) «ShowMarkerWhenEmpty(ToUpper(Name))»: when Name is empty, this will show the empty marker without replacing the ^ (if there is one) with anything. (Please see the note below about version 9.3)
When the Empty Marker is set in the template (as against in the configuration), it must be set in the template before any data elements to which it applies. In points 3 to 7 above, it is assumed that the Empty Marker has been set (either in the configuration or with a SetEmptyMarker command) prior to the ShowFormattedMarkerWhenEmpty or ShowMarkerWhenEmpty are used.
Improvements with Version 6.1.0
These improvements include the following:
- XpressDox is now able to recognize data elements within functions and apply the empty marker where relevant. For example, the fillpoint
«ToUpper(Name,1)»will now show the empty marker if the data element Name is empty. It is no longer necessary to use ShowFormattedMarkerWhenEmpty in this case. However, if the reference to the data element is more complex, e.g.«FormatNumber(Amount * 0.1)»(which will calculate 10% of Amount), then if Amount is empty, the fillpoint will put ‘0.00’ into the document. In this instance the command«ShowFormattedMarkerWhenEmpty(FormatNumber(Amount * 0.1),‘Amount’)»will show the empty marker when Amount is empty. - The SetEmptyMarker command not longer has to appear before the data element(s) that it affects – i.e. it can appear anywhere in the template.
- In the folder My Documents\XpressDox\Samples there is a document called PaintEmptyMarkers.docm. This document contains a Word macro that can be used to “paint” any empty markers in the assembled document. What is required is that
- the macro must be modified to reflect the format of the empty marker(s) that you will be using, and the colour(s) with which they should be embellished;
- the macro should then be saved either into the Normal template (Normal.dotm) or into the template where it is to be used (probably this is better in a multi-user environment, to avoid having to install the macro into all the potential users’ Normal templates);
- and then the command
«RunWordMacro(PaintEmptyMarkers)»placed in the template will cause the macro to be run after the document as been assembled, and the empty markers nicely colored.
Improvements with Version 8
With Version 8, it is no longer necessary to run a Word macro to “paint” an empty marker. This can be achieved using the following syntax:
«SetEmptyMarker('[~cyan~@~]')»
This will colour the “@” character in the colour cyan, while leaving the “[” and “]” in the ruling document font.
Other variations would be:
«SetEmptyMarker('[~red~^~]')»
«SetEmptyMarker('[~magenta~***~]')»
The Command Editor wizard has a drop-down with a list of the colours available to this command.
Note that the Empty Marker feature is available only in Version 4 and later of XpressDox.
Improvements with Version 9.3
- In the situation where a calculation occurs where one of the data elements in the calculation is empty, the result of the calculation will be the string “NaN” – meaning “Not a Number”. This special string, when encountered by the FormatNumber function, will be regarded as an empty string and the relevant empty marker will be input into the assembled document.
- The ShowFormattedMarkerWhenEmpty and ShowEmptyMarker commands are no longer necessary.
