Merge allows the use of simple text Profile files (or "INI" files) to provide data that can be load (or preloaded) into your Merge run. This mechanism provides a simple way to configure or customize a form definition externally, without needing to alter the actual form template in Design. This can be helpful when a single form is customized for different user groups such as branch offices or departments.

A Profile file is one that is typically loaded via the Merge command line option -profile prior to any document or script processing. There is also a _file.readIniFile function which is recommended if you wish to simply read a .ini file into your JavaScript code.

Profile File Format

See the _profile (Access Profile Files) section for details on the file format. Profile files look like .ini files but have additional capabilities as described below.

Opening a Profile File

As well as using the script _profile.load() function you can specify a Profile file to be opened by Merge by using the command line option

-profile filename

This will open the specified profile file at the start of the Merge process. The data will remain available throughout the Merge run unless a different file is opened using the script _profile.load(filename) call.

Profile Values as Merge Embedded Fields

The DocOrigin Merge program allows additional Profile features that are not available in other DocOrigin Modules. Profile settings can be referenced via the DocOrigin embedded field mechanism. See Auto/Embedded Fields. This allows values to be automatically inserted into text Labels and Fields when Merge is run. For example, a text Label might be defined as the string:

Label = The city of [!profile Address.city] in [!profile Address.state].

which at runtime, using our example, would be converted to:

The city of San Jose in California.

Note that the [!profile] definition uses a dot to separate the profile section name from the key. This embedded substitution may also be used in Field initial values as well as actual Field values.

Using a Profile to Modify Form Objects

A powerful feature of the Profile is its ability to modify or customize a Form template in Merge. You can use a profile to modify text Labels, fonts, and colors as well as re-position certain objects on the page. These features can be used to allow a single form design to be customized to a particular customer's name, address, logo, etc. without the need of either JavaScript or modifying the form in Design. While not as powerful or flexible as actual form re-design, this feature can be used where a standard, stock form requires minor tailoring for various clients or uses.

In essence, these are actions that modify a Form's design as Merge is initializing. Each action performs some sort of action on a selected object in the form.

Another use of these customization features is the ability to create a single form which is to be presented in several languages. Each of the fixed titles, field names, etc. can be re-assigned a new (translated) value when Merge runs. Using a simple bit of scripting one can even dynamically choose the language at run-time based on an incoming field value.

There are several pre-defined profile section names that trigger these dynamic actions. All these special section names are preceded by an asterisk - as in
[*Font].

[*Assign] - assign new text to a Label or Field

[*Assign]
; Assign a value to a Field, Label, or Image.
Pane1.Prompt = "Approved by:"
Address = DocOrigin Corp.\n2364 Pollock Rd\nYourtown, Ont.
Logo = $U/Logos/YourTown.jpg

The above would search for a Field or Text Label called Pane1.Prompt and change its value to "Approved by:". Similarly, the Address, a multi-line label, is reset. The static image object called Logo is changed to display the given image file.

If you use the *Assign mechanism to modify a Field value, it effectively sets a (possibly new) default value for the Field. The subsequent merging of data into the form will of course override this default provided that there is in fact data for that specific field name.

[*Color] - Change an Object's Color(s)

[*Color]
; Reset color of an object.
; <foreground>, <background>, <border>, <shading pattern>
; Patterns are horizontal vertical crosshatch diagonal reversediagonal diagonalcrosshatch

Footer = white,black
Declaration = , #ddd, #ddd, diagonal

The above settings will change a label named Footer to display white text on a black background. The Declaration label will change it's background to a diagonal-stripe of color #ddd (a light gray) and also turn on a border of the same color. See the Colors page for information on built-in colors and defining arbitrary colors.

Note that *Colors can set the color of any object - rectangles, panes, lines, etc. as well.

[*Font] - Change Field or Label Font Settings

[*Font]
; Reset font information for a Field or Label
; <typeface>,<point size>, <B/I/BI>, <horizontal justify>, <vertical justify>
; if value omitted, it remains the same as in the design.
; <horizontal justify> can be left, right, center, spread, or spreadall
; <vertical justify> can be top, middle, or bottom

Address = Courier New, 9pt, B, right
Pane1.Prompt = ,12  

The above will change the Address string to use Courier New font, 9 points, and bolded. It also right-justifies each line of the address. The Pane1.Prompt string is changed to 12-point text, with other font settings left untouched.

Note that *Font changes will NOT work for Text Labels that have embedded font changes (RTF) already in them.

[*Visible] - Show or Hide an Object

[*Visible]
; Change an object's visiblity
;  = N or No - to make invisible
Footer = No
Declaration = Yes
Address =
TearOffLine = N  

The above settings make the Footer invisible, Declaration visible, and leaves Address unchanged. The object (presumably a line object) named TearOffLine is also made invisible.