JavaScript Filters

Script-based JetForm data to XML You may use as is, or copy and edit
Script based comma separated to XML Use as is, or copy and edit.
xfilter scripts via FilterEditor See Filter Editor.
XMLAttrs Filter Expose XML attributes as tagged data
Any filters that you write – they are easy.

Writing filter scripts

Using the JavaScript language you can code your own custom filter to convert data into XML. The -filter command must specify a JavaScript file (typically with a .wjs file extension). You must specify the script file (.wjs) using the -filter command as in:

... -filter "C:/DocOrigin/User/Scripts/MyFilter.wjs ..."

Script Filter Options

When Merge runs a script-based filter it supplies a -in option and a -out option. If multiple filters have been defined, Merge takes care of passing the 'out' of one filter to the 'in' of the next filter. The first filter normally gets the data file as its 'in'. Even there you can't be sure that Merge didn't have to do some of its own earlier processing which resulted in a temp file. So use the -in option as the safer bet.

When run as a filter, the -in and -out options are NOT found in _job.command.in and _job.command.out. Instead, they are found in _job.filter.in and _job.filter.out.

As it happens, one doesn't usually make use of the -out option because you are more likely to use the _xml object that is also provided to a filter when it is run by Merge. The _xml object makes it easier for you to generate XML, and in general, that is the target that all filters are aiming for.

Standalone usage of script filters

It's great that Merge can run filters. It is also useful to be able to run them independently of Merge. Some effort is required to support both usages as a Merge filter and usage as a standalone script. The following script snippet will likely show you the score.

var dataFile;
if (typeof _job.filter != "undefined")
    dataFile = _job.filter.in;              // Presume use as a Merge filter
if (typeof dataFile == "undefined")
    dataFile = _job.command.in;             // Fallback for standalone usage
if (typeof dataFile == "undefined")
    dataFile = _job.datafile;               // Well, lazy standalone usage

Similarly, one may wish to know the -out option that is in force, if for no other reason than to use it in some log messages that you may issue.

var outFile;
if (typeof _job.filter != "undefined")
    outFile = _job.filter.out;              // Presume use as a Merge filter
if (typeof outFile == "undefined")
    outFile = _job.command.out;             // Fallback for standalone usage
if (typeof _xml != "undefined")
    outFile = _xml.getFileName();           // A defined _xml is definite 'source of truth'.
if (typeof outFile == "undefined")
    outFile = _file.getFileNamePart(dataFile, "NoExt") + ".xml";   // A possible default (you choose)

Within a filter, there is a pre-defined object called _xml which is used to specify the xml output of the filter. See the XmlFile Class for details on the generation of xml output. However, for standalone usage, you will need to create that _xml object yourself. As in...

if (typeof _xml == "undefined")
    _xml = new XmlFile(outFile, true);     // see above for outFile computation

With those code snippets in place you can happily run / test your filter in standalone mode:

RunScript -script MyFilter.wjs -in ....

Processing within a script

All of the standard DocOrigin scripting extensions listed in the Scripting section are available when running a Merge filter script.

A classic filter processing loop would be:

var fp =_file.fopen(dataFile, "r");
while (true) {
    line = fp.fgets();
    if (line == null) break;
    ... work out a name / value pair
    _xml[name] = value;
}
fp.fclose();
_xml.close();

A script Filter can also reset the name of the form that is being processed. Use the

_setForm("newFormName");

script function to reset the form to be used.

The script's return value

1 (true) means success, 0 (false) is failure

The Filter script must indicate whether the conversion was successful or not by returning true if it succeeded or false if the file cannot be converted. Use the JavaScript return true; or return false; statement to return this value.

In most places a return 0; is good, BUT NOT HERE. For script-based filters, you must return 1; or return true; to indicate success.