MicroStrategy ONE

Work with Resource Bundles in iOS

As defined in Apple's Mac OS documentation, a bundle is a directory with a standardized hierarchical structure that holds executable code and the resources used by that code. The MicroStrategy Mobile project includes such a bundle that contains all the resource files from the MicroStrategy Mobile framework. These resource files include images (icons, buttons, etc.) that are used in MicroStrategy Mobile (iPhone and iPad).

Any application that uses the MicroStrategyMobileSDK framework (either the MicroStrategy Mobile application or custom applications embedding the MicroStrategyMobileSDK framework) must have a bundle file of this type called FinalBundle.bundle in its project in order for the MicroStrategy framework to find its resources as needed. The steps to set up a project to use the MicroStrategy Mobile framework can be found under Setting up a Custom Project.

Certain customizations require that you change the definition of files contained in the FinalBundle.bundle, which are used by the MicroStrategyMobile framework. Such customizations include:  

  • Changing images  
  • Changing strings files  
  • Changing widget style mappings (modifying vis.plist)  
  • Changing selector style mappings (modifying selector.plist)  

The recommendation is to create a custom FinalBundle.bundle and a script that overwrites the files that exist in the out-of-the-box FinalBundle.bundle with the ones that exist in the custom FinalBundle.bundle at build time.

The custom FinalBundle.bundle is an exact copy of the out-of-the-box FinalBundle.bundle that has been modified to include the customization changes. The out-of-the-box bundle is located under the MicroStrategyMobileSDK.framework/Resources folder, while the custom FinalBundle.bundle is located under the MicroStrategyMobileSDK.framework/Custom folder.  

Because the files in the custom FinalBundle.bundle do not work as delta files, you have to make a complete copy of the out-of-the-box bundle and then make your changes to that copy. Then, at build time, the script overwrites the files that exist in the out-of-the-box FinalBundle.bundle with the ones that exist in the custom FinalBundle.bundle.

To use this logic in your application, do the following in the application’s project:  

  1. Download a custom FinalBundle.bundle from here.  

  2. In Xcode, either drag the empty custom FinalBundle.bundle into the desired group  or select the desired group where the custom  FinalBundle.bundle will reside, then right-click and select Add Files to.

     

  3. Select the targets the FinalBundle.bundle will be used for and make sure the Copy items into destination group’s folder is selected.

     

  4. Copy the MergeBundles.sh script available either inside the MicroStrategyMobile project’s folder or here, to your application project’s root folder. The image below shows the project structure of the MicroStrategyMobile project’s folder, which has the MergeBundles.sh script directly under it.
     
     

  5. Access the Build Phases - Run Script section for the application’s target and add the following script.

    Copy 
    # This script is used to merge custom resources to MicroStrategy Bundle
    # Argument 1: The target bundle name.
    # Argument 2: The custom bundle location.
    sh "$SRCROOT/MergeBundles.sh" FinalBundle.bundle "$SRCROOT/Custom/FinalBundle.bundle"

The screenshot below shows this configuration for the MicroStrategyMobileIPad target of the MicroStrategyMobile app.

The MicroStrategy Mobile project is preconfigured in this way for both the MicroStrategyMobileIPhone and MicroStrategyMobileIPad targets.

The screenshot below showcases both the out-of-the-box FinalBundle.bundle available in the Resources group of the MicroStrategyMobile project and the custom FinalBundle.bundle available in the Custom group.

It is important to note that the hierarchy structure inside FinalBundle.bundle should be maintained when customizing the resource files, and the custom files should have the same names as the original files.

The custom resource files include custom images used in MicroStrategy Mobile. If you plan to use custom images on the standard navigation bar when you rebrand the MicroStrategy Mobile application, you should use transparent pixels for the background. Any colored pixels are automatically converted to white pixels.