Developer

Loading the Library

Once you have appropriately set up the environment, you can start coding apps.

Context

These steps are required only if you use the built-in datasource adapter to fetch and parse OData entries. If you use your current data provider and pass the data to the framework-powered tiles, you can skip these steps. See Adding Configuration-Based Tiles to Programmed View Controllers.

Procedure

  1. Set up a connection (via SAP Mobile Platform or HTTP), or use demo mode.
    • For demo mode, you need the offline XML files, which represent the OData payloads (service document, metadata, OData entries).
    • To use the secure SAP Mobile Platform channel, authenticate the user, for example, by using the Logon component of Mobile Application Framework: MAFLogonManagerNG and MAFLogonUING.
  2. Manage configuration changes. Validate and apply your custom configuration. If you have not created a custom configuration, or if the configuration is invalid, you can use the bundled layout XML.
    The Extensibility Framework does not use any automatic fallback strategies for configuration issues. However, it exposes the APIs required to validate the configuration, and then uses either the bundled or the external custom configuration profile.
  3. Instantiate an SDMDataSource instance and invoke the loadModel: API to fetch the service document and the metadata. When the call completes, instantiate a MAFSDMDataSourceAdapter (or your custom MAFDataSourceAdapter) and set it via the MAFCore –setDataSourceAdapter API.
  4. Start the Extensibility Framework using one of the MAFCore loadWithWindow: APIs.

Example

To use the styling library, link against the required reusable MAFUIComponents library. The Extensibility Framework automatically applies the default SAP style to the rendered UI elements. (The default style metadata, SAPDefaultStyles.xml, is part of the MAFUIComponents.bundle. Include this resource in your project.)

To apply custom styling, add the style XML resource to your project and use the MAFCore -setApplicationSpecificStylePath API to set the path that points to your custom style data (see the code below).

This example shows the adapted didFinishLaunchingWithOptions: method application delegate API, which executes the required steps to setup and start the Extensibility engine. This example uses an HTTP connection to access OData content. If you need an ODP/SAP Mobile Platform connection, use MAFLogonManager for authentication.

- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions
{    
    self.window = [[[UIWindow alloc] initWithFrame:[[UIScreen mainScreen] bounds]] autorelease];
    
    // set image folders
    [[MAFUIManager sharedInstance] setImagesBundleName : @"MAFExtensibilityImages.bundle"];
    
    self.viewController = [[[ViewController alloc]init] autorelease];
    self.window.rootViewController = _viewController;
    
    // pass the styling relevant configuration path
    NSString* appStylePath = [[NSBundle mainBundle] pathForResource:@"AppSpecificStyles" ofType:@"xml"];
    [[MAFCore sharedInstance] setApplicationSpecificStylePath: appStylePath];
    // initialize the datasource adapter
    [SDMDataSource setUsername:@"<username>"];
    [SDMDataSource setPassword:@"<xxxxxxxx>"];
    [SDMDataSource setRequestType:SDMHTTPRequestType];

    [SDMDataSource setBaseURL:@"<endpoint url>"];
  
    // validate the XML
    VALIDATION_RESULT validationResult = [[MAFCore sharedInstance] validateCustomConfiguration:configPath];

    // 1. if no layout XML found in the Documents dir, use the bundled one
    if( validationResult == CUSTOM_CONFIGURATION_NOT_FOUND )
    {
        [[MAFCore sharedInstance] setUseBuiltInConfiguration:YES];
        [self startExtensibilityEngine];
    }
    // 2. custom configuration found, but failed validation
    else if( validationResult == CUSTOM_CONFIGURATION_FOUND_AND_NOT_VALID )
    {
    	// inform the user, perform fallback logic and so on.
    }
    // 3. custom configuration found and valid -> use it
    else 
    {
        [[MAFCore sharedInstance] setUseBuiltInConfiguration:NO];
        [self startExtensibilityEngine];
    }

    return YES;
}

- (void) startExtensibilityEngine
{
    // initialize the SAP Mobile Platform OData facade
    __block SDMDataSource* dataSource = [[SDMDataSource alloc] init];
   
    // initialize the data source facade
    [dataSource loadModel:^(NSError* error)
    {         
         if( !error )
         {
             // initialize and set the data source adapter
             MAFSDMDataSourceAdapter* datasourceAdapter = [[[MAFSDMDataSourceAdapter alloc] init] autorelease];
             [[MAFCore sharedInstance] setDataSourceAdapter:datasourceAdapter];

             // Start Extensibility
             [[MAFCore sharedInstance] loadWithWindow:self.window andCompletionBlock:^(NSError* error)
              {
                  if(error)
                  {
                      NSLog( @"Error occured during model loading. Domain: %@, error code %i, details:%@", error.domain, error.code, [error.userInfo objectForKey:NSLocalizedDescriptionKey] );
                  }
              }];
         }
        // loadModel failed
         else
         {
             UIAlertView *alertView  = [[[UIAlertView alloc] initWithTitle:@"Error" message:@"Data model could not be loaded" delegate:nil cancelButtonTitle:@"Close" otherButtonTitles:nil] autorelease];
         }
         
         [dataSource release];
     }];
}