Integrating the Properties Viewer in Your Widget

One of the nicest features of the MicroStrategy Visualization Framework is that widget default properties are stored in the metadata along with the report.  The framework comes with a very easy to use Properties editor automatically saves the current settings with the report when it’s saved.  This allows you to use the widget in multiple locations, provide flexible configurations that users can change, but also store those defaults per report similar to how the existing MicroStrategy widgets provide the same options with formatting.  I haven’t found a sample explicitly talking about this useful feature on it’s own, so today I’ll share one that walks through everything you need to add a Properties dialog with metadata saving abilities to your widget.



Properties.as – I originally found this in the Map Visualization sample, and have simplified it.  I filled in some generic variables (YourString, etc) and commented where you need to make changes.  Just create a package in your project called CustomPackage (or whatever) and drop this into it.


package CustomPackage
{
import com.microstrategy.web.vf.viewer.properties.BasePropertiesViewer;

import mx.core.Application;

public class Properties extends BasePropertiesViewer
{
     
    private var _propChanged:Boolean = true;
     
        public function displayshowPropEditor() :void
        {
        this.showPropEditor(null);
        }
     
        public function setInitialProps():void {
    formatWidgetFromProps();
}
        override protected function changeWidgetProperty(key:String, value:String):void
        {
super.changeWidgetProperty(key, value);
_propChanged = true;
   }
     
        override protected function getEditorLayout():XML
        {
        //add/remove your variables here
        var YourBoolean:Boolean = this.propertiesHelper.getBoolean("YourBoolean");
        var YourNumber:Number = this.propertiesHelper.getNumber("YourNumber");
        var YourString:String = this.propertiesHelper.getString("YourString");
     
//setup your properties window xml, straight forward, copy/paste these lines
        var ed:XML = <layout>
        <input id={"YourBoolean"} type="2" label="Type 2 is a checkbox:" value={YourBoolean} enabled="true"/>
        <input id={"YourNumber"} type="4" label="Type 4 is a text box:" value={YourNumber} enabled="true"/>
        <input id={"YourString"} type="4" label="Some more text:" value={YourString} enabled="true"/>
        </layout>;
        return ed;
        }
     
        override protected function formatWidgetFromProps():void
        {
            if (_propChanged)
            {                                    
//same declarations as previous
var YourBoolean:Boolean = this.propertiesHelper.getBoolean("YourBoolean");
var YourNumber:Number = this.propertiesHelper.getNumber("YourNumber");
var YourString:String = this.propertiesHelper.getString("YourString");
       
//this is where you pass these properties back to the main application.
       (Application (this.control) as  YourApplicationName).changeProperties(YourBoolean, YourNumber, YourString);
    Application (this.control).invalidateProperties();
   _propChanged = false;
        }
        }
     
        override protected function getDefaultPropValues():Object
        {
            var obj:Object = new Object();
            obj["YourBoolean"]=true;
            obj["YourNumber"]=50;
            obj["YourString"]="hello";
            return obj;
        }
             
}
}

ImplementProperties.mxml – this is some excerpt code for implementing the Properties Viewer.  Effectively, you just import it, and wire it’s initialize function to your Create Model event.  You can now right click your widget, change properties, and when you click OK, it will call back to the application and pass the new values.  You can then react to those values as needed.

You set defaults in the Properties.as, but it will first search the metadata for any saved defaults.  These defaults are saved with the report instance, so if you have 3 reports, each can have different saved defaults.  Simply run your report with your widget inside MicroStrategy the first time, set the properties how you’d like, then save it in web.  The defaults will now be pulled for all users.

If you export your report to Flash (MHT or PDF), the values of the Properties at the time of export are set as the defaults in the exported file.  You can still change them in the exported file at run time, but when closed, they’ll default back to what they were at export time.


<mx:Script>
        <![CDATA[
import CustomPackage.Properties;
...
private var appPropViewer:Properties;
..
private function onComplete():void {
appPropViewer = new Properties();

(Controller.getInstance(appNameSpace)).createModel("model1");
(Controller.getInstance(appNameSpace)).addEventListener(ControllerEvent.VIEWER_MODEL_REQUESTS_COMPLETE, initPropEditor);
}
...
private function initPropEditor(e : Event) :void {
//Set up the properties viewer for application.
appPropViewer.model = IReportData(Controller.getInstance(appNameSpace).getModelById("model1"));
appPropViewer.control = UIComponent(this);
appPropViewer.createContextMenu();
appPropViewer.initProps();
}

public function changeProperties(YourBoolean:Boolean, YourNumber:Number, YourString:String):void {
buildControl(YourBoolean, YourNumber, YourString);
}
]]>
</mx:Script>

Note: the buildControl function shown at the end of the code above is just a placeholder for calling back to whatever method you have that actually does the work of building your control.  This illustration is just showing how to collect and store Property information, and then pass it back to whatever working method you need to consume them in.

I’ve used this code with Flex SDK 3.5 and 4.1, MicroStrategy 9.0.2 and 9.2.

One other unfortunate side effect is that access to the Properties menu in a Widget requires a Web Professional license.  This is because the permission is tied to the “Web Format Report” permission which is a Web Professional permission.  It’s unfortunate that the requirement bleeds over to the VisSDK, most likely because most (if not all) out of the box Widget properties are format related.  Still, this can be a very useful tool for handling properties and saving settings with very easy code.  Enjoy!

You may also like...