All Products
Document Center

Custom JSAPI

Last Updated: Feb 23, 2021

To call the native function on a page, for example, to display an ActionSheet or contacts dialog box, you need to expand a JavaScript API (JSAPI). With the JSAPI, you can add an entry to call the native function on an HTML5 page. Certain functions are implemented in native mode by implementing the handler method in the custom JSAPI class.

The HTML5 container component has the following capabilities:

  • Provides abundant embedded JSAPIs to implement functions such as push, pop, and title setup. For more information, see Built-in JSAPI.
  • Allows you to customize JavaScript API (JSAPI) and plug-in to satisfy your business expansion needs.

This topic describes how to use a demo of HTML5 container and offline package to customize a plug-in that modifies the navigation bar when an HTML5 page is loaded.

About this task

You can customize a JSAPI by using two methods:

  • Plist registration
  • Code registration


Plist registration

  1. Create a JSAPI class:

    • Naming format: For consistency with the names of plug-ins provided by the container by default, the created JSAPI name begins with XXJsApi4, where XX is a custom prefix.
    • Base class: All JSAPIs are derived from PSDJsApiHandler.
    • Basic method: Rewrite method -(void)handler:context:callback: in the .m file. When this JSAPI is called in the frontend, the call request will be forwarded to this method.
    • The following describes the parameters in this method:
      Name Description
      data The parameter passed in when an HTML5 page calls this JSAPI.
      context The context of the current HTML5 page. For details, see PSDContext.h.
      callback The callback method after the JSAPI call is complete. This method returns a dictionary as the calling result to the HTML5 page.
      Refer to the following code example:
      1. #import <NebulaPoseidon/NebulaPoseidon.h>
      2. @interface MPJsApiHandler4OpenSms : PSDJsApiHandler
      3. @end
      4. @implementation MPJsApiHandler4OpenSms
      5. - (void)handler:(NSDictionary *)data context:(PSDContext *)context callback:(PSDJsApiResponseCallbackBlock)callback
      6. {
      7. [super handler:data context:context callback:callback];
      8. // Open the SMS.
      9. NSURL *url = [NSURL URLWithString:@"sms://xxx"];
      10. BOOL reasult = [[UIApplication sharedApplication] openURL:url];
      11. callback(@{@"success":@(reasult)});
      12. }
      13. @end
  2. Register the JSAPI. Register this JSAPI in the custom Plist file.

    • Create a PLIST file for unified management of custom JSAPI and plug-ins. You can download the template file and add this file to your project.
    • In the JsApis array, register the JSAPI class created in the previous step.
    • The registered JSAPI is of the dictionary type and includes two items.

      1. <th>Parameter</th>
      2. <th>Description</th>

      1. <td>jsApi</td>
      2. <td>The name of the JSAPI called on the HTML5 page. <div class="alert alert-notes">**Caution:** Attach a prefix to the name of a custom JSAPI to distinguish the custom JSAPI from the built-in JSAPI of the container. The purpose is to prevent unavailability due to interaction between the custom JSAPI and the built-in JSAPI.</div></td>

      1. <td>name</td>
      2. <td>The name of the created JSAPI class.</td>

      • Specify the path of the custom PLIST file during container configuration initialization.

      Refer to the following code example:

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

Code registration

In addition to customizing a JSAPI using the Plist, you can register a custom JSAPI by calling the interface method provided by the Nebula container.

  1. Create a plug-in. See Customize a plug-in.

  2. Implement the addJSApis method in the plug-in.

    1. - (void)addJSApis
    2. {
    3. [super addJSApis];
    4. // Register JSAPI by code.
    5. PSDJsApi *jsApi4DemoTest2 = [PSDJsApi jsApi:@"demoTest2"
    6. handler:^(NSDictionary *data, PSDContext *context, PSDJsApiResponseCallbackBlock responseCallbackBlock) {
    7. responseCallbackBlock(@{@"result":@"jsapi-demoTest2 The result of calling Native"});
    8. }
    9. checkParams:NO
    10. isPrivate:NO
    11. scope:self.scope];
    12. [self registerJsApi2Target:jsApi4DemoTest2];
    13. }
    • The following table describes the parameters required for registration.
      Parameters Description
      jsApi The name of the JSAPI called on the HTML5 page.
      handler JSAPI handler function, which is the same as the handler method in the PLIST registration mode.
      checkParams Specifies whether parameters are checked. Set this parameter to NO.
      isPrivate Specifies whether the JSAPI is a private JSAPI. Set this parameter to NO.
      scope Scope of action. Set this parameter to self.scope.

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

What to do next

  1. Call the custom JSAPI on an HTML5 page.
  2. Add a breakpoint in the handler method and check whether the parameters provided by the HTML5 page meet the expectations.
  3. Check whether the results returned by the HTML5 page meet the expectations.