Widget Plug-in Interface

If you want to define a custom plug-in to use with a widget, the principal class of your plug-in must support the Widget Plug-in interface. This interface provides basic initialization support for your plug-in code along with access to the web view of your widget. You can also use this interface to register custom JavaScript objects for use by your widget code.

While the Widget Plug-in interface is required of all widget plug-ins, implementing the optional WebScripting protocol provides you with the ability to bridge data between your plug-in's native code and your widget's JavaScript code. Learn more about the WebScripting protocol by reading Using Objective-C From JavaScript and WebScripting.

Methods

The following sections describe the methods of the Widget Plug-in interface.

initWithWebView:

Default initializer for your plug-in.

- (id) initWithWebView:(WebView*)webView

Use this method to perform basic initialization of your widget‚Äôs principal class. The webView parameter contains the view object used to display the widget contents. This method is called before your widget‚Äôs HTML page is fully loaded.

If you need to do additional initialization after your plug-in is loaded, you should expose a method from your plug-in object to perform that initialization. You can then call that method from the onload event handler of your widget’s HTML page. See “windowScriptObjectAvailable:” for information on how to create a bridge between your Objective-C classes and JavaScript.

Implementation of this method is required.

windowScriptObjectAvailable:

Indicates that a scriptable object is now available.

- (void) windowScriptObjectAvailable:(WebScriptObject *) windowScriptObject

This method notifies you that the window scripting object is available for your use. You can use this method to expose your Objective-C classes as JavaScript objects so that they can be accessed by your widget code.

When your plug-in receives the windowScriptObjectAvailable: message, call the setValue:forKey: method of windowScriptObject to associate your Objective-C object (the value) with the object name JavaScript clients should use.

The following example registers an instance of the MyScriptObject class:

- (void) windowScriptObjectAvailable:(WebScriptObject *) scriptObj

{

    MyScriptObject* myObj = [[MyScriptObject* alloc] init];

    [scriptObj setValue:myObj forKey:@"MyScriptObj"];

}

After you publish your object in this manner, you can refer to it in JavaScript code by the name you gave it. From the preceding example, if the object exposed a method called finishInitialization, you could call that method using the following JavaScript code:

function MyWebPageLoadHandler()

{

    if (MyScriptObj)

    {

        MyScriptObj.finishInitialization();

    }

...

}