One-click JSViz Visualizations - Extending JSViz for Spotfire®

Introduction

The extension type ConfiguredVisualization in the TIBCO Spotfire® API allows for the addition of a one-click automated configuration of an existing plot. By essentially supplying a custom autoconfiguration section to the instantiation of the plot this would allow for a one-click histogram version of the barchart or bubble chart version of the scatter plot.

This feature becomes even more valuable when working with JSViz, as the JSViz out of the box doesn't specify the visualization type or rendering logic at all for that matter. By creating a ConfiguredVisualization based on JSViz, it is possible have a dedicated button that automatically sets JavaScript files, configuration parameters and configures a best-effort sane default data setting for the plot.

The Configured Visualization menu entry and doughnut symbol.

Below the one-click doughnut from the sample project at the bottom of the page with it's doughnut-specific custom JSViz property pages.

Prerequisites

• Visual Studio 2013 or later
• TIBCO Spotfire® Analyst installation or Portable
• TIBCO Spotfire® Server
• TIBCO Spotfire® SDK
• JavaScript Visualization Framework 3.5. New for 3.5 release is the possibility to add custom windows forms property pages.
• Developer's already using this mechanism moving to 3.5 from a previous version of JSViz, will need to update their extension code as described in the code example at the bottom of the page.

Implementation

Setting up a configured visual by it self isn't very hard, and there is a Configured Visual example that should suffice as an introduction to how Configured Visuals work for those that want to customize the configuration of out of the box visualizations. What this how-to covers that is not covered elswhere is how to extend another TIBCO Spotfire® extension, such as the JSViz.

Extending Extensions

It is possible to extend custom extensions in TIBCO Spotfire®, but you will need to take care of a few quirks concerning the TIBCO Spotfire® build proces in the package builder as well as load-order of custom functionality.

Setting up Visual Studio

In order to build the Visual Studio project you need to link to the appropriate .dll in visual studio - for the SpotfirePS.ConfiguredJSViz project reference SpotfirePS.Framework.JSVisualization.dll and for the SpotfirePS.ConfiguredJSVizForms project reference SpotfirePS.Framework.JSVisualization.dll and SpotfirePS.Framework.JSVisualizationForms.dll.

1. Install the JSViz .sdn in your Spotfire Analyst client, by upploading it to the Spotfire Server's deployment section, connecting your analyst and download the update to your installed client. The new funcitonality will be downloaded to your Spotfire installation's Modules folder.
2. Copy all the JSViz* folders to your or next to your visual studio build folder
3. Link to SpotfirePS.Framework.JSVisualization.dll from the JSViz Core* folder

It is possible to do this without copying the files, but it is recommended to do so since your installation folder may experience changes as the server admin modifies the distribution on the server.

Setting up the Package Builder

For the package builder to be able to find all the references the extension needs to find, all the JSViz* packages previously copied to the working directory (above) will need to be added to the package builder configuration.

1. Click add and navigate to the each JSViz* folder
2. Before clicking Add, uncheck the Source Folder check box, so the package builder can find and use the already existing modules.xml
3. After compiling your custom VS project, you may now also add your new extension (leaving the Source Folder check box checked) to Package Builder.
4. It is recommended to
   • In the main project try to register JSViz, so that the configured visual will find the right type
   • Name the Package Builder project extension something that comes after "JSViz" alphabetically - this affects custom extension load-order and the JSViz:dlls must be loaded dynamically before the configured visualization can be loaded. 
   • Add a forms project that only does AddIn-registration of the property dialog, to make sure the UI gets registered at the same time as the configured visualization

It should now look something like this:

When deploying to the server, the "Deploy to Server" button in the package builder cannot be used, as the JSViz packages will already be deployed. Use the file menu or right click to build only the two configured visual *.spk files.

Core Code Implementation

The following code will provide the configuration needed for a one click doughnut chart visualization (See zip file for full code example and files).

internal sealed class ConfiguredVisualizationFactory : ConfiguredVisualFactory<JSVisualizationModel>
{

	public ConfiguredVisualizationFactory() :
		base(
		JSVisualizationIdentifiers.JSVisualization,
		ConfiguredVisualizationTypeIdentifier.ConfiguredVisualizationIdentifier,
		VisualCategory.Visualization,
		Resources.doughnut,
		null)
	{
		
	}

	protected override void AutoConfigureCore(JSVisualizationModel visual)
	{   
		base.AutoConfigureCore(visual);

                // Adding custom property pages, new in 3.5
                visual.AddGeneralPropertyPage();
                visual.AddPropertyPage("Doughtnut", "SpotfirePS.ConfiguredJSVizForms", "SpotfirePS.ConfiguredJSVizForms.DoughnutPropertyPage");

            
		var doc = visual.Context.GetAncestor<Document>();

		// Add the files;
		var cr = doc.CustomNodes.AddNewIfNeeded<ContentRepository>();

		var content = System.Text.Encoding.UTF8.GetString(GetEmbeddedResource("SpotfirePS.ConfiguredJSViz.scripts.jQuery.js"));
		var urlReference = new UrlReference(@"scripts.jQuery.js", string.Empty, content, ContentType.JS, true);
		cr["scripts.jQuery.js"] = urlReference;
		visual.UrlInclusions.Add("scripts.jQuery.js");

		content = System.Text.Encoding.UTF8.GetString(GetEmbeddedResource("SpotfirePS.ConfiguredJSViz.scripts.d3.v3.min.js"));
		urlReference = new UrlReference(@"scripts.d3.v3.min.js", string.Empty, content, ContentType.JS, true);
		cr["scripts.d3.v3.min.js"] = urlReference;
		visual.UrlInclusions.Add("scripts.d3.v3.min.js");

		content = System.Text.Encoding.UTF8.GetString(GetEmbeddedResource("SpotfirePS.ConfiguredJSViz.scripts.DoughnutChart.js"));
		urlReference = new UrlReference(@"scripts.DoughnutChart.js", string.Empty, content, ContentType.JS, true);
		cr["scripts.DoughnutChart.js"] = urlReference;
		visual.UrlInclusions.Add("scripts.DoughnutChart.js");

		content = System.Text.Encoding.UTF8.GetString(GetEmbeddedResource("SpotfirePS.ConfiguredJSViz.scripts.JSViz.js"));
		urlReference = new UrlReference(@"scripts.JSViz.js", string.Empty, content, ContentType.JS, true);
		cr["scripts.JSViz.js"] = urlReference;
		visual.UrlInclusions.Add("scripts.JSViz.js");

		visual.AutoConfigure();
	}

// Helper methods here (see zip for details)
}

Most notable change for the custom property page support in 3.5:

• The property pages will have to be referenced by assembly and class names to the JSViz model class as strings, as it does not link to any UI classes.
• All custom property pages must have a constructor taking the single instance of the JSViz model class
• Developers extending the JSViz framework this way pre 3.5 moving to 3.5 will have to explicitly add any needed original property pages as they are no longer added by default when overriding the autoconfiguration of the plot.

spotfireps.configuredjsviz_352.zip