MicroStrategy ONE

Create Basic Code for a Custom Widget in iOS

After you have registered a custom widget with MicroStrategy Web and applied it to a report or report grid in a document, you are ready to write the code that will render the MicroStrategy data as a custom widget on a mobile device. You can create this code directly inside the Xcode project of the mobile application or as part of a static library project which can be imported into the application’s project.

Use the following steps to create the code of a custom widget directly within the application’s project.

  1. Inside the Xcode project, select New from the File menu, then File.


  2. Select Cocoa Touch, then Objective-C class.


  3. Give a name to your widget class and make sure it extends MSIWidgetViewer. In this example, the name of the class is MyDemoWidget.


  4. Make sure the targets for which the widget class will be used are selected. In this case, the widget will be available both for iPhone and iPad targets. Click Create.


  5. Rename the .m file for widget to .mm. This is required because MicroStrategy Mobile framework uses certain C++ libraries internally.
     

  6. Enable ARC (Automatic Reference Counting) to simplify the widget code by eliminating the need to do manual memory management.

    If the widget is being coded in an application that has ARC enabled at the project level, no action has to be taken since ARC will be used in the widget’s code. By default, the MicroStrategyMobile project is not enabled with ARC, so the ARC setting has to be enabled for the widget’s code. To enable ARC: 

    1. Select the target the setting will be applied to. If you are using the MicroStrategyMobile project and intend to use the widget in both iPhone and iPad applications, the setting has to be enabled in both targets. 

    2. Go to Build Phases, then Compile Sources. 

    3. Select the file and add the –fobjc-arc flag on each file ARC will be used for. 

  7. In the .h file, extend the MSIWidgetViewer class to indicate to MicroStrategy that you are creating a widget and import as well the MSTRWidgetHelper.h file.

    As the super class for MicroStrategy widgets, MSIWidgetViewer contains default implementations of the methods that all MicroStrategy widgets use to display their data. The MSTRWidgetHelper.h file contains several methods required to build the widget. 

  8. Override at least the following main callback methods

    Copy 
    -(id)initViewer:(ViewerDataModel*)ipDataModel withCommander:(Commander*)ipCommander withProps:(NSString*)ipProps
    -(void)cleanViews
    -(void)recreateWidget
    -(void)handleEvent:(NSString*)ipEventName

    For more information about them, please refer to the MSIWidgetViewer class topic. 

  9. Implement the overridden methods.

    While implementing the callback methods, you will iterate through the data on the grid to obtain all the information required by the custom widget. This information is contained in the grid’s MSIHeaderValue objects. Refer to the Iterating through Data topic for an example of how to access this information while e iterating on the grid’s data. 

  10. Create the widget’s UI code, which must contain the logic to display MicroStrategy data from a report or document according to your initial design as well as the information retrieved in the previous step. 

  11. Add additional functionality used by the widget, such as drilling and acting as a selector or target. Please reference the other topics in this section, such as Drilling and Opening a Panel Stack as an Information Window, for additional information on how to add functionality to the widget. 

  12. Ensure the views created are added as a widget’s sub-view in the recreateWidget method implementation. 

You can download a shell version of this widget code, which contains a basic implementation of the callback methods as well as the implementation of iterating through the grid’s data. This shell code assumes that you are using ARC and that you will add the code to handle creating and adding the UI. 

Next step: Now that you have the basic code for your custom widget, you can add additional functionality.