Class

SpotfireDocumentEditor

SpotfireDocumentEditor(serverUrl, documentPath, [onDocumentOpenedHandler], [sfConnector], [defaultSerializer])

Constructor

new SpotfireDocumentEditor(serverUrl, documentPath, [onDocumentOpenedHandler], [sfConnector], [defaultSerializer])

Represents the state to be applied to the TIBCO Spotfire® document, using a collection of pages, markings and filters. Includes also the data access layer (DAL) which will help to synchronize the real TIBCO Spotfire® document using a python script generated by a scriptComposer.

Parameters:
Name Type Attributes Description
serverUrl String

The TIBCO Spotfire® server URL to be connected to.

documentPath String

The document to be opened. Mandatory to use in a mashup using the TIBCO Spotfire® Web Player. Optional for the TIBCO Spotfire® Analyst.

onDocumentOpenedHandler onDocumentOpenedCb <optional>

Handler to be executed on the openedDocument event.

sfConnector SpotfireConnectorBase <optional>

The TIBCO Spotfire® connector instance you can inject at the creation.

defaultSerializer SpotfireDocumentEditorDefaultSerializer <optional>

The serializer instance you can inject at the creation.

Methods

addBarChart(barChartDescription)

Adds a SpotfireBarChart to the current state to be applied on the current Spotfire document.

Parameters:
Name Type Description
barChartDescription Object

The bar chart properties (see SpotfireBarChart for details).

addBoxPlot(boxPlotDescription)

Adds a SpotfireBoxPlot to the current state to be applied on the current Spotfire document.

Parameters:
Name Type Description
boxPlotDescription Object

The box plot properties (see SpotfireBoxPlot for details).

addColumnMatchings(columnRelations)

Adds a match between two columns from two different data tables.

Parameters:
Name Type Description
columnRelations Array.<SpotfireColumnRelation>

Array of column relation descriptions.

Example
spotfireDocument.editor
    .addColumnMatchings([
        {
            leftColumn: {
                tableName: 'firstDataTable',
                name: 'a column of firstDataTable',
                transformation: SpotfireColumnTransformation.integer
            },
            rightColumn: {
                tableName: 'secondDataTable',
                name: 'a column of secondDataTable',
                transformation: SpotfireColumnTransformation.integer
            }
        }
    ])
    .applyState();

addColumnRelations(columnRelationsDescription, getMethod, destinationArray)

Adds/replaces a relation between two columns of two data tables. Used to add data table relations and column matchings for adding linked data.

Parameters:
Name Type Description
columnRelationsDescription Array.<ColumnRelationDescription>

Array of description of the relation between data columns

getMethod function

The method to use when getting the corresponding relations

destinationArray Array.<SpotfireColumnRelation>

the array of SpotfireColumnRelation where to push/modify the column relation

Example
spotfireDocument.editor.loadDataTableFromUrl('oneTable',urlToImport)
.loadDataTableFromUrl('secondTable',urlToImport)
.addColumnRelations([
{
       leftColumn : {
          tableName: 'oneDataTable',
          name: 'Activity',
          transformation: SpotfireColumnTransformation.string
      },
      rightColumn : {
          tableName: 'secondDataTable',
          name: 'Activity',
          transformation: SpotfireColumnTransformation.string
      }
  }
]).applyState()

addColumnsFromUrl(importedDataAsColumnDescription)

Adds data to be imported as columns in a data table.

Parameters:
Name Type Description
importedDataAsColumnDescription ImportedDataAsColumnDefinition

addCombinationChart(combinationChartDescription)

Adds a SpotfireCombinationChart to the current state to be applied on the current Spotfire document.

Parameters:
Name Type Description
combinationChartDescription Object

The combination chart properties (see SpotfireTable for details).

addCrossTable(crossTableDescription)

Adds a SpotfireCrossTable to the current state to be applied on the current Spotfire document.

Parameters:
Name Type Description
crossTableDescription Object

The cross table properties (see SpotfireCrossTable for details).

addCustomScript(customScriptText, [atTheEnd])

Adds an IronPython custom script to the SpotfireDocumentEditor, using the TIBCO Spotfire® IronPython API. This script can be executed after the last created element (DataTable, Page, DataVisualization) or at the very end of the script.

NB: in your custom script, you can directly access the last element created by the editor using this convention:

  • dataviz: the variable containing the last visualization created,
  • pageToModify: the variable containing the last page created,
  • currentDataTable: the variable containing the last data table created.

NBB: if the SpotfireDocumentEditor does not create a page or a visualization when calling addCustomScript, the script will be executed with this context:

  • dataviz = None
  • pageToModify = Document.ActivePageReference
  • currentDataTable = None
Parameters:
Name Type Attributes Default Description
customScriptText String

The custom script to add to the state of the SpotfireDocumentEditor.

atTheEnd Boolean <optional>
false

Specifies whether the script should be added at the end of the state or not. If false, the script will be executed after all the last created element (data table, page or visualization).

Examples

Modify the name of a data table after its creation:

spotfireDocument.editor
     .loadDataTableFromUrl('A New Table', 'https://anURI/aSBDF.sbdf')
     .addCustomScript('currentDataTable.Name = "My New Table (modified using a custom script)"')
     .applyState()

Modify the name of a line chart using a custom script and then add a bar chart using the API:

spotfireDocument.editor.addLineChart({ general: { title: "MyLineChart"}});
var currentDataviz = spotfireDocument.editor.lastElementCreated;
currentDataviz.addCustomScript('dataviz.Title = "My Line Chart (modified using a custom script)"');
spotfireDocument.editor..addBarChart().applyState()

Modify the name of a page using a custom script after its creation:

spotfireDocument.editor
     .addPage('MyLastPage')
     .addCustomScript('pageToModify.Title = "My Last Page (modified using a custom script)"')
     .applyState()

Modify the name of the current page using a custom script:

spotfireDocument.editor
     .addCustomScript('pageToModify.Title = "My Last Page (modified using a custom script)"')
     .applyState()

Modify the name of the page named 'MyPage' using a custom script added at the end of the state:

spotfireDocument.editor
     .addCustomScript('for page in Document.Pages:\n' +
                       '    if(page.Title == "MyPage"):\n' +
                       '        pageToModify = page\n' +
                       '    break\n' +
                       'pageToModify.Title = "My Last Page (modified using a custom script)"', true)
     .addPage('MyPage')
     .applyState()

addDataTable(dataTableDescription)

Adds a data table.

Parameters:
Name Type Description
dataTableDescription DataTableDescription

The description of the data table.

addDataTableColumns(dataTableName, addedColumnsDefinitions)

Adds columns to a data table.

Parameters:
Name Type Description
dataTableName String

The name of the data table.

addedColumnsDefinitions Array.<AddedColumnsDefinition>

The definition of columns to be added.

addDataTableProperty(dataTableName, dataTablePropertyName, dataTablePropertyValue)

Adds/updates a property in the specified data table.

Parameters:
Name Type Description
dataTableName String

The name of the data table to be updated.

dataTablePropertyName String

The name of the data table property to be added/updated.

dataTablePropertyValue String | Boolean | Number

The value of the data table property to be added/updated.

addDataTableRelations(dataTableRelations)

Adds a relation between two columns from two different data tables.

Parameters:
Name Type Description
dataTableRelations Array.<SpotfireColumnRelation>

Array of column relation descriptions.

Example
spotfireDocument.editor
    .addDataTableRelations([
        {
            leftColumn: {
                tableName: 'firstDataTable',
                name: 'a column of firstDataTable',
                transformation: 'Integer(Value)'
            },
            rightColumn: {
                tableName: 'secondDataTable',
                name: 'a column of secondDataTable',
                transformation: 'Integer(Value)'
            }
        }
    ])
    .applyState();

addFiltering(filteringName)

Add a filtering scheme in the current state to be applied

Parameters:
Name Type Description
filteringName string

the name of the current filtering scheme to be added

addFilterings(arrayOfFilteringNames)

Add one or many filtering scheme in the current state to be applied in the current SpotfireDocument

Parameters:
Name Type Description
arrayOfFilteringNames Array.<string>

the array of filtering schemes to be added

addGraphicalTable(graphicalTableDescription)

Adds a SpotfireGraphicalTable to the current state to be applied on the current Spotfire document.

Parameters:
Name Type Description
graphicalTableDescription Object

The graphical table properties (see SpotfireGraphicalTable for details).

addHeatMap(heatMapDescription)

Adds a SpotfireHeatMap to the current state to be applied on the current Spotfire document.

Parameters:
Name Type Description
heatMapDescription Object

The heat map properties (see SpotfireHeatMap for details).

addKPIChart(kpiChartDescription)

Adds a SpotfireKPIChart to the current state to be applied on the current Spotfire document.

Parameters:
Name Type Description
kpiChartDescription Object

The KPI chart properties (see SpotfireKPIChart for details).

addLineChart(lineChartDescription)

Adds a SpotfireLineChart to the current state to be applied on the current Spotfire document.

Parameters:
Name Type Description
lineChartDescription Object

The line chart properties (see SpotfireLineChart for details).

addMapChart(mapChartDescription)

Adds a SpotfireMapChart to the current state to be applied on the current Spotfire document.

Parameters:
Name Type Description
mapChartDescription Object

The map chart properties (see SpotfireMapChart for details).

addMarking(markingDescription)

Add a MarkingDefinition in the current state to be applied to the current Spotfire document

Parameters:
Name Type Description
markingDescription MarkingDescription

description of the marking to be created/modified

addMarkings(arrayOfMarkingDescription)

Add one or many markings to the current state to be applied

Parameters:
Name Type Description
arrayOfMarkingDescription Array.<MarkingDescription>

array of marking description

addPage(pageDescription)

Add a page to the current state to be applied to the current Spotfire document

Parameters:
Name Type Description
pageDescription String | PageDescription

the title or the complete description of the page to be added

addParallelCoordinatePlot(parallelCoordinatePlotDescription)

Adds a SpotfireParallelCoordinatePlot to the current state to be applied on the current Spotfire document.

Parameters:
Name Type Description
parallelCoordinatePlotDescription Object

The parallel coordinate plot properties (see SpotfireParallelCoordinatePlot for details).

addPieChart(pieChartDescription)

Adds a SpotfirePieChart to the current state to be applied on the current Spotfire document.

Parameters:
Name Type Description
pieChartDescription Object

The pie chart properties (see SpotfirePieChart for details).

addRowsFromUrl(importedDataAsRowsDescription)

Add data from url as rows in a data table.

Parameters:
Name Type Description
importedDataAsRowsDescription ImportedDataAsRowDefinition

addScatterPlot(scatterPlotDescription)

Adds a SpotfireScatterPlot to the current state to be applied on the current Spotfire document.

Parameters:
Name Type Description
scatterPlotDescription Object

The scatter plot properties (see SpotfireScatterPlot for details).

addScatterPlot3D(scatterPlot3DDescription)

Adds a SpotfireScatterPlot3D to the current state to be applied on the current Spotfire document.

Parameters:
Name Type Description
scatterPlot3DDescription Object

The scatter plot 3D properties (see SpotfireScatterPlot3D for details).

addSummaryTable(summaryTableDescription)

Adds a SpotfireSummaryTable to the current state to be applied on the current Spotfire document.

Parameters:
Name Type Description
summaryTableDescription Object

The summary table properties (see SpotfireSummaryTable for details).

addTable(tableDescription)

Adds a SpotfireTable to the current state to be applied on the current Spotfire document.

Parameters:
Name Type Description
tableDescription Object

The table plot properties (see SpotfireTable for details).

addTreemap(treemapDescription)

Adds a SpotfireTreemap to the current state to be applied on the current Spotfire document.

Parameters:
Name Type Description
treemapDescription Object

The treemap properties (see SpotfireTreemap for details).

addWaterfallChart(waterfallDescription)

Adds a SpotfireWaterfallChart to the current state to be applied on the current Spotfire document.

Parameters:
Name Type Description
waterfallDescription Object

The waterfall chart properties (see SpotfireWaterfallChart for details).

defaultDataTableDescription() → {DataTableDescription}

Returns a data table description with default values.

The default description of a data table.

DataTableDescription

getColumnMatchingRelation(leftColumn, rightColumn)

Get the SpotfireColumnRelation from the columnMatchings collection having the same name for left and right column than the arg specified

Parameters:
Name Type Description
leftColumn ColumnDescription

the left column description for the column relation searched

rightColumn ColumnDescription

the right column description for the column relation searched

getColumnRelation(leftColumn, rightColumn, columnRelationCollection) → {Object|null}

Get the corresponding column relation from the specified SpotfireColumnRelation collections having the same name for left and right column than the arg specified

Parameters:
Name Type Description
leftColumn ColumnDescription

the left column description for the column relation searched

rightColumn ColumnDescription

the right column description for the column relation searched

columnRelationCollection Array.<Object>

the SpotfireColumnRelation collection you are searching in

Object | null

getDataTable(dataTableName) → {Object|null}

Returns the data table with the given name if it exists.

Parameters:
Name Type Description
dataTableName String

The name of the data table.

Object | null

getDataTableRelation(leftColumn, rightColumn)

Get the SpotfireColumnRelation from the dataTableRelations collection having the same name for left and right column than the arg specified

Parameters:
Name Type Description
leftColumn ColumnDescription

the left column description for the column relation searched

rightColumn ColumnDescription

the right column description for the column relation searched

getMarking(markingDescription) → {MarkingDescription|null}

Get the marking in the current state to be applied having the same name than the MarkingDescription passed as arg

Parameters:
Name Type Description
markingDescription MarkingDescription

the marking description we are looking for

MarkingDescription | null

getPage(pageDescription) → {SpotfirePage|undefined}

Get the SpotfirePage having the same title than the pageDescription arg from the current state to be applied to the current SpotfireDocument

Parameters:
Name Type Description
pageDescription string | PageDescription

the title or page description searched

SpotfirePage | undefined

getPageByVisualDescription(visualDescription)

Get the SpotfirePage for the corresponding visualDescription (see SpotfireVisualization arg}

Parameters:
Name Type Description
visualDescription Object

the visual description with a pageTitle property

initOrClear()

Clears the structure in the editor that represents the action to be done on the document.

loadDataTableFromInformationLink(dataTableName, informationLink, informationLinkParameters, [addedColumnsDefinitions])

Loads a data table from a TIBCO Spotfire® information link.

Parameters:
Name Type Attributes Description
dataTableName String

The name of the data table.

informationLink String

The complete path to the information link to be used.

informationLinkParameters Array.<InformationLinkParameter>

The parameters of the information link.

addedColumnsDefinitions Array.<AddedColumnsDefinition> <optional>

Array of definitions of the columns to be added. Only calculated columns can be added for now.

Examples
spotfireDocument.editor.loadDataTableFromInformationLink('dataTable', '/path/to/the/information_link', null, null).applyState()
spotfireDocument.editor.loadDataTableFromInformationLink('dataTable', '/path/to/the/information_link', [
 {
     name: "a_string_parameter",
     values: "Europe"
 }, {
     name: "an_integer_parameter_with_multiple_values",
     values: [2, 4]
 }],
 null).applyStateAsync(true)

loadDataTableFromUrl(dataTableName, url, [addedColumnsDefinitions])

Loads a data table from a URL.

Parameters:
Name Type Attributes Description
dataTableName String

The name of the data table.

url String

The URL of the source containing the data table.

addedColumnsDefinitions Array.<AddedColumnsDefinition> <optional>

Array of definitions of the columns to be added. Only calculated columns can be added for now.

Example
spotfireDocument.editor.loadDataTableFromUrl('dummyTable', 'http://dummySource/url', [
 {
     type: SpotfireDataColumnsTypes.calculatedDataColumn,
     name: 'MyCalculatedColumn1',
     expression: 'SUM([Col1])'
 },
 {
     type: SpotfireDataColumnsTypes.calculatedDataColumn,
     name: 'MyCalculatedColumn2',
     expression: 'AVG([Col2])'
 }
 ]).applyStateAsync(true)

onVisualisationAdded()

Keep the reference of the last data visualization created

removeRowsFromDataTable(dataTable)

Removes all rows from a data table. This action is done using the addCustomScript function of the SpotfireDocumentEditor and will always be executed after all other actions on the last created data table of the state. See the SpotfireDocumentEditor.addCustomScript function for more details.

Parameters:
Name Type Description
dataTable String

The name of the data table in which all rows are to be removed. If empty, the current data table of the state is used.