Custom JSAPIs

The HTML5 container component provides the following capabilities:

• Built-in JSAPIs for page push, pop, and title settings. For more information, see Built-in JSAPIs.

• Custom JSAPIs and plugins to meet your business needs.

This topic uses the H5 Container and Offline Package demo to show how to create a custom plugin that 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.

   • Specify the path to the custom Plist file when you initialize the container configuration.

     • For more information about initializing 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

You can also register a custom JSAPI by calling an interface method provided by the Nebula container, without using a Plist file.

1. Create a new plugin. For more information, see Custom plugins.

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 describes the registration parameters.

     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 a complete example, see 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.