Version 2021

Embed Content and Controls in iOS on a Partial Screen

You can embed MicroStrategy data in a third-party application, suppress the MicroStrategy navigation toolbar, and add your own custom controls or toolbar for navigation.

The code snippets below illustrate how to embed MicroStrategy data in part of the screen and include additional text and navigation controls in the remaining space. In this sample code, the additional text is information about the currently selected MicroStrategy object and the navigation controls are three buttons—Back, Execute My Report, and Fit Width/Exact Size. There is a navigation bar on an iPad, but not on an iPhone.

When you launch the application, the contents of the MicroStrategy Shared Reports folder are displayed. The folder is specified by a value in ConnectionsInfo.plist and can be changed in that property list file. The report that is executed when you tap the Execute My Report button is specified in the code itself.

  • You declare a UIView for the rectangular area on the screen where the MicroStrategy data will be displayed (MicroStrategy view) and the view controller for the MicroStrategy view.

    Copy
    /* MSTRObject View Controller to keep track of MSTR Objects like Report, Document or Folder. */
    @property (strong,nonatomic) MSTRObjectViewController *mMicroStrategyVC; 
    /* UIView to keep track of MSTR Objects like Report, Document or Folder contents. */
    @property (strong, nonatomic) IBOutlet UIView *mMicroStrategyView;
  • You also declare the methods that perform the actions associated with the three buttons—Back, Execute My Report, and Fit Width/Actual Size.

    Copy
    /* This method displays back view of current navigation. */
    - (IBAction) handleBack: (id)sender;
    /* This method displays specified report in screen layout window. */
    - (IBAction) handleReport: (id)sender;
    /* This method fits layout data (i.e. report/document contents) into available screen layout window. */
    - (IBAction) handleFitWidth: (id)sender;
    /* This method keeps track of navigation items. */
    - (void) pushViewController: (id)viewController withView: (UIView *)view;
  • You define the constants for the connection info file, the folder to display initially, and the report to execute when the Execute My Report button is tapped.

    Copy
    /* Required Constants. */
    /* Report ID To execute. */
    #define kHANDREPORTID       @"E63834A411D5C49EC0000C881FDA1A4F"
    /* Connection Info to get connection details. */
    #define kCONNECTIONINFO     @"ConnectionInfo.plist"
    /* Folder Tag. */
    #define kFOLDERID           @"FolderID"
  • You also declare the variables for the controls and the methods that will let users navigate the data displayed in the MicroStrategy view. These controls and methods are defined in the xib file. The purpose of the stack variables and the popViewController method is to support custom backwards navigation.  

    Copy
    @interface PartialScreenViewController () {
    /* IBOutlet Variable to keep track of view information. */
    IBOutlet UITextView* mViewInfoView;
    /* IBOutlet Variable to keep track of back button view. */
    IBOutlet UIButton* mBackButtonView;
    /* IBOutlet Variable to keep track of execution report button  view. */
    IBOutlet UIButton* mExecRepButtonView;
    /* IBOutlet Variable to keep track of execution report button  view. */
    IBOutlet UIButton* mFitWidthView;
    /* IBOutlet Variable to keep track of navigation. */
    IBOutlet UINavigationItem* mMSTRNavigationItem;
    /* Variable to keep track of MSTRObjectViewController objects. */
    NSMutableArray* mMSTRVCBackwardStack;
    /* Variable to keep track of object views. */
    NSMutableArray* mMSTRViewBackwardStack;
    /* Variable to keep track of layout screen width. */
    BOOL mIsFitWidth;
    /* This is method pops navigation item by 1 level up on the stack. */
    - (void) popViewController;
  • When the application finishes launching, it invokes the didFinishLaunchingWithOptions method. In this method, you load the MicroStrategy view. Since MicroStrategy takes up only part of the screen, you need to set a property to eliminate the gap where the status bar would be. You can do other customization in this method, after the view is loaded, but this is not illustrated in the code snippet below.

    Copy
    - (BOOL)application:(UIApplication *)iApplicationdidFinishLaunchingWithOptions:(NSDictionary *)iLaunchOptions {
        NSSetUncaughtExceptionHandler(&uncaughtExceptionHandler1);
        BOOL launchedOK = [ super application: iApplication didFinishLaunchingWithOptions: iLaunchOptions];
        self.window = [[UIWindow alloc] initWithFrame:[[UIScreen mainScreen] bounds]];
        // Override point for customization after application launch.
        if ([[UIDevice currentDevice] userInterfaceIdiom] == UIUserInterfaceIdiomPhone) {
            self.viewController = [[PartialScreenViewController alloc] initWithNibName:@"PartialScreenViewController_iPhone" bundle:nil];
        } else {
            self.viewController = [[PartialScreenViewController alloc] initWithNibName:@"PartialScreenViewController_iPad" bundle:nil];
        [self.viewController setWantsFullScreenLayout: YES ];// Without this, dismissModalViewController will add a gap for the status bar
        self.window.rootViewController = self.viewController;
        [self.window makeKeyAndVisible];
        return launchedOK;
    }
  • The application calls the setupNavigationControllerWithApplicationLauncher method. In this method, you initialize the MicroStrategy view using the settings in ConnectionInfo.plist. In these code snippets, a value in this property list is used to specify the folder that will be displayed initially in the MicroStrategy view.

    Copy
    - (void)setupNavigationControllerWithApplicationLauncher: (ApplicationLauncherController*) applicationLauncherController {
        [ Generic setupConnectInfoFromPlist: kCONNECTIONINFO ];
        [ Generic getSDKEnvSettings].isEnforceShowCloseForRetry = YES;
        [ Generic getSDKEnvSettings].isEnforceEnableDocumentZoom = YES;
    }
  • When the view has been loaded, the application calls the viewDidLoad method. In this method, you do additional setup from the xib, load the folder whose contents will be displayed in the MicroStrategy view, initialize the stack values, specify that the view will not take up the full screen, and disable the Back button. The stack values allow you to create your own custom backward navigation.

    Copy
    - (void)viewDidLoad{
        [super viewDidLoad];
        // Do any additional setup after loading the view, typically from a xib.
        NSString* plistFilePath = [[NSBundle mainBundle] pathForResource:kCONNECTIONINFO ofType:nil];
        NSDictionary* plistDict = [[NSDictionary alloc] initWithContentsOfFile:plistFilePath];
        // Point to a specific folder.
        self.mMicroStrategyVC = [[MSTRObjectViewController alloc] init];
        NSString* folderID = [ plistDict objectForKey: kFOLDERID ];
        ...
        // Load the Shared Reports folder and initialize stack values.
        [ self.mMicroStrategyVC loadWithObjectID: folderID type: ObjectTypeFolder ];
        self.mMicroStrategyVC.delegate = self;
        mMSTRVCBackwardStack = [[NSMutableArray alloc] init];
        mMSTRViewBackwardStack = [[NSMutableArray alloc] init];
        mIsFitWidth = NO;
        // Set back button to disabled
        mBackButtonView.enabled = NO;
        [self addChildViewController:self.mMicroStrategyVC];// "will" is called for us
        self.mMicroStrategyVC.view = self.mMicroStrategyView;
        // when we call "add", we must call "did" afterwards
        [self.mMicroStrategyVC didMoveToParentViewController:self];
     }
  • When the report, document, or folder is successfully loaded from the server, the application calls the initMSTRView method. In this method, you obtain the current View Controller and tell it to initialize the view properties. You also invoke pushViewController to add the new view to the stack to support backwards navigation and set the view controller delegate for changed views on the iPad. The pushViewController and popViewController methods work together to let users go forward and backwards in the MicroStrategy view.

    Copy
    - (void)initMSTRView: (UIViewController *)viewController {
        id <SDKViewControllerDelegate> vc = (id <SDKViewControllerDelegate>)viewController ;
        [self pushViewController:vc withView:self.mMicroStrategyVC.view];
        [vc setViewFrame: CGRectMake(0, 0, self.mMicroStrategyVC.view.frame.size.width, self.mMicroStrategyVC.view.frame.size.height)];
        [vc setViewOrientation:NO];
        [vc setFitWidth:mIsFitWidth];
        [vc refresh];
        // set delegate for IPadFolderController and IPadDataController
        [vc setCurrentObjectChangedDelegate: self];
    }
  • Whenever the object loaded in the MicroStrategy view changes, the application calls the currentObjectChanged method. In this method, you assemble the text that is displayed in the View Info text box and determine whether to enable or disable the Back button. You can also add code here to perform other manipulations that are needed after the object is loaded.

    Copy
    - (void)currentObjectChanged: (ObjectInfo *)objectInfo {
        // Display object (view) info in mViewInfoView
        NSString* path = [objectInfo.iconPath isEqualToString:@""] ? objectInfo.name:objectInfo.iconPath;
        NSString* viewInfo = [NSString stringWithFormat:@"Object ID: %@\nObject Type: %d\nObject Path: %@", objectInfo.objectID, objectInfo.type, path];
        mViewInfoView.text = viewInfo;
        // Set Back button to enabled or disabled
        mBackButtonView.enabled = ([[mMSTRVCBackwardStack lastObject] respondsToAction:SDKBackAction withObject:nil] || [mMSTRVCBackwardStack count] > 1);
    }
  • For each of the methods that handle a button action defined in the xib file, you provide the code that performs the desired action. These buttons provide the custom navigation that you define to take the place of the MicroStrategy navigation toolbar that you suppressed.
    • In the handleBack method, you provide the code to handle what happens when the Back button is tapped. The code is different for navigation in the Shared Reports folder and when you execute a report using the Execute My Report button. The popViewController method takes the view back one level on the stack.

      Copy
      - (IBAction)handleBack: (id)sender {
          // If the current view is folder / report view, go back to previous folder or report,
          // if the current view is My Report view, go back to previous report binary, if cannot go back, switch to folder / report view.
          if ([[mMSTRVCBackwardStack lastObject] respondsToAction:SDKBackAction withObject:nil])
              [[mMSTRVCBackwardStack lastObject] performAction:SDKBackAction withObject:nil];
          else if ([mMSTRVCBackwardStack count] > 1) {
              [self popViewController];
              self.mMicroStrategyVC.view = [mMSTRViewBackwardStack lastObject];
              id<SDKViewControllerDelegate> currentVC = [mMSTRVCBackwardStack lastObject];
                  {
                  [currentVC setFitWidth:mIsFitWidth];
                  [currentVC refresh];
                  }
          }
    • In the handleReport method, you provide the code to handle what happens when the Execute My Report button is tapped. View Controllers are not static, but can be modified externally. For example, the code snippet below sets the background color programmatically and points to a specific report.

      Copy
      - (IBAction)handleReport: (id)sender {
          // Point to a specific report.
          self.mMicroStrategyVC.view = [[UIView alloc] initWithFrame:self.mMicroStrategyView.frame];
          [self.mMicroStrategyVC.view setBackgroundColor:[UIColor lightGrayColor]];
          [self.mMicroStrategyVC loadWithObjectID: kHANDREPORTID type: ObjectTypeReportDefinition]
    • In the handleFitWidth method, you provide the code to handle what happens when the Fit Width/Actual Size toggle button is tapped. You use this method to force MicroStrategy to redraw itself to the specified width parameters when you embed a MicroStrategy report or document in a partial screen. This allows you to use the same report object in different sized displays.

      Copy
      - (IBAction)handleFitWidth: (id)sender {
          mIsFitWidth = !mIsFitWidth;
          id<SDKViewControllerDelegate> currentVC = [mMSTRVCBackwardStack lastObject];
          [currentVC setFitWidth:mIsFitWidth];
          [currentVC refresh];
          NSString* buttonTitle = (mIsFitWidth) ? @"ActualSize" : @"Fit Width";
          [mFitWidthView setTitle: buttonTitle forState: UIControlStateNormal];
      }
  • You need to add methods to support forward and backwards navigation. The pushViewController and popViewController methods work together to let users go forward and backwards in the MicroStrategy view. The pushViewController method adds the current view to the stack, and the popViewController method takes the view up one level on the stack.

    Copy
    - (void)pushViewController: (id <SDKViewControllerDelegate>)viewController withView: (UIView *)view {
        [mMSTRVCBackwardStack addObject:viewController];
        [mMSTRViewBackwardStack addObject:view];
    }
    - (void)popViewController{
        if ([mMSTRVCBackwardStack count] > 0)
        [mMSTRVCBackwardStack removeLastObject];
        if ([mMSTRViewBackwardStack count] > 0)
        [mMSTRViewBackwardStack removeLastObject];
    }