Dashboard Pivot Embedded Section Object (ESO) in Active Mode only
Returns a JavaScript array (and not an Object Model array) of top label values. Each array element contains the value of the label at successively lower levels. For example, if there are two top labels in the Pivot, Year and Month, then the array element at index 1 in the array might contain “2001” and the next element at index 2 would contain a value like “November”. Because JavaScript arrays are zero-based, the element at index 0 (zero) contains an empty string value.
The TopLabelValues (Array) is accessible for a Dashboard Embedded Section Object (ESO) only. It is available even if the Pivot contains no data. In addition, it is only functional when the Pivot is in Active mode.
The TopLabelValues (Array) is refreshed each time a Pivot ESO cell is clicked in the user interface, or the OnCellDoubleClick() method is used. An array is used in this case due to the uncertainty of the TopLabel hierarchy at any given time. The array forces the user to iterate through and get the value each time to ensure it is up to date. It purposefully avoids the standard x.y.z.name structure of an object which could become ambiguous or incorrect with any change of the Pivot Top Labels.
The array is read-only. An attempt to change the values in the array has no effect, scripts continue and this action does not change any of the Pivot top label values.
The value returned by the array should be a string which reflects the names of the Pivot Top Labels in sequence. The number of values is returned using the length accessor. JavaScript arrays are normally 0-based, but for purposes of consistency with other Object Model objects, the ]0] value always returns an empty string. If there are three Top labels, the array returns … TopLabelValues[0] =<empty string>, …TopLabelValues[1] =<First Top Label Name>, …TopLabelValues[2] =<Second Top Label Name>, …TopLabelValues[3] =<Last Top Label Name>.
When no Pivot top label exists, the TopLabelValues[1] returns the value “undefined”; however no exception is generated and scripts continue to execute. The same behavior occurs when a value exceeding the length of the array is called. The array functions the same whether or not data exists at the selected intersection.
Any value returned by the array is not formatted. Any formatting that you want applied to the value should be scripted additionally.
Iterating through the TopLabelValues (Array) does not persist (dirty) in the document; nor does retrieving the value. The value in the array reflects the names of the Pivot top labels in sequence. It does not persist separately from the Pivot values or in the application.
The TopLabelValues (Array) is available in Interactive Reporting Studio and Interactive Reporting Web Client. It is unavailable in EPM Workspace.
This example shows how to access top label array data:
var ActionName = "TopLabelValues Array"
TextBox1.Text ="Start " + ActionName
PivotESOTextBox.Text = PivotESOTextBox.Text + "\r\nTopLabelValues Default is: " + ActiveSection.Shapes["Pivot1"].TopLabelValues
PivotESOTextBox.Text = PivotESOTextBox.Text + "\r\nTopLabelValues length is: " + ActiveSection.Shapes["Pivot1"].TopLabelValues.length
PivotESOTextBox.Text = PivotESOTextBox.Text + "\r\nTopLabelValues[0] is: " + ActiveSection.Shapes["Pivot1"].TopLabelValues[0]
PivotESOTextBox.Text = PivotESOTextBox.Text + "\r\nTopLabelValues[1] is: " + ActiveSection.Shapes["Pivot1"].TopLabelValues[1]
PivotESOTextBox.Text = PivotESOTextBox.Text + "\r\nTopLabelValues[2] is: " + ActiveSection.Shapes["Pivot1"].TopLabelValues[2]
PivotESOTextBox.Text = PivotESOTextBox.Text + "\r\nTopLabelValues[3] is: " + ActiveSection.Shapes["Pivot1"].TopLabelValues[3]
TextBox2.Text = "Caught: " + e.toString()
TextBox1.Text ="End " + ActionName
The results of the script are displayed as follows:
TopLabelValues Default is: ,15 TopLabelValues length is: 2 TopLabelValues[0] is: TopLabelValues[1] is: 15 TopLabelValues[2] is: undefined TopLabelValues[3] is: undefined