Existing examples of JavaScript extensions that are available for developers to use today include: audio, phone and SMS. More information about these extensions, which are part of the BlackBerry Open Source Project, can be found in the BlackBerry WebWorks API Reference guide.

This lab will demonstrate how developers can create their own JavaScript extensions to be used in their BlackBerry WebWorks applications. The complete source code for the JavaScript extension that will be created as part of this lab is attached at the end of this article.

The steps involved in completing this lab are:

1.  Start a new BlackBerry Project
2.  Add a package to the src folder
3.  Create a ScriptableFunction Class
4.  Create a Scriptable Class
5.  Create a Widget Extension Class
6.  Create a library.xml file
7.  Export all source and resource files to a JAR

Start a new BlackBerry Project

You will use the BlackBerry® Java Plug-in for Eclipse® (with component pack 5.0) to create and package the source code of your JavaScript extension. This is a separate development tool from the BlackBerry WebWorks SDK, and is typically used by Java developers to write BlackBerry applications.

1. Open the BlackBerry Java Plug-in for Eclipse.

2. To keep your development environment organized, it is helpful to use a unique workspace for JavaScript extensions:

3. Create a new Blackberry Project by selecting the “New” and “Project …” items from the File Menu.

4. Name your project AlertExtension. Ensure that the BlackBerry JRE 5.0.0 is selected as the project specific JRE and click on the Finish button. If there is no option available for the 5.0 BlackBerry JRE, it means the 5.0 component pack is not installed in Eclipse. This component pack is required for building custom JavaScript extensions for BlackBerry WebWorks Applications, as they make use of new APIs introduced in 5.0.

Add a package to the src folder

1. Expand the AlertExtension twistie within the Package Explorer window

2. Create a new package by right clicking on the src folder and selecting the “New” and “Package” menu items:

3. Name the package samplecode and click on the Finish button:

Create a ScriptableFunction Class

The ScriptableFunction class contains the actual implementation of the given feature’s functionality that you wish to include in this JavaScript Extension.

1. Create a new Java class by right clicking on the samplecode package name and selecting the “New” and “Class” menu items:

2. Name your class AlertFunction and enable the public and final modifiers. Specify a superclass of net.rim.device.api.script.ScriptableFunction:

3. Add the following code to the AlertFunction class. This logic will cause the BlackBerry smartphone to vibrate for a specified duration of time, provided as a command line argument:

package samplecode;
import net.rim.device.api.script.ScriptableFunction;
import net.rim.device.api.system.Alert;
public final class AlertFunction extends ScriptableFunction {
public Object invoke(Object obj, Object[] args) throws Exception
{
if (!Alert.isVibrateSupported()) {
return UNDEFINED;
}
if (args.length == 1) {
int duration = ((Integer)args[0]).intValue();
Alert.startVibrate(duration);
}
return UNDEFINED;
}
}

Create a Scriptable Class

Scriptable classes are registered with the JavaScript Engine that is used by the active BrowserField of a BlackBerry WebWorks application. The JavaScript extension enables a BlackBerry WebWorks application to communicate with underylying Java code. Calls to JavaScript methods are handled by the ScriptableFunction class, while calls for property or constant values can be returned as standard Objects (e.g. String or Integer).

1. Create a new Java class by right clicking on the samplecode package name and selecting the “New” and “Class” menu items.

2. Name the class AlertNamespace and enable the public and final modifiers. Specify a superclass of net.rim.device.api.script.Scriptable:

3. This class will be used to associate JavaScript method or property keywords provided by a BlackBerry WebWorks application to Java-defined BlackBerry functionality. Add the following code to the AlertNamespace class. This sample demonstrates how to extend two methods named “isVibrateSupported” and “vibrate”:

package samplecode;
import net.rim.device.api.script.Scriptable;
import net.rim.device.api.system.Alert;
public final class AlertNamespace extends Scriptable {
public static final String FIELD_VIBRATE_SUPPORTED = "isVibrateSupported";
public static final String FIELD_VIBRATE = "vibrate";
private AlertFunction callVibrate;

public AlertNamespace() {
this.callVibrate = new AlertFunction();
}

// The getField() function is called when the
//  dot '.' extender is used on your JavaScript object.
public Object getField(String name) throws Exception {
if (name.equals(FIELD_VIBRATE_SUPPORTED)) {
return new Boolean(Alert.isVibrateSupported());
} else if (name.equals(FIELD_VIBRATE)) {
return this.callVibrate;
}
return super.getField(name);
}
}

Since a WebWorks application may run on BlackBerry smartphone models with different hardware configurations, it is considered good practice to always check whether a hardware feature is supported before it is used.

Create a WidgetExtension Class

The WidgetExtension class ties everything together and acts as the interface between the JavaScript engine of a BlackBerry WebWorks application and the custom logic you have defined in your AlertNamespace class.

1. Create a new Java class by right clicking on the samplecode package name and selecting the “New” and “Class” menu items.

2. Name your class AlertExtension and enable the public and final modifiers. Ensure that the AlertExtension class will be defined with an interface of net.rim.device.api.web.WidgetExtension. To add an interface, click on the add button next to the Interfaces field and then type in the full name of the interface:

3. The AlertExtension class should contain the following method stubs:

* getFeatureList() – this method is called when the JavaScript extension is created. It will return an array containing the names of the available features that it provides.

* loadFeature() – this method is called when an application loads a resource that requires a <feature> id that you supplied in getFeatureList()

* register() – this method is called so that your extension can get a handle to the configuration document or BrowserField object if it needs it.

* unloadFeatures() – this method is available if you need to do any clean-up when your extension is unloaded.

4. Add the following code to the AlertExtension class:

package widgetpackage;
import org.w3c.dom.Document;
import net.rim.device.api.browser.field2.BrowserField;
import net.rim.device.api.script.ScriptEngine;
import net.rim.device.api.web.WidgetConfig;
import net.rim.device.api.web.WidgetExtension;

public final class AlertExtension implements WidgetExtension {
public String[] getFeatureList() {
String[] result = new String[1];
result[0] = "sample.alert";
return result;
}

public void loadFeature(String feature, String version,
Document doc, ScriptEngine scriptEngine) throws Exception {
if (feature == "sample.alert") {
scriptEngine.addExtension("sample.alert", new AlertNamespace());
}
}

public void register(WidgetConfig arg0, BrowserField arg1) {
// TODO Auto-generated method stub
}

public void unloadFeatures(Document arg0) {
// TODO Auto-generated method stub
}
}

Create a library.xml file

The purpose of the libary.xml file is to provide a public definition of feature names available within the given JavaScript extension, and an association to internal Java Class names. The latter is used by the BlackBerry WebWorks SDK when applications are packaged.

1. Create a new file by right clicking on the src folder within the AlertExtension project and selecting the “New” and “Other …” menu items.

2. Select XML from the New popup window and click on the Next button:

3. Name your file library.xml:

4. Add the following XML to the library.xml:

<?xml version="1.0" encoding="UTF-8"?>
<library>
<extension>
<entryClass>samplecode.AlertExtension</entryClass>
</extension>
<features>
<feature id="sample.alert" version="1.0.0" ></feature>
</features>
</library>

When a developer uses this JavaSCript extension in their WebWorks application, they will add the feature “sample.alert” to their configuration document (config.xml). The BlackBerry WebWorks SDK is then able to determine which internal class name is to be packaged into the compiled application (in this case “samplecode.AlertExtension”).

Export all source and resource files to a JAR

The final step is packaging any source and resource files that make up a JavaScript extension into a JAR file.

1. Export the relevant contents of AlertExtension project by right clicking on the src folder and selecting the “Export …” menu item:

2. Choose to export resources to a JAR file on the local file system

3. From the JAR File Specification popup window, only export the Java source files and resources found within the src/samplecode folder. Specify a descriptive name for the destination JAR file and click Finish.

The JavaScript Extension is now complete, and ready to be used in a BlackBerry WebWorks Application. For more information on this topic, see the following article: Using JavaScript Extensions in your BlackBerry WebWorks Application development.