MicroStrategy ONE

MSIWidgetViewer Class in iOS

When you create a class in Xcode that you intend to use as a MicroStrategy widget, it must extend the MSIWidgetViewer class. The MSIWidgetViewer class takes care of most of the implementation required by a widget in MicroStrategy Mobile. Functionality such as retrieving the data, being notified when selectors change, performing the logic to handle link drilling and regular drilling, handling selections, and displaying Information Windows are done either by the MSIWidgetViewer class or by its widgetHelper object.

Because the MSIWidgetViewer class is a child of UIView, all the functionality available in UIView is also available in MSIWidgetViewer.

Lifecycle methods

When you create the code for a custom widget, you must implement the following required life-cycle methods inherited from the MSIWidgetViewer class:

  • Widget initialization

    Copy 
    - (id)initViewer:(ViewerDataModel*)_viewerDataModel withCommanderDelegate:(id<MSICommanderDelegate>)_commander withProps:(NSString*)_props;

    This is the initialization method of the widget. It is called only once, when MicroStrategy Mobile creates the widget the first time a document is rendered (i.e., it is not called when a user changes a selector in the document). This method should include the code to perform any initialization tasks that need to be done only once, such as initializing variables and preparing external data. For example, the code for creating the widget's UI should not be in this method, but should be in recreateWidget, where it can be reused for both initialization and re-initialization.

  • Widget cleanup

    Copy 
    - (void)cleanViews

    This method is used to clear all the widget’s views in order to save memory. It is called the first time the widget is loaded, and later if the widget needs to be recreated or deleted.

  • Widget UI setup

    Copy 
    - (void)recreateWidget

    This method is called every time the widget is recreated, which could be during initialization, when a layout or panel changes, or when the widget’s source selector is changed. The cleanViews method, which is usually called immediately before this method, should contain the code to clean all subviews, and recreateWidget should contain the code to recreate all subviews.

    In this method you add the widget’s subviews to the MSIWidgetViewer’s view so that they are rendered on the screen. You can use the UIView’s method addSubview to do this. For example, you could add a collection view to the widget by calling [self addSubview:self.collectionView]; because collectionView is a property of MSIWidgetViewer.  

  • Widget updates upon selector changes

    Copy 
    - (void)handleEvent:(NSString*)ipEventName

    This method is called if a selector that targets the widget changes its selection.

    The typical implementation of this method first calls [widgetHelper reinitDataModels];  to refresh the widget’s data model based on the new selection and then calls [self recreateWidget]; to update the widget’s views with the new data.

There are additional life-cycle methods that can be called for different events, but they are not required. For additional information, please check the MSIWidgetViewer and MSTRWidgetHelper header files.