extract()

Extracts the text value from selected data: a node path, column, or rectangular region, depending on the type of data source.

This method always returns a String.

extract(left, right, verticalOffset, regionHeight, separator)

Extracts a value from a position in a text file. Coordinates are expressed as characters (horizontally) or lines (vertically).

left

Number that represents the distance, measured in characters, from the left edge of the page to the left edge of the rectangular region. The leftmost character is character 1.

right

Number that represents the distance, measured in characters, from the left edge of the page to the right edge of the rectangular region.

verticalOffset

Number that represents the current vertical position, measured in lines.

regionHeight

Number that represents the total height of the region, measured in lines.
Setting the regionHeight to 0 instructs the DataMapper to extract all lines starting from the given position until the end of the record.
Specifying an extraction height that is longer than the number of remaining lines results in a "step out of bound" error message.

separator

String inserted between all lines returned from the region. If you don't want anything to be inserted between the lines, specify an empty string ("").

Tip:

" " is a very handy string to use as a separator. When the extracted data is inserted in a Designer template, " " will be interpreted as a line break, because is a line break in HTML and Designer templates are actually HTML files.
Setting the regionHeight to 0 makes it possible to extract a variable number of lines at the end of a record.

Examples

Example 1:

The script command data.extract(1,22,8,1," "); means that the left position of the extracted information is located at character 1, the right position at character 22, the offset position is 8 (since the line number is 9) and the regionHeight is 1 (to select only 1 line). Finally, the " " string is used for concatenation.

Example 2:

The script command data.extract(1,22,9,6," "); means that the left position of the extracted information is located at 1, the right position at 22, the offset position is 9 (since the first line number is 10) and the regionHeight is 6 (6 lines are selected). Finally, the " " string is used for concatenation.

extract(xPath)

Extracts the text value of the specified node in an XML file.

xPath

String that can be relative to the current location or absolute from the start of the record.

Example

The script command data.extract('./CUSTOMER/FirstName'); means that the extraction is made on the FirstName node under Customer.

extract(columnName, rowOffset)

Extracts the text value from the specified column and row in a CSV/XLS/XLSX file.

The column is specified by name. To extract data from a column specified by index, use extractByIndex(index, rowOffset).

columnName

String that represents the column name.

rowOffset

Number that represents the row index (zero-based), relative to the current position. To extract the current row, specify 0 as the rowOffset. Use moveTo() to move the pointer in the source data file (see moveTo()).

Example

The script command data.extract('ID',0); means that the extraction is made on the ID column in the first row.

extract(left, right, verticalOffset, lineHeight, separator)

Extracts the text value from a rectangular region in a PDF file. All coordinates are expressed in millimeters.

left

Double that represents the distance from the left edge of the page to the left edge of the rectangular region.

right

Double that represents the distance from the left edge of the page to the right edge of the rectangular region.

verticalOffset

Double that represents the distance from the current vertical position.

lineHeight

Double that represents the total height of the region.

separator

String inserted between all lines returned from the region. If you don't want anything to be inserted between the lines, specify an empty string ("").

Tip: " " is a very handy string to use as a separator. When the extracted data is inserted in a Designer template, it will be interpreted as a line break, because is a line break in HTML and Designer templates are actually HTML files.

Example

The script command data.extract(4.572,51.815998,37.761333,3.7253342," "); means that the left position of the extracted information is located at 4.572mm, the right position at 51.815998mm, the vertical offset is 37.761333mm and the line height is 3.7253342mm. Finally, the " " string is used for concatenation.

extract(jPath)

Extracts the text value of the specified element in a JSON file.

jPath

JsonPath expression (String) that can be relative to the current location or absolute from the start of the record. See also: JsonPath.

Example

The script command data.extract('$[0].FirstName'); means that the extraction is made on the FirstName element found in the first element in the array at the root.

Note that in order to access an extracted object or array in script, the extracted value has to be parsed, for example:
var myData = JSON.parse(data.extract('$[0]'));