Class

SpotfireDocument

SpotfireDocument(serverUrlOrDocumentParametersObject, [documentPath], [onDocumentOpened], [configurationBlockText], [apiVersion])

Object allowing to access the TIBCO Spotfire® document and to edit it via its editor property.

Constructor

new SpotfireDocument(serverUrlOrDocumentParametersObject, [documentPath], [onDocumentOpened], [configurationBlockText], [apiVersion])

Parameters:
Name Type Default Description
serverUrlOrDocumentParametersObject String | DocumentParametersObject

The Spotfire Server url, of the form 'htt(s)://[server][:port]/spotfire/wp or the DocumentParametersObject.

serverUrl String

The Spotfire Server url, of the form 'htt(s)://[server][:port]/spotfire/wp or the DocumentParametersObject.

documentPath String

The complete path to the library document.

[ onDocumentOpened ] onDocumentOpenedEventHandler

The callback that will be executed after the document is opened.

[ err ] Error

The error that may have occurred or undefined.

[ configurationBlockText ] String

The configuration block text that will be applied after the document is opened.

[ apiVersion = '7.14' ] String

The webplayer apiVersion (for Spotfire 7.14+).

[ documentPath = "/Discngine/Client Automation/empty" ] String

The complete path to the library document.

[ onDocumentOpened ] onDocumentOpenedEventHandler

The callback that will be executed after the document is opened.

[ err ] Error

The error that may have occurred or undefined.

[ configurationBlockText ] String

The configuration block text that will be applied after the document is opened.

[ apiVersion = '7.14' ] String

The webplayer apiVersion (for Spotfire 7.14+).

Methods

static checkSaveLibraryPath()

Throws an exception if the library path passed as args is not a correctly formed path.

If the path is not a correctly formed spotfire library path

Error

applyTemplateAsync(applyParameters)

Apply a template to the current document.
A template is a document with empty data tables. During the process, the data tables are temporarily exported into SBDF files of the same name and with the extension '.export.sbdf', in the same place as the template. We therefore advise you to make sure that no SBDF files with these names are present in the location of the template to apply, otherwise they will be deleted.
Other warning: once the template is applied, it becomes the current document, so the template can easily be overwritten by accident. A solution to avoid this may be to save the document as a new one, using the SpotfireDocument.save function (see the examples).

Parameters:
Name Type Default Description
applyParameters Object

Describes the parameters needed to apply the template.

path String

The path of the template.

fileName String

The name of the template to be applied.

[ configurationBlockText ] String

The configuration block text that shall be used to perform an initial configuration of the document after it has been opened.

[ location = SpotfireDocument.library ] SpotfireDocumentLocation  {Enum} 

The location where the document is saved.

Enum options: library, local
Examples

Apply a template from the library:

spotfireDocument.applyTemplateAsync({
    path: '/Discngine/Client Automation',
    fileName: 'myNewTemplate',
    configurationBlockText: 'myKey1="ATextToSave";myKey2=255;'
})

Apply a template from a local file:

spotfireDocument.applyTemplateAsync({
    path: 'C:/temp',
    fileName: 'myNewTemplate',
    location: 'Local'
})

createWhereClauseForColumnAndValues(idColumnName, ids)

Helper method used to create clause expression for a specific column and a set of values that may be in it.

Parameters:
Name Type Description
idColumnName String

The name of the column that will contains the ids searched.

ids Array.<string> | Array.<boolean> | Array.<numeric>

The list of values searched.

Example
spotfireDocument.createWhereClauseForColumnAndValues('Column Name', ['ID1', 'ID2', 'ID3', 'ID4'])
// => [Column Name]="ID1" OR [Column Name]="ID2" OR [Column Name]="ID3" OR [Column Name]="ID4"

dispose()

Disposes all resources that must be disposed and clear all events listeners.

executePythonScript(scriptText, scriptArgs)

Execute a python script on the document synchronously. We suggest to avoid using it unless necessary because of its detrimental effect on performance.

Parameters:
Name Type Description
scriptText String

The script to be executed.

scriptArgs Object

The list of named parameters that may be used in the script. In python script the args will be used as jsonParam[].

Example
// Script to hide the column "Column To Hide" from a Table Plot
const hideColumnScript = `
for p in Document.Pages:
for v in p.Visuals:
    if v.TypeId.Name == "Spotfire.Table":
    chart = v.As[TablePlot]()
    (found, column) = chart.Data.DataTableReference.Columns.TryGetValue(jsonParam["columnName"])
    if found:
        chart.TableColumns.Remove(column)
 `;
 spotfireDocument.executePythonScript(hideColumnScript, { columnName: "Column To Hide" });

executePythonScriptAsync(scriptText, scriptArgs) → {Promise}

Execute a python script on the document asynchronously. We suggest to avoid using it unless necessary because of its detrimental effect on performance.

Parameters:
Name Type Description
scriptText String

The script to be executed.

scriptArgs Object

The list of named parameters that may be used in the script. In python script the args will be used as jsonParam[].

Promise
Example
// Script to hide the column "Column To Hide" from a Table Plot
const hideColumnScript = `
for p in Document.Pages:
for v in p.Visuals:
    if v.TypeId.Name == "Spotfire.Table":
    chart = v.As[TablePlot]()
    (found, column) = chart.Data.DataTableReference.Columns.TryGetValue(jsonParam["columnName"])
    if found:
        chart.TableColumns.Remove(column)
 `;
 spotfireDocument.executePythonScriptAsync(hideColumnScript, { columnName: "Column To Hide" }).then(() => alert('Column Hidden'));

getActiveDataTableAsync() → {String}

Gets the name of the active data table.

A data table name.

String

getActiveMarkingAsync() → {Promise(String)}

Gets the active marking name of the active visual.

Promise(String)

getDataColumnsAsync(dataTableName) → {Array.<String>}

Gets the list of data table names with their identifiers.

Parameters:
Name Type Description
dataTableName String

The name of the data table.

An array of columns names.

Array.<String>
Example
spotfireDocument.getDataColumnsAsync("Maybridge-200").then(console.log);
// outputs something like
['Column A', 'Column B', 'Column C']

getDataColumnsPropertiesAsync(dataTableName) → {Array.<DataTableColumnProperties>}

Gets the list of properties for all columns of a data table.

Parameters:
Name Type Description
dataTableName String

The name of the data table.

Example
spotfireDocument.getDataColumnsPropertiesAsync("My Data Table").then(console.log);
// outputs something like
[{
    contentType: "chemical/x-mdl-molfile",
    dataType: "Binary",
    description: "",
    expression: "",
    externalId: null,
    externalName: "Structure <MOLFILE>",
    name: "Structure <MOLFILE>"
},
{
    contentType: null,
    dataType: "String",
    description: "",
    expression: "",
    externalId: null,
    externalName: "CODE",
    name: "CODE"
}]

getDataTableNamesAsync() → {Array.<String>}

Gets the names of all data tables in the document.

An array of data tables names.

Array.<String>

getDataTablePropertiesAsync(dataTableName) → {Promise(DataTableProperty[])}

Gets the list of properties of the data table.

Parameters:
Name Type Description
dataTableName String

The name of the data table.

Promise(DataTableProperty[])
Example
spotfireDocument.getDataTablePropertiesAsync("My Data Table").then(console.log);
// outputs something like
[{
     name: "Color",
     value: {
         R: 100,
         G: 137,
         B: 250,
         A: 255,
         IsKnownColor: false,
         IsEmpty: false,
         IsNamedColor: false,
         IsSystemColor: false,
         Name: "ff6489fa"
     }
}, {
     name: "Description",
     value: "Lorem ipsum"
}]

getDataTablePropertyAsync(dataTableName, propertyName) → {Promise(DataTableProperty)}

Gets the value of a given property of the data table.

Parameters:
Name Type Description
dataTableName String

The name of the data table.

propertyName String

The name of the property.

Promise(DataTableProperty)
Example
spotfireDocument.getDataTablePropertiesAsync("My Data Table", "color").then(console.log);
// outputs something like
{
     name: "Color",
     value: {
         R: 100,
         G: 137,
         B: 250,
         A: 255,
         IsKnownColor: false,
         IsEmpty: false,
         IsNamedColor: false,
         IsSystemColor: false,
         Name: "ff6489fa"
     }
}

getDataTableRowsCountAsync(dataTableName) → {Promise(Number)}

Gets the row count for the specified data table.

Parameters:
Name Type Description
dataTableName String

The name of the data table.

Promise(Number)

getDataTablesNamesByIdsAsync() → {Array.<Object>}

Gets the names and GUIDs of all data tables in the document.

An array of objects of the shape { name: String, id: String }.

Array.<Object>
Example
spotfireDocument.getDataTablesNamesByIdsAsync().then(console.log)
// outputs something like
[{
     id: "2a2f783a-ad48-48b5-b93d-9af04d6618f7",
     name: "Table A"
}, {
     id: "be1b0c51-b086-4d28-b4c7-ee47ee82047b",
     name: "Table B"
}]

getDataTablesSaveSettingsAsync() → {Array.<DataTableSaveSettings>}

Gets the list of the "save settings" of all the data tables.

The list of the "save settings".

Array.<DataTableSaveSettings>

getMarkedRowsAsync(markingName, dataTableName)

Get the list of marked rows with content.

Parameters:
Name Type Description
markingName String

The marking name that we want to get the marked rows.

dataTableName String

The data table name that is marked.

Example
spotfireDocument.getMarkedRowsAsync('MyMarking','aTable').then(function(markedRows) {
    alert(markedRows);
})

getMarkingsAsync() → {Promise(String[])}

Gets all marking names.

Promise(String[])

getMetadataAsync() → {Promise(Object)}

List the metadata of the document.

An object containing metadata of the document ('path', 'created', etc.).

Promise(Object)
Example
spotfireDocument.getMetadataAsync().then(console.log)
// Outputs something like
{
  contentSize: "139246",
  created: "02/11/2018 09:49:45",
  description: "",
  lastModified: "02/20/2020 16:07:00",
  path: "/Discngine (Connector 5.x)/Client Automation/empty",
  title: "empty"
}

getPropertiesAsync() → {Array.<Object>}

Gets the value of all defined document properties.

An array of objects of the shape { name: String, value: String }.

Array.<Object>
Example
spotfireDocument.getPropertiesAsync().then(console.log);
// Outputs something like
[
 {name: "Description", value: ""},
 {name: "Keywords", value: Array(0)},
 {name: "AllowWebPlayerResume", value: "False"},
 ...
]

getPropertyAsync(propertyName) → {String}

Gets the value of a document property.

Parameters:
Name Type Description
propertyName String

The string value of the property.

String
Example
spotfireDocument.getPropertiesAsync('PublicBookmarkCreation').then(console.log); // => "RequiresReadAndWriteAccess"

isDocumentOpen() → {Boolean}

True if a document is opened, false if not.

Boolean

markingExistsAsync(markingName)

Does the marking provided exist?

Parameters:
Name Type Description
markingName String

The name of the marking to check.

markRowsAsync(markingName, dataTableName, whereClause, operation)

Sets a marking in the analysis specified by the input parameters.

Parameters:
Name Type Default Description
markingName String

The marking name in which to set the marking.

dataTableName String

The data table in which to set the marking.

whereClause String

An expression string with conditions for the data columns used to set the marking. For more information, see the documentation for the TIBCO Spotfire® Expression Language.

operation = SpotfireDataSelectionOperations.replace SpotfireDataSelectionOperations  {Enum} 

The operation to use when combining this selection with previously set selections.

Enum options: replace, add, subtract, toggle, intersect
Example
spotfireDocument.markRowsAsync('MyMarking (0)','aTable','[Activity] <= 0', SpotfireDataSelectionOperations.add)

markRowsByIdsAsync(markingName, dataTableName, idColumnName, ids)

Mark rows identified by column and specified values for specified marking and data table.

Parameters:
Name Type Description
markingName String

The name of the marking in which you want to mark the rows.

dataTableName String

The name of the dataTable from where you want to mark rows.

idColumnName String

The name of the column that represents the id on which you want to select the rows.

ids Array.<String>

Array of ids that identified the rows to mark.

Example
spotfireDocument.markRowsByIdsAsync('MyMarking (1)', 'aTable', 'InChIKey', [
    'APZFVJKUDMXDFA-UHFFFAOYSA-N',
    'LQUMXBMVHBUSOC-UHFFFAOYSA-N',
    'KJTUBZKMFRILQD-UHFFFAOYSA-N',
    'WYCLKVQLVUQKNZ-UHFFFAOYSA-N'
])

onDataColumnsChanged(dataTableName, callback)

Adds a new callback to be executed when the list of data tables has changed.

Parameters:
Name Type Description
dataTableName String

The data table to watch.

callback onDataColumnsChangedCb

The callback to be executed when the list of Data Columns has changed.

onDataTablesChanged(callback)

Adds a new callback to be executed when the list of data tables has changed.

Parameters:
Name Type Description
callback onDataTablesChangedCb

The callback to be executed on closed changed event.

onDocumentChanged(callback) → {Number|Boolean}

Configures a callback that will be executed when a document has changed. Note that these callbacks can potentially be executed frequently.

Parameters:
Name Type Description
callback onDocumentChangedCb

The callback to be executed on document changed event.

The number of registered callback in case of success, false otherwise.

Number | Boolean

onDocumentClosed(callback)

Configures a callback that will be executed when a document is closed.

Parameters:
Name Type Description
callback onDocumentClosedCb

The callback to be executed on closed changed event.

onMarkingChanged(markingName, dataTableName, callback)

Configures the callback that will be called when a specific marking has changed for a specific data table. LIMITATION: in web player, all callbacks are called when a marking changes, regardless of whether it happens in the specified data table.

Parameters:
Name Type Description
markingName String

The marking to listen to.

dataTableName String

The datatable to listen to.

callback onMarkingChangedCb

The callback that will be executed when the marking changed for the corresponding data table.

openDocument(documentPath, [onDocumentOpenedHandler], [configurationBlockText], [location])

Opens an existing document from library.

Parameters:
Name Type Default Description
documentPath String

The full path to the document in the library, or to a local drive if you are using only the TIBCO Spotfire ® Analyst client</>.

[ onDocumentOpenedHandler ] onDocumentOpenedEventHandler

The callback that will be executed after the document is opened.

[ err ] Error

The error that may have occurred or undefined.

[ configurationBlockText ] String

The configuration block text to be applied.

[ location = SpotfireDocumentLocation.library ] SpotfireDocumentLocation  {Enum} 

The location type of the document, from SpotfireDocumentLocation.

Enum options: library, local
Examples

Open a document from the library:

spotfireDocument.openDocument('/Discngine/Client Automation/empty')

Open a document from a local file:

spotfireDocument.openDocument('C:/temp/data.dxp', null, null, SpotfireDocumentLocation.local)

Open a document with a configuration block and a callback function:

spotfireDocument.openDocument('/MyTeam/data.dxp', function() {alert('document opened')}, 'myKey1="ATextToSave";myKey2=255;')

removeOnDataColumnsChanged(dataTableName, callback)

Removes a callback previously registered with the SpotfireDocument#onDataTablesChanged method.

Parameters:
Name Type Description
dataTableName String

The data table for which the callback was registered.

callback onDataColumnsChangedCb

The callback to unregister.

removeOnDataTablesChanged(callback)

Removes a callback previously registered with the SpotfireDocument#onDataTablesChanged method.

Parameters:
Name Type Description
callback onDataTablesChangedCb

The callback to unregister.

removeOnDocumentChanged(callback)

Removes a callback previously registered with the SpotfireDocument#onDocumentChanged method.

Parameters:
Name Type Description
callback onDocumentChangedCb

The callback to unregister.

removeOnDocumentClosed(callback)

Removes a callback previously registered with the SpotfireDocument#onDocumentClosed method.

Parameters:
Name Type Description
callback onDocumentClosedCb

The callback to unregister.

removeOnMarkingChanged(markingName, dataTableName, callback)

Removes a callback previously registered with the SpotfireDocument#onMarkingChanged method.

Parameters:
Name Type Description
markingName String

The marking for which the callback was registered.

dataTableName String

The data table for which the callback was registered.

callback onDataTablesChangedCb

The callback to unregister.

save(saveOptionsOrLibraryPath)

Saves the document.

Parameters:
Name Type Description
saveOptionsOrLibraryPath String | DocumentSaveOptions

List all options for saving the document. If array is string, assuming that the save operation is done in the library.

path String

The existing destination path of the document to be saved.

fileName String

The name of the document to be saved.

[ configurationBlockText ] String

The configuration block text that shall be embedded in the file when the document is saved.

[ location = SpotfireDocument.library ] SpotfireDocumentLocation  {Enum} 

The location where to save the document, from SpotfireDocumentLocation.

Enum options: library, local
[ libraryItemMetaData ] LibraryItemMetaData

The metadata to associate with the library item (not available if the document is saved locally).

[ description = '' ] String

the description

[ otherData ] Object

the list of all custom metadata you want to pull as metadata for the library document

Examples

Save the document as it is:

spotfireDocument.save()

Save the document as a new document in local folder (FOR ANALYST ONLY):

spotfireDocument.save({
    path:'c:\\TMP\\',
    fileName:'NewFileName.dxp',
    location: SpotfireDocumentLocation.local
})

Save the document as a new document in local folder (FOR ANALYST ONLY) with a configuration block:

spotfireDocument.save({
    path:'c:\\TMP\\',
    fileName:'NewFileName.dxp',
    location: SpotfireDocumentLocation.local,
    configurationBlockText: 'myKey1="ATextToSave";myKey2=255;'
})

Save the document as a new document in library:

 spotfireDocument.save({
     path:'/myLibraryFolder/',
     fileName:'NewFileName'
})

Save the document as a new document in library with configurationBlockText:

spotfireDocument.save({
    path:'/myLibraryFolder/',
    fileName:'NewFileName',
    configurationBlockText: 'myKey1="ATextToSave";myKey2=255;'
})

saveTemplateAsync(saveParameters)

Saves the document as a template.
A template is a document with empty data tables. During the process, the data tables are temporarily exported into SBDF files of the same name and with the extension '.export.sbdf', in the same place as the template. We therefore advise you to make sure that no SBDF files with these names are present in the location of the future template, otherwise they will be deleted.

Parameters:
Name Type Description
saveParameters DocumentSaveOptions

Describes the parameters needed to save the template.

path String

The existing destination path of the document to be saved.

fileName String

The name of the document to be saved.

[ configurationBlockText ] String

The configuration block text that shall be embedded in the file when the document is saved.

[ location = SpotfireDocument.library ] SpotfireDocumentLocation  {Enum} 

The location where to save the document, from SpotfireDocumentLocation.

Enum options: library, local
[ libraryItemMetaData ] LibraryItemMetaData

The metadata to associate with the library item (not available if the document is saved locally).

[ description = '' ] String

the description

[ otherData ] Object

the list of all custom metadata you want to pull as metadata for the library document

Examples

Save a template in the library:

spotfireDocument.saveTemplateAsync({
    path: '/Discngine/Client Automation',
    fileName: 'myNewTemplate',
    configurationBlockText: 'myKey1="ATextToSave";myKey2=255;'
})

Save a template in an existing local folder:

spotfireDocument.saveTemplateAsync({
    path: 'C:/temp',
    fileName: 'myNewTemplate',
    location: 'Local'
})

setSpinnerState(isActive, message, [timeout]) → {this}

Allows to add a spinner containing a custom message to indicate when Spotfire is working. This can be convenient to prevent multiple blinking caused by Python scripts being executed sequentially. Calling the method multiple times while changing message allows to update the message displayed to the user.

Parameters:
Name Type Default Description
isActive Boolean

Whether to show or hide the spinner.

message String

The message you want to display on the screen.

[ timeout = 10000 ] Number

The time in ms after which the spinner will be unset automatically. You can disable it by explicitely passing 0.

Returned with this to allow chaining.

this