evalDefinedName

This command requires an extra license.

Evaluate and retrieve the values of all cells belonging to a defined name of an XLSX workbook. This includes formula cells as well as cells with static content, and completely empty cells too. This command is very similar to evalRows, differing only by the way of specifying the cells whose values to retrieve.

The data is delivered into the variable context as a (OLD / LEGACY)Collection of Collections. Each of the inner Collections represents a row, with the items within being the values of the cells in that row. The cell values are in the Collection in their column order, so for example the value of cell A2 is followed by the value of B2, which is followed by C2, and so on. The row-representing Collections are ordered with a similar logic, with the first inner Collection being the first row of the defined area, followed by the Collection of the next row, and so on.

Attributes

var
Required	Value type	EL-evaluated
Yes	Collection	No
Defines the name of the variable that will hold the data Collection.

name
Required	Value type	EL-evaluated
Yes	String	Yes
Defines the name of the defined name whose cells' data is retrieved.

workbook
Required	Value type	EL-evaluated
Yes	File	Yes
Defines the XLSX workbook whose data is being retrieved. The resolved File is therefore expected to be an XLSX document.

Examples

This command has the same uses as evalRows due to the same format of value they both produce - the cells organized in a Collection of Collections. So this example is pretty much the same as well.

The evalDefinedName can be used to easily present the defined name's area on a Form or a document. So, a Step preceding a Form can have an evalDefinedName command like this:

CODE

<evalDefinedName var="nameData" name="SpecialPrices" workbook="${xlsxFile}">

The values of cells that the name "SpecialPrices" refers to are now in a variable. A dynamic table in HTML can present the data like this:

CODE

<table dyn-repeat="nameData" dyn-repeat-var="row">  <tr dyn-repeat="row" dyn-repeat-var="cellValue">  <td dyn-content="cellValue"/>  </tr></table>

The data format is somewhat inconvenient if the intention is to access values of specific cells. The only way to access specific values in a Collection is to use indexes in the EL expressions, which requires one to calculate the row and cell index based on the name's referred area's starting cell (which can be found by inspecting the XLSX workbook in Excel). So if the area starts at cell B4, that starting cell's value is accessed with ${sheetData[0][0]}, while cell C5 would be behind ${sheetData[1][1]}.