FilterEditor JavaScript

One of the Steps you can perform on an Extraction or an Action is the JavaScript step. This allows you to insert a line or a whole block of JavaScript to be executed. Using this script you can access the currently selected line or lines of text, change them, access the current output XML tree, and other text lines in the source file.

A set of access functions are pre-defined to allow you to access various settings and values within the transformation processor. And you also have the option to define your own custom functions.

Custom Functions

You can use the FilterEditor Filter>Edit Script... menu item to define additional "helper" JavaScript functions that can be called from a JavaScript action.

As an example, you could add the following JavaScript function to remove commas from a numeric string:

function removeCommas() {                  // remove commas
    var text = $$GetText();                // get current selection
    var newtext = text.replace(/,/g,'');   // remove commas
    $$SetText(newtext);                    // update selection
}

In the above...
$$GetText() is a built-in xfilter function to let you access the selected text for this Extraction.

$$SetText(theText) is a built-in xfilter function to update that selected text – not on the source file canvas, but in memory such that subsequent Steps, such as Store as Field would be using that updated text.

Now that you have defined your custom function, how do you use it?

Besides the Filter>Edit Script... menu item, you can provide some JavaScript in two places.

1. If you were to right-click on a Rule or on an existing Action under a Rule, you could use the Add Action... context menu entry, and thence select "JavaScript Execute some JavaScript code". You will get an edit window that allows you to add the script.
2. If you were to right-click on a step of an Extraction Action, you could use the Add Action Step context menu entry, and thence select "JavaScript Execute some JavaScript code". You will get an edit window that allows you to add the script. A typical place to do this is by right-clicking on the Trim Blanks Extraction Action step.

What if you want to edit your script?

In either of the above two cases, you will see an Action or an Action Step that is led off by the word JavaScript. Click on the area to the right of the word JavaScript and you'll get an edit window that allows you to view or edit the script. As you exit that window FilterEditor will automatically "compile" the script and check for common JavaScript syntax errors.

It could look like this:

FE Custom JavaScript Call

Notice how easy it was to invoke your pre-defined custom function.

All the standard DocOrigin add-on functions are available - including _message(), _logf, _file, XmlClass, etc. By default, FE produces its own log file named FilterEditor.log.

FilterEditor Functions

A number of additional functions are available within the xfilter scripting world. These routines are used to access or modify the processing of the transaction processor.

$$Advance(n) - causes the transformation processing to skip forward in the source file "n" lines.

$$GetActionNumber() - returns the current Action's number. Useful for debugging messages.

$$GetCurrentState() - returns the State name that the current Rule matches - that is, the State name(s) from the "If State is" section of the Rule.

$$GetField(name) - get the text currently assigned to field name in the output XML tree. This will retrieve the current or most recent value assigned to name. name can be either the "leaf" or field name, or a full dotted syntax such as "Header.Address".

$$GetLineCount() - returns the number of lines in the entire source file.

$$GetLineNumber() - returns the current line number within the source file. Useful if you're logging or displaying an error message. NOTE - lines are numbered starting with 0 as the first line in the file.

$$GetNextState() - returns the name of the next state the current rule will transition to. Useful for debugging messages.

$$GetRuleAnnotation() - returns the annotation text associated with the current rule (or null). Useful for debugging messages.

$$GetRuleNumber() - returns the Rule# of the current rule being processed. Useful for debugging messages.

$$GetText() - returns the current Selection text. If the selection is a single line (typical) that string is returned. If the selection spans multiple line$$Ges, an array of strings is returned.

$$GetTextLine(n) - fetch the nth overlay line relative to the current rule's trigger line. This function returns the entire "raw" input line but without the trailing newline (\n) character. n can be negative.
$$GetTextLine(-$$GetLineCount()) will return the very first line in the file.
$$GetTextLine(0) will return the line that caused the state assignment rule to trigger.
$GetTextLine(1) will return the line that follows the line that caused the state assignment rule to trigger.

$$Return(true/false) - sets the Test logical state when a JavaScript statement appears within the Test part of a Rule. By default, all scripts return "true" unless this routine is called.

$$SetField(name, value) - updates the current XML tree field with a new value. Note that it is somewhat different from how the "Store a Field" operation works. "Store as Field" will not replace an output value, but instead automatically creates a new instance of the field's parent structure or pane.
$$SetField will replace a current value.

$$SetNewState(name) - overrides the name of the State when this Rule is complete. This overrides whatever is currently set in the "State becomes" section of the Rule.

$$SetPI(string) - adds a DocOrigin Process Instruction to the start of the generated xml file. string is the text that will appear in the PI.

$$SetText(newtext) - update the current Selection to be this new text. newtext can be either a single string or an array of strings.