Mobile Platform as a Service:Custom JSAPIs

The HTML5 container component provides the following features:

• A rich set of built-in JSAPIs for features such as page push, pop, and title settings. For more information, see Built-in JSAPIs.

• Support for custom JSAPIs and plugins to meet your business needs.

This topic uses the H5 Container and Offline Package demo to demonstrate how to create a custom plugin. This plugin modifies the navigation bar when an HTML5 page loads.

About this task

You can customize a JSAPI in one of two ways:

• Plist registration

• Code registration

Procedure

Plist registration

1. Create a JSAPI class.

   • Naming convention: To maintain consistency with the default plugin names, prefix your JSAPI class name with XXJsApiHandler4, where XX is a custom prefix.

   • Base class: All JSAPIs must inherit from PSDJsApiHandler.

   • Implement the handler method: In the .m file, override the -(void)handler:context:callback: method. When the frontend calls this JSAPI, the request is forwarded to this method.

   • The parameters for this method are as follows:

     Parameter	Description
     data	The parameters passed from the HTML5 page when this JSAPI is called.
     context	The context of the current HTML5 page. For details, see PSDContext.h.
     callback	The callback method that is invoked after the JSAPI call is complete. This method passes the result to the HTML5 page as a dictionary.

     The following code provides an example.

       #import <NebulaPoseidon/NebulaPoseidon.h>
       @interface MPJsApiHandler4OpenSms : PSDJsApiHandler
       @end
       @implementation MPJsApiHandler4OpenSms
       - (void)handler:(NSDictionary *)data context:(PSDContext *)context callback:(PSDJsApiResponseCallbackBlock)callback
       {
       [super handler:data context:context callback:callback];
       // Open the system text message app.
       NSURL *url = [NSURL URLWithString:@"sms://xxx"];
       BOOL reasult = [[UIApplication sharedApplication] openURL:url];
       callback(@{@"success":@(reasult)});
       }
       @end

2. Register the JSAPI in your custom Plist file.

   • To manage custom JSAPIs and plugins together, you can create a new Plist file. Download the DemoCustomPlugins.bundle.zip template file and add it to your project.

   • Register the JSAPI class that you created in the previous step under the JsApis array.

   • The registered JSAPI is a dictionary that contains the following two items:

     Name	Description
     jsApi	The name of the JSAPI interface called on the HTML5 page. Important To prevent conflicts with built-in JSAPIs, add a prefix to your custom JSAPI name.
     name	The class name of the JSAPI that you created.

   • You must also specify the path to the custom Plist file when you initialize the container configuration.

     • For more information about how to initialize the H5 container, see H5 container quick start.

     The following code provides an example.

       - (void)application:(UIApplication *)application beforeDidFinishLaunchingWithOptions:(NSDictionary *)launchOptions
       {  
           // Initialize the container.
           // [MPNebulaAdapterInterface initNebula];
     
           // Specify the custom JSAPI path and preset offline package information.
           NSString *presetApplistPath = [[NSBundle mainBundle] pathForResource:[NSString stringWithFormat:@"DemoCustomPresetApps.bundle/h5_json.json"] ofType:nil];
           NSString *appPackagePath = [[NSBundle mainBundle] pathForResource:[NSString stringWithFormat:@"DemoCustomPresetApps.bundle"] ofType:nil];
           NSString *pluginsJsapisPath = [[NSBundle mainBundle] pathForResource:[NSString stringWithFormat:@"DemoCustomPlugins.bundle/Poseidon-UserDefine-Extra-Config.plist"] ofType:nil];
           [MPNebulaAdapterInterface initNebulaWithCustomPresetApplistPath:presetApplistPath customPresetAppPackagePath:appPackagePath customPluginsJsapisPath:pluginsJsapisPath]
       }

Code registration

Instead of using a Plist file, you can register a custom JSAPI by directly calling an interface method provided by the Nebula container.

1. For information about how to create a new plugin, see the Custom plugins document.

2. Implement the addJSApis method in the plugin.

    - (void)addJSApis
    {
        [super addJSApis];
   
        // Register the JSAPI using code.
        PSDJsApi *jsApi4DemoTest2 = [PSDJsApi jsApi:@"demoTest2"
                                              handler:^(NSDictionary *data, PSDContext *context, PSDJsApiResponseCallbackBlock responseCallbackBlock) {
                                                  responseCallbackBlock(@{@"result":@"Processing result from native call by jsapi-demoTest2"});
                                              }
                                          checkParams:NO
                                            isPrivate:NO
                                                scope:self.scope];
        [self registerJsApi2Target:jsApi4DemoTest2];
    }

   • The following table lists the registration parameters and their descriptions.

     Parameter	Description
     jsApi	The name of the JSAPI interface called on the HTML5 page.
     handler	The JSAPI handler function. This function is the same as the handler method used for Plist registration.
     checkParams	Specifies whether to check parameters. Set this to NO.
     isPrivate	Specifies whether the JSAPI is private. Set this to NO.
     scope	The scope. Set this to self.scope.

For an example, see the implementation of the MPPlugin4TitleView class in the code sample.

What to do next

1. Call the custom JSAPI from the HTML5 page.

   

2. Add a breakpoint in the handler method to verify the parameters from the HTML5 page.

   

3. Verify the result returned to the HTML5 page.