_profile (Access Profile Files)
DocOrigin allows the use of simple text Profile files (".ini" or "INI" files) to provide data that can be loaded via script. This mechanism can be used to customize your form design using an external file.
A Profile file is one that is typically loaded via Merge command line option (-profile) prior to any document or script processing. (As of 3.1.002.10) There is also a _file.readIniFile function which is recommended if you wish to simply read a INI file into your JavaScript code.
True profile files offer "automatic actions". See Profile Files. Please differentiate, in your mind, ordinary INI files from true, action-oriented, profile files. You can continue to use _profile with ordinary INI files but remember that each _profile.load() wipes out any earlier profile info. It may curtail the functionality of the data-driven, per document, actions specified in a previously loaded profile. It may cause [!profile xxx] embedded field definitions used in the form, but long forgotten by the scripter, to fail. Definitely consider using the _file.readIniFile function.
On the other hand, it may be that the true profile file that you want to load will be determined by values in the data stream. E.g. you may wish to load the profile for Acme2 instead of the usual one for Acme. You cannot specify the needed profile file name on the Merge command line. So it still makes perfect sense to use _profile.load() to load a true profile file. Do so during the Start-of-Job event as it is in only that scenario that the [*action] automatic actions will be performed. (Of course, they are also performed if the -profile command-line option is used.)
Profile File Format
Profile files are simple text files. The file is required to contain either UTF8 or plain ASCII characters. The files consist of lines of key=value settings. One can optionally add a [section] name which indicates that all key assignments that follow are to be considered part of this section name. For example:
; An example profile file. (any text following a semicolon is a comment) ; Blank lines are ignored Name=Joe Smith [Address] city = San Jose state = "California"
Any name=value pairs before the first (if any) [section] line are considered part of the "default section", which internally has the section name "". You can continue the definition of the default section after other sections by using a section specification of []. The key names can be any string of characters, although it is recommended that they be alphanumeric for clarity. Blank lines and comments can be interspersed throughout the file. The value can optionally be contained within quotes (double or single). The value strings are stripped of leading and trailing blanks or tabs. If leading/trailing blanks are required you must quote the string in order to preserve the blank. Within the value string you can use the following special sequences:
\\ - is replaced by a single \ \n - is replaced by a newline (hex 10) character \r - is replaced by a linefeed (hex 13) character \t - is replaced by a tab character \E - is replaced by the escape character (hex 1B). \xnnnn - the 4 digits nnnn are interpreted as a single hex unicode character.
(As of version 3.1.002.06) Multi-line values can also be defined using "heredoc" notation, as in:
Address = <<<END 123 Sesame St, San Jose, California END
The END in the above example can be any text you like. All text up to the first line with that same text string at the start of a line is assigned to the key name.
Profiles can also contain directives to "include" another file:
; the following loads the contents of master.ini as well. @master.ini ; this conditionally loads 'secondary.ini' ; it does not complain if the file does not exist. @@secondary.ini
If an explicit file path is not given, the file is assumed to be in the same directory as the profile file it was referenced from.
Text Substitution [Define]
(As of 3.1.002.04)
Profile files support a mechanism to create shorthand names for longer paths or other text that is repeated, possibly many times, within the files. The [Define] section is used for this purpose
[Define]
mypath = //server3/share7/AppName/Archives/MyTests
[]
myfile = {mypath}/myOutput.pdf
Everywhere within the profile file processing where a name is found between {} (braces), it will be replaced by the text defined within an earlier [Define] section. If the name within the braces is not found, the original text (and braces) will remain as-is.
Opening a Profile File
_profile.load(filename)
Opens a new profile file and replaces any currently stored profile settings. No return code is provided. You may want to check for the file's existence beforehand.
Accessing Profile File Settings
You can access a profile file setting with the following script function:
_profile.get(key[, section]);
The section name is optional and required only for values that are stored under a profile section name. Section names and key names are case-insensitive.
this._value = _profile.get("Name"); // set to "Joe Smith" using the above profile file.
this._value = _profile.get("city", "Address"); // set to "San Jose" using the above profile
If the desired key does not exist then null will be returned.
Enumerating Section keys
You can enumerate the names of all keys within a section using the following two calls:
_profile.getFirstKey(section);
Returns the first key in the section or null.
_profile.getNextKey();
Returns the next key in the section or null.
Typical usage might be:
for (k=_profile.getFirstKey('abc'); k; k=_profile.getNextKey()) {
... do something with key k
}
To enumerate the keys before the first (if any) [section] entry, use "" as the section name. Note that only one _profile enumeration may be in progress at a time. Calling _profile.getFirstKey will cancel any current enumeration processing.
Enumerating all Sections
_profile.getFirstSection();
Returns the first section name in the profile or null.
_profile.getNextSection();
Returns the next section name or null.
Note that the default section name is "", so the section name returned may be a zero-length string. Your test for completion must distinguish between a null/empty string and null itself.
for (s=_profile.getFirstSection(); s !== null; s=_profile.getNextSection())
_message("next section name is '%s'", s);
Extended Profile usage within Merge
See the Profile Files section of Merge for additional Merge-only features and handling of profile files.
