Bookmarks allow the user to capture, share and reapply the state of TIBCO Spotfire analyses.
Overview
These examples describe how to add, modify and apply TIBCO Spotfire bookmarks through the API.
Bookmarks are XML representations of the document state that allow the user to capture the state of TIBCO Spotfire analyses. The bookmarks can then be shared and reapplied.
This article concerns the bookmarks introduced in Spotfire 3.3.
Background information
Spotfire SDK\Examples\Extensions\SpotfireDeveloper.ApiExamples\BookmarkExamples.cs
This file showcases the code of some of the following examples.
The bookmark manager
The bookmark manager allows the user to find and modify the existing bookmarks as well as adding new bookmarks to the analysis. There is one bookmark manager per session.
The bookmark manager can be retrieved through a document node.
BookmarkManager bookmarkManager = docNode.Context.GetService<BookmarkManager>();
Bookmarks
The bookmark is an immutable object that captures the state of the document at the time it is created. Only the bookmark id is guaranteed to be unique.
|
Property
|
Function
|
|
Author
|
Gets the name of the author. This is the name of the user that adds the bookmark.
|
|
Components
|
Gets the included components.
|
| Modified |
Gets the date when the bookmark was last modified.
|
|
Id
|
Gets the unique identifier of the bookmark.
|
|
IsPublic
|
Gets a value indicating whether the bookmark is visible to all users or not.
|
|
Name
|
Gets the name of the bookmark. More than one bookmark can have the same name.
|
Since bookmarks are immutable they can only be modified through the methods on the bookmark manager. When a bookmark is modified, the old bookmark is destroyed and a new bookmark object with the specified modification is returned.
Bookmark bookmark;
bookmarkManager.TryGetBookmark(guid, out bookmark);
// Since bookmarks are immutable, the bookmark manager removes the old bookmark and returns a new
// bookmark, where we have copied everything and changed the name.
bookmark = bookmarkManager.SetName(bookmark, "NewBookmarkName");
// Make the bookmark public if it is not
// We have to use the new, returned bookmark.
if (!bookmark.IsPublic)
{
bookmarkManager.SetPublicVisibility(bookmark, true);
}
The BookmarkComponentFlags specify which parts of the state the bookmark will capture. By default a bookmark captures all available components. Note that the ActivePage and ActiveVisual flags only specifies which visual and page is active.
|
Component
|
Function
|
|
ActivePage
|
Captures which page is active.
|
|
ActiveVisual
|
Captures which visual is active.
|
| FilterSettings |
Captures the filter settings for the active page.
|
|
MarkedRecords
|
Captures the marked rows for all markings on the active page.
|
|
FilterOrganization
|
Captures the filter organization for the active page.
|
|
Properties
|
Captures the document , data and column properties.
|
|
PageConfiguration
|
Captures the layout and configuration of the visuals on the active page.
|
Adding a bookmark
To create a bookmark it has to be added in an analysis with the desired state. Adding a bookmark always captures the state in the active page.
// The bookmark component flags specify which components are captured in the bookmark.
BookmarkComponentFlags components = BookmarkComponentFlags.ActiveVisual | BookmarkComponentFlags.PageConfiguration;
// We add a bookmark, with a specified name and components .
Bookmark partialBookmark = bookmarkManager.AddNew("NewPartialBookmark", components);
// If we add a bookmark without components, all components will be captured in the bookmark.
Bookmark bookmark = bookmarkManager.AddNew("NewBookmark");
Applying a bookmark
In order for the state to be reapplied, the node that the state refers to must still be present. All components that can be applied are applied.
// Bookmark component flags.
BookmarkComponentFlags components = BookmarkComponentFlags.FilterSettings | BookmarkComponentFlags.MarkedRecords;
// Apply the filter settings and the marked record captured in the bookmark.
bookmarkManager.Apply(bookmark, components);
It is possible to check if the components of a bookmark can be applied.
// Check if a bookmark can be fully applied, i.e. all captured components can be applied.
bookmarkManadder.CanApply(bookmark);
// Check if the filter settings captured in the bookmark can be applied.
BookmarkComponentFlags components = BookmarkComponentFlags.FilterSettings;
bookmarkManager.CanApply(bookmark, components);
Saving a private copy of a bookmark
This creates a new, private bookmark with the same components as the copied bookmark. The creator is set to the current user.
// Save a private copy of the bookmark.
Bookmark copy = bookmarkManager.SavePrivateCopy(bookmark);
Searching for a bookmark
BookmarkManager.Search returns a list of bookmarks given a search string. For a listing of the basic search syntax, see Searching in TIBCO Spotfire.
Allowed properties:
|
Property
|
Example
|
Function
|
|
name
|
name:sales |
Returns all bookmarks with the specified word in its name.
|
|
author
|
author:April
|
Returns all bookmarks with the specified author.
|
| modified |
modified:2011-04-06
modified:"00:08"
|
Returns all bookmarks with the specified modification date/time.
|
|
visibility
|
visibility:Public
visibility:Personal
|
Returns all bookmarks with the specified visibility.
|
|
components
|
components:ActivePage
|
Returns all bookmarks with the specified component.
|
// Get a list of all bookmark where April is the author.
List<Bookmark> foundBookmarks = new List<Bookmark>(bookmarkManager.Search(author:April));
Linking to an analysis for a specific bookmark
Analyses in the library can be reached through links. To get links to the bookmark, use BookmarkManager.Links, which returns a BookmarkLinks object from which a number of links can be retrieved per bookmark. The LibraryLinksOption specifies the format of the link.
For more information, see Links to Analyses in the Library.
// From the bookmark manager we can get the BookmarkLinks object, which we then can ask for links for a specific bookmark.
BookmarkLinks links = bookmarkManager.Links;
Uri uri;
// We try to get the different kinds of links for the added bookmark.
// Link to the bookmark in analysis in TIBCO Spotfire client.
if (links.TryGetUri(bookmark, LibraryLinksOption.Path, out uri))
{
}
// Link to TIBCO Spotfire Server redirect page for the bookmark.
if (links.TryGetRedirectUri(bookmark, LibraryLinksOption.UrlEncodedPath, out uri))
{
}
// Link to the bookmark in TIBCO Spotfire Web Player.
if (links.TryGetWebPlayerUri(bookmark, LibraryLinksOption.Id, out uri))
{
}
// Link to TIBCO Spotfire Web Player Server redirect page for the bookmark.
if (links.TryGetWebPlayerRedirectUri(bookmark, LibraryLinksOption.UrlEncodedPath, out uri))
{
}
Event Handlers
BookmarksChanged will fire when a bookmark has been added, removed or modified, either locally or due to a synchronization with the library.
Synchronization
Bookmarks stored in the library will be synchronized with all other open instances of the analysis.
Converting legacy bookmarks
Legacy bookmarks can be batch converted through BookmarkCollection.Migrate().