Web and WebWorks Development

[#1]

Applications created using the BlackBerry WebWorks App Platform have the ability to integrate with the data, features and capabilities from the underlying Java® development environment as well as the native BlackBerry® smartphone through the use of special JavaScript® objects.  These objects are called JavaScript extensions.

Existing examples of JavaScript extensions 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.

Update (Jan 19, 2012):

The content listed below is no longer up to date. This article has been moved to the Using JavaScript extensions guide within the BlackBerry HTML5 microsite.

---

Configure your BlackBerry WebWorks application to recognize the JavaScript Extension

a) Using the BlackBerry WebWorks Plug-in for Eclipse

After creating a new BlackBerry Widget application you will notice that a folder named "ext" exists within your Project inside of the Package Explorer Window:

Begin by importing the JAR file of the JavaScript Extension into this folder.  Right click on the "ext" folder and select the "Import" menu item:

Choose the "File System" option from the General import source and click the Next button.

Navigation to the location on your file system where the JAR file exists.  Select only that file and click on the Finish button.

The JAR file should now be visible within the ext folder inside of the Package Explorer window:

Grant your application permission to use the functionality found within this extension by adding its feature to the Widget Permissions section of the configuration document.  Open the config.xml file and click on the Widget Permissions tab at the bottom.  Click on the "Add Feature" button and find the feature name provided by the JavaScript extension:

The feature name should appear within the Widget Access window of the project.  You can now access the functionality defined within the JavaScript extension from your WebWorks application.

b) Using the BlackBerry WebWorks Plug-in for Microsoft Visual Studio 2008

After creating a new BlackBerry Widget Project, you will notice that a folder named "Extensions" exists within your Project inside of the Solution Explorer Window:

Begin by adding the JAR file of the JavaScript Extension into this folder.  Right click on the "Extensions" folder and select the "Add" and "Existing Item..." menu items:

Navigation to the location on your file system where the JAR file exists.  Select only that file and click on the Add button.

The JAR file should now be visible within the ext folder inside of the Package Explorer window:

Grant your application permission to use the functionality found within this extension by adding its feature to the Widget Permissions section of the configuration document.  Open the config.xml fileand scroll to the Widget Permissions section at the bottom.  Click on the "Local" domain and then click on the "Add Feature" button.  Locate the feature name provided by the JavaScript extension:

The feature name should appear within the Widget Access window of the project.  You can now access the functionality defined within the JavaScript extension from your WebWorks application.

c) Using the BlackBerry WebWorks Packager

Add a folder named "ext" to the root of the folder where you have defined your config.xml and starting page (e.g. index.html):

Adding the JAR file of the JavaScript Extension into the "ext" folder:

Grant your application permission to use the functionality found within this extension by adding its feature to the the configuration document.  Open the config.xml file and add a feature element such as the following:

<?xml version="1.0" encoding="UTF-8"?>
<widget xmlns="http://www.w3.org/ns/widgets" xmlns:rim="http://www.blackberry.com/ns/widgets" version="1.0.0.0">
  <name>MyExtensionTest</name>
  

<feature id="sample.alert" required="false" version="1.0.0"/>

  <content src="index.html"/>
</widget>

Consume the JavaScript Extension in your BlackBerry WebWorks application

Add JavaScript to your BlackBerry WebWorks application to allow it to communicate with the method and property names that have been defined within the JavaScript Extension.  The following sample demonstrates how you can modify index.html to integrate with the AlertExtension.jar extension.  This sample allows the user to specify a given amount of time (ms) to vibrate the BlackBerry smartphone.

<html>
   <head>
      <meta name="viewport" content="user-scalable=no, width=device-width;"/>
      <script type="text/JavaScript">
      function vibrateAlert()
      {
         if (

sample.alert.vibrateSupported

) 
         {
            var ele = document.getElementById("txtLength");
            var iDuration = parseInt(ele.value);
            

sample.alert.vibrate(iDuration)

;
         } 
         else
            alert('sample.alert.vibrate not supported');
      }
      </script>
</head>
<body>
   duration <input type="text" id="txtLength" value="1000"/> (ms) 
   <input type="submit" value="Alert" onclick="vibrateAlert()"/> 
</body>
</html>