Register a Custom Widget for iOS with MicroStrategy Web

In order to use a custom widget in a mobile application, you must register it with MicroStrategy Web. Registering a widget with MicroStrategy Web creates a link between the widget and a specific style. When the style is applied to a MicroStrategy report or document, it is saved in the metadata as a property of that report or document. If the report or document is then viewed in a mobile application, the style saved in the metadata is used to determine the View class that should be used to display the MicroStrategy data. The mobile application project has a properties file (vis.plist) that contains a mapping between widget styles registered in MicroStrategy Web and the View classes for the corresponding mobile widgets that can be used in the mobile application.

Styles have transforms and layout definitions associated with them. For widgets viewed in MicroStrategy Web, these files are responsible for the functionality and display logic of the widget. However, for widgets that will be used in mobile applications, these files are irrelevant because the functionality and display logic are provided by the Objective-C code written in Apple Xcode.

You use the Web Customization Editor to register a widget with MicroStrategy Web. This process creates a plug-in that associates the custom widget with a specific style. The style for the widget serves as the key that links the widget applied to a report or document in MicroStrategy Web with the widget built in Apple Xcode to display the report or document data in a mobile application.

You need to register the iPhone and iPad styles separately. During the registration process, you can either create a different style for each or use the same style for both. Your decision will affect how the widget can be used when it is applied to a report grid in a document.

• When you apply a widget style to a report, you can specify different styles for iPhone and iPad—with the result that the report can be visualized in both an iPhone application and an iPad application.  

• When you apply a widget style to a report grid in a document, you can apply only one style. If you have registered the same style for both iPhone and iPad, then you can apply that style to a document and it will work for both iPhone and iPad applications. However, if you registered two different styles, you can apply only one of them to the document—with the result that the report grid can be visualized in either an iPhone application or an iPad application, but not both.  

To register a custom widget that can be applied to a report or document run in a mobile application, follow the steps provided below. These steps create the plug-in that enables the widget in MicroStrategy Web.  

1. Launch the Web Customization Editor.

   The Web Customization Editor is discussed in detail in the Web SDK section of the MSDL under Customizing MicroStrategy Web -> Part I: Fundamentals of Customization -> Web Customization Editor.

2. Create a new plug-in Navigate to Windows -> Preferences. On the Preferences screen, choose MicroStrategy on the left and click the Change button for Customization Folder under MicroStrategy Preferences on the right. Click New, enter the plug-in name, and click OK. for the custom widget and give it a meaningful name—for example, MyCustomMobileVis.  
3. Expand MicroStrategy Web Configuration inside the Application Settings view to display the list of settings that can be modified.  

4. Create a new style for the custom widget.

   Because this is a style for a widget that will be used in a mobile application rather than in MicroStrategy Web, only the style name is used by the mobile application. The code to display the widget is created in Apple Xcode, and neither the transform nor the layout definition file associated with the widget style in MicroStrategy Web is used. However, in order for the style to show up on the Visualization Settings and Properties tab, the style must have a transform that extends AbstractReportDataVisualizationTransform, AbstractRWDataVisualizationTransform, or AbstractReportXMLTransform in the com.microstrategy.web.app.transforms package.  

   1. Expand Styles to view the list of available styles.  

   2. Navigate to iPhoneReportDataXMLAllStyle and duplicate it by right-mouse-clicking the style and selecting Duplicate. 

      1. On the Duplicate Style dialog, give the new style a meaningful name—for example, MyCustomMobileVisStyle.  

      2. Click OK. 

   3. The new style is added to the list of styles under Styles, and a Style Properties tab opens on the right.

      
      

   4.  Do the following on the Style Properties tab: 

      1. The name you gave the style is displayed in the Name field. 

      2. Optionally, you can provide a description for the style in the Description field. 

      3. The name of the transform used by the style—iPhoneReportDataXMLTransform—is displayed in the Transform field. This transform extends AbstractReportXMLTransform (located in the com.microstrategy.web.app.transforms package).

         This transform is not used, but it must be associated with the style in order for the style to show up on the Visualization Settings and Properties tab.  

   5. Save the style. 

   6. If you are going to create different styles for iPhone and iPad, repeat steps 4.a – 4.e to create the second style. 

   7. Collapse Styles. 

5. Add widget settings for the style you just created for the custom widget. If you plan to use this widget for both iPhone and iPad applications, add settings for both. 

   1. Expand Visualization Settings.

      If you don't seeVisualization Settings, do the following: 

      1. Choose Preferences from the Windows menu. 

      2. On the Preferences dialog, select MicroStrategy in the left-hand pane and check the Show Advanced Options check box on the right. 

   2. If you plan to use this widget for an iPhone application, double-click iphone, and the Visualization Settings tab opens. Your custom widget style is displayed in the Visualization Name pane. 

   3. Select your custom widget style in the Visualization Name pane and configure its settings as described below. 

      1. Style Name is used as the key for the widget. It links the widget applied to a report or document in MicroStrategy Web with the Objective-C View class created for the widget when it is used in a mobile application.
         

         If you plan to apply the widget to a report grid in a document and want to view the widget in both an iPhone and an iPad application, you must select the same Style Name and ID for both the iPhone and iPad styles.

         

      2. ID is optional. By default, the name of the style is entered. You can accept this value or change it. 

      3. Scopedetermines whether the widget can be applied to a report, a report grid in a document, a specific layout for a document, or an entire document. Since only a report and a report grid in a document are applicable for mobile widgets, you should check one or both of these checkboxes.

      4. Description is used to identify the widget. This is what appears in the list of available styles when you apply the widget to a report or document. Enter a meaningful name that describes what the widget produces—for example,MyCustomMobileVis. 

      5. You must delete the entry in Description ID. If you leave the entry (that was copied from your duplicated style), it will override your description and you will not see your widget in the drop-down list of iPhone/iPad widgets when you try to apply your widget to a report or report grid in a document. 

      6. Projects specifies the projects in which you can apply the widget to reports and documents. Enter the names of appropriate projects, separated by the pipe symbol. 

      7. If your widget uses more than one data provider, you must do the following: 

         • For Minimum Secondary Data Providers, enter a number representing the least number of additional data providers (that is, in addition to the primary data provider) that can furnish data to the underlying document. 

         • For Maximum Secondary Data Providers, enter a number representing the most number of additional data providers that can furnish data to the underlying document. 

      8. If you have built a custom properties editor for the custom widget, you must select the style associated with that properties editor from the Property Editor Style drop-down. If the style you duplicated above has a properties editor associated with it, you should use the drop-down to remove the style. 

         If you have not yet built a properties editor and decide to do so later, you can come back and add this setting. 

   4. Save the widget settings for the style. 

   5. If you plan to use this widget for an iPad application, double-click ipad and repeat steps 5.c – 5.d to add widget settings for the iPad style.

      If you plan to apply the widget to a report grid in a document and want to view the widget in both an iPhone and an iPad application, you must use the same Style Name and ID for the iPhone and iPad styles.

You have now registered your custom widget with MicroStrategy Web. The plug-in created by the Web Customization Editor includes the name of the new widget style (which will be used as the key to link to the Objective-C View class for the widget in a mobile application) and any properties that you enabled.

Next step:  Once you have registered a custom widget, you are ready to apply the widget to a report or a report grid in a document in MicroStrategy Web