Deploying MicroStrategy Widgets as Plugins
There are a few different ways to deploy your widget from Flex to MicroStrategy. The easiest, in my opinion, is to simply use the Deploy menu directly from Flex Builder. This will handle all of the configurations you need on web, and even place the SWF in the proper locations if you can directly map to them (if not, it’s a simple copy/paste). Another option is to build a “Widget Changes” package as outlined in the SDK, though honestly I’ve never got that to work. Unfortunately, both of those deployments update the widgets.xml, visualizations.xml and styleCatalog.xml files directly. This means your deployments are lost after an upgrade. Today, I’ll go over the steps of manually deploying your widgets in a long term sustainable manner using the plugin architecture. This is also an easy method should you run into trouble with either of the “recommended” two methods.
Plugins: A Brief Introduction
Starting with MicroStrategy 9, you can deploy Web Customizations using a plugin architecture. You simply create files that contain your differences and place them in a structure that mimics the web folder structure. These are then kept in a folder with the name of your plugin, and can simply be dropped into the Webplugins folder. During upgrades, these aren’t touched, plus they can easily be saved or copied to other installations.
Here’s an example: When the Web Server starts up, say it finds a folder in the Webplugins folder called Bryans_Plugin. Inside that folder are folders that mimic the web folder structure for WEB-INFxmlstyleCatalog.xml. Inside that folder, I haven’t copied the entire styleCatalog.xml file, but only the nodes I want to add or change. Web will then take that file, compare it to the “real” styleCatalog.xml file, and merge them together. The result is that only the part I’ve intended to add or change is modified, and future upgrade changes are still picked up.
Before we get too far, here’s a little tip for your Development Environment. Every time you modify something in your plugin (other than the swf itself), you have to restart the Web Server for the changes to be picked up. However, there is a setting you can turn on in WEB-INFmicrostrategy.xml that will make it reload those files after every action. There is a slight performance degradation, so you don’t want to leave this on all the time, but it’s very handy when developing, especially when sharing a server with other developers so as not to interrupt.
<parameter name=”reloadConfigurationFiles” value=”true” />
With that setting on, you can modify your web configuration files and plugins, then simply go back to your web page and refresh to see the changes.
I mentioned that you don’t have to do this with SWFs. This is because those are files that are directly served over http and are not processed in memory. You may have to clear your local browser’s cache though in order to see the changes. This is just a feature of our web browser to cache files for speed. Sometimes, you can run into a situation where you’re caching an older SWF and not getting the update.
Components of a Widget/Visualization
To deploy a Widget, you only had to add a line into the widgets.xml file under WEB-INFxmlconfig. To deploy a Visualization, you have to add a line into the visualizations.xml file in the same location, but also add a style into the styleCatalog.xml file under WEB-INFxml. A lot of the flags and parameters are optional, and for an exhaustive list you should consult the SDK documentation. Today, I’m just going to talk about the barebones options to get your Widget/Visualization deployed.
My plugin looks like this:
In Webplugins, create the folder Bryans_Plugin.
Inside that folder, create two folders: swf and WEB-INF.
Inside the WEB-INF folder, create the folder xml and inside that, create the folder config.
Assuming a .NET environment, you should have a folder structure that looks like this:
The first file we’ll setup is widgets.xml. Deploying here is so that you can use your widget in Flash mode in a Document.
<widget id=”YourWidget” isApp=”true” rslPath=”../plugins/Bryans_Plugin/swf/YourWidget.swf” scope=”52″ title=”Your Widget”/>
The isApp flag is set to true to indicate that your widget was built using the VisFramework and is used instead of the fqcn field that you may observe elsewhere in the widgets.xml file. Scope simply declares where your widget can be used. In this case, 52 refers to Grid/Graph objects, which is what you’re more than likely using to feed your widget data.
The next file is visualizations.xml. Deploying here is so that you can use your widget in DHTML mode or on a Grid directly.
<visualization desc=”Your Widget” scope=”3″ style-name=”visBry-YourWidget”/>
Scope is an integer value between 1 and 4 that defines where you can use your visualization. The possible values are:
1 – Report Only (Enabled via the Tools -> Custom Visualizations menu on a Grid Report)
2 – Grids on a Document
3 – Reports & Grids on a Document
4 – Full Documents
Option 4 is pretty powerful, as it allows you to pass multiple data sets to a single visualization. I’ll cover that in more detail in a later post, as that allows you to build some pretty cool things. The most common one you’ll use is 3.
The style will refer to an entry in the style catalog, and it simply directs your visualization to it’s file.
The final file you’ll need to provide is styleCatalog.xml. This is the associated style as defined in the visualizations.xml file.
<?xml version=”1.0″ standalone=”no”?>
<!DOCTYPE StyleCatalog SYSTEM “dtds/styleCatalog.dtd”>
<StyleCatalog description=”MSTR System Style Catalog” name=”MSTRStyleCatalog”
<Style name=”visBry-YourWidget” transform=”RWFlashTransform”>
<ActualParameter name=”flashFile” value=”../plugins/Bryans_Plugin/swf/YourWidget.swf”/>
<ActualParameter name=”containerWidth” value=”-1″/>
<ActualParameter name=”containerHeight” value=”-1″/>
<ActualParameter name=”includeBaseURL” value=”false”/>
The key pieces of information here are the Style Name and the flashFile parameter. I don’t believe that the other 3 parameters I’ve provided are required, but out of habit, this is the file structure I always use.
It’s important to not get confused by the two terms Widgets and Visualizations. Just think of them as different ways to use the same Flash SWF. Whenever I deploy a “widget”, I deploy it using the method above which includes both widgets.xml and visualizations.xml.
Once complete, you’ll have your small plugin folder that can be zipped/backed up and easily copied/deployed to multiple environments and you won’t use your deployments after upgrades. It’s important to note that you’ll still need to recompile your SWFs with the updated VisFramework.swc’s from each release. But, with this deployment method, you can simply drop the updated SWFs into the plugin as the rest of the deployment configurations will remain the same.