Welcome!

Welcome to the official BlackBerry Support Community Forums.

This is your resource to discuss support topics with your peers, and learn from each other.

inside custom component

Web and WebWorks Development

Common BlackBerry WebWorks development pitfalls that can be avoided

by Retired on ‎11-24-2010 03:11 PM - edited on ‎05-10-2013 05:13 PM by BlackBerry Development Advisor (46,095 Views)

Attention:

 

The BlackBerry® Web Plug-in for Eclipse® and BlackBerry® Web Plug-in for Microsoft® Visual Studio® have received their end-of-life announcement.  Developers are encouraged to use the BlackBerry Ripple™ emulator, and the BlackBerry WebWorks SDK for testing and previewing their Web content.

  


  

This article contains information about common issues that developers may encounter while building BlackBerry WebWorks applications.  By raising awareness about the root cause of these problems, developers can introduce habits and best practices into their daily development lives that will help reduce and/or avoid the occurances of these issues.

 

  • Unable to Access External Domains
  • Unable to Access BlackBerry WebWorks API / JavaScript® Extension features
  • Dealing with Runtime Errors
  • Common JavaScript Language Issues
  • Slow / Frozen BlackBerry WebWorks applications on BlackBerry® 6
  • Accessing Embedded vs File System Resources
  • Resource Name is Not valid
  • BlackBerry Smartphone Simulator connection issues

 


 

Unable to Access External Domains

 

You must grant your BlackBerry WebWorks application permission to access any external domains.  If you do not, the following error will occur when the application attempts to sent an HTTP request to that domain:

 

domains.png

 

Domains can be white listed individually, or the wildcard * can be used to white list all domains.

 

HTML example:

 

Clicking <a href="http://www.blackberry.com">this link<a> will cause the above error to occur if the domain "www.blackberry.com" is not white listed.

AJAX example:

 

//The following AJAX request will cause the above error to occur if the domain
// "www.blackberry.com" is not white listed.
function doAJAX()
{
var req = new XMLHttpRequest();
req.open('GET', 'http://www.blackberry.com', true);
req.send(null);
}

 

How to fix this error:

 

If you are using the BlackBerry Web Plug-in for Eclipse or BlackBerry Web Plug-in for Microsoft Visual Studio, open your application's configuration document (config.xml) and click on the 'Add Domain' button in the Widget Permissions section.  Specify the domain of the external URI that should be white listed and and verify that you see the domain added as shown in the following screenshot:

 

domains_fix.png

 

If you are using the BlackBerry WebWorks Packager command utility, manually edit the configuration document (config.xml) of your BlackBerry WebWorks application and add an "access" element that specifies the domain that should be white listed:

 

 

<?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>commonPitfalls</name>
<access subdomains="false" uri="http://www.blackberry.com"/>
<content src="index.html"/>
</widget>

 

 

 

Unable to Access BlackBerry WebWorks API / JavaScript Extension Features

 

You must grant your BlackBerry WebWorks application permissions to access any features used from the BlackBerry WebWorks APIs and/or JavaScript Extensions.  If you do not, the feature is not registered with the JavaScript engine.  In this situation, the following runtime error may occur if the application attempts to access any property or method from the feature:

 

TypeError: Cannot convert 'undefined' to an object.

 

Example:

 

function showName() 
{
alert('App Name: ' + blackberry.app.name);

// The above example will produce a runtime error if the
// "blackberry.app" feature is not whitelisted because the
// JavaScript engine will evaluate "blackberry.app" to be
// 'undefined' which can then not be used as an object
// to evaluate the ".name" property
}

 

How to fix this error:

 

If you are using the BlackBerry WebWorks Plug-in for Eclipse or BlackBerry WebWorks Plug-in for Microsoft Visual Studio, open your application's configuration document (config.xml) and click on the 'Add Feature' button in the Widget Permissions section.  Find the feature name of the BlackBerry WebWorks API that should be white listed and verify that you see the feature added under the required domain as shown in the following screenshot:

 

feature_fix.png

 

If you are using the BlackBerry WebWorks Packager command utility, manually edit the configuration document (config.xml) of your BlackBerry WebWorks application and add a "feature" element that specifies the BlackBerry WebWorks API that should be white listed:

 

 

<?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>commonPitfalls</name>
<feature id="blackberry.app" required="true" version="1.0.0.0"/>
<content src="index.html"/>
</widget>

 

 

 

Dealing with Runtime Errors

 

The easiest way to find the source of runtime errors is to ensure you have well formed, procedural JavaScript code that makes use of Try / Catch statements.  Using this methedology, you can quickly narrow down which method or source contains the offending JavaScript.

 

 

function world()
{
try {
// Do some functionality - what happens if an exception occurs here?
 return 'World';
} catch {
alert("Exception in 'world': " + e);
}
}
function hello()
{
try {
// Do some functionality - what happens if an exception occurs here
 return 'Hello ' + world();
}
catch {
alert("Exception in 'hello': " + e);
}
}

//In the above example, if an exception occurs within the 'world' method
// method, it will not bubble up to the hello method and the developer will
// quickly be able to find the source of the problem.

alert(hello());

 

If you discover you are writing extremely large blocks of JavaScript code inside of a single method, it may be a sign that you should reformat the code into separate, smaller methods, each containing their own logical blocks of code.  This can also help developers troubleshoot runtime errors as they can focus their attention on and minimize risk when modifing specific functionality.

 

 

JavaScript Language Issues

 

Case sensitivity

 

An important reminder that JavaScript is a case sensitive language.  An object, method or property will not be recognized (and may generate 'undefined' runtime errors) if you use improper case within your application.  Reduce runtime errors by adopting the habit of following standard naming convention for defining your variable and method names.

 

Example:

 

 

function helloWorld()
{
alert('hello world');
}

//The following will generate an error since no method named "HelloWorld()"
//has been defined;

HelloWorld();

 

Malformed JavaScript

 

Nothing is more frustrating than spending hours tracking down a bug in your JavaScript code only to realize the problem was a missing braces.  If you discover that none of your JavaScript is responsive, it is likely that the syntax is incorrect and has not been parsed correctly by the JavaScript engine.

 

The easiest way to remedy these issues is to validate your JavaScript source using freely available code validation tools such as JSlint.

 

Example:

 

 

function doSomething()
{
alert(' ... something');

function doSomethingElse()
{
alert(' ... something else');
}

//The JavaScript engine will not recognize any of this script
// since the doSomething() method is missing a closing braces

doSomething();
doSomethingElse();

 

'undefined' is not an object

 

The telltale sign that the JavaScript engine is not able to recognize a call to an object's method or property is if you see runtime errors that state "'undefined' is not an object" or "cannot convert 'undefined' to an object".  This error can be caused by a variety of reasons, however a quick checklist of solutions to verify is :

 

  1. Is the object, method or property named correctly?
  2. For BlackBerry WebWorks APIs, has the feature been white listed correctly?
  3. Is the JavaScript object you are attempting to access even supported?

Example:

 

 

function notSupported()
{
alert(blackberry.doesNotExist.propertyABC);
}

//The code above will generate a runtime error when the JavaScript engine
// tries to evaluate ".propertyABC". The reason why is because the
// "blackberry" object does not have a child object named "doesNotExist".

notSupported();

 

 

Slow / Frozen BlackBerry WebWorks Applications on BlackBerry 6

 

If you ever notice your BlackBerry WebWorks applications are sluggish and/or frozen when running on a BlackBerry 6 device, it could be caused by one of the following deadlock conditions: 

 

  1. The main event thread within the BlackBerry WebWorks application makes a call into a BlackBerry WebWorks API or JavaScript extension, and waits for a response (blocks all other actions - such as updating the UI).
  2. The BlackBerry WebWorks API or JavaScript Extension tries to modify the UI by calling JavaScript methods, but ends up waiting forever because the UI is locked (waiting for the JavaScript extension to finish).

The result of this is the application freezes because it is stuck in a deadlock.  The solution is to make sure the JavaScript Extension is thread-safe.

 

This is the main reason why developers are encouraged to upgrade to the latest version of the BlackBerry Web development tools and re-build their BlackBerry WebWorks applications.  The BlackBerry WebWorks APIs have all been updated to be thread safe.

 

Accessing Embedded vs File System Resources

 

Applications created using the BlackBerry WebWorks platform can make HTTP requests to resources (such as HTML, Image, CSS or JavaScript files) embedded within the application using the local:/// protocol or to pages saved on the BlackBerry file system or SDCard using the "file:///" protocol.  Developers must recognize the difference and not mistakenly use one for the other.

 

Local Resource Example:

 

webworks_embedded_image.png

 

 

This image is an embedded Resource: 
<img src="local:///embedded_image.png" height="16" width="16" />

 

File System Example:

 

 

This image is saved on the file system:
<img src="file:///store/home/user/pictures/file_system.jpg" height="16" width="16" />

This image is saved on the removable SD card:
<img src="file:///SDCard/BlackBerry/pictures/removable.jpg" height="16" width="16" />

 

Resource Name Is Not Valid

 

Embedded resource files cannot contain hyphen characters.  If you attempt to build a BlackBerry WebWorks application that includes embedded resources having file names that include hyphens, you will receive an error message similar to the following:

 

BUILDING commonPitfalls
cmd.exe /c bbwp C:\sandbox\web apps\commonPitfalls\build\commonPitfalls.zip /o C:\sandbox\web apps\commonPitfalls\build
[INFO] Parsing command line options
[INFO] Parsing bbwp.properties
[INFO] Validating widget archive
[ERROR] Invalid widget archive - resource name is not valid(invalid-name.html)
BUILD EXITED WITH 1 ERROR

 

For more info on file naming conventions, see the Best Practices section of the BlackBerry WebWorks SDK Development Guide.

 

 

BlackBerry Smartphone Simulator Connection Problems

 

The Mobile Data Server Connection Service (MDS-CS) simulator is used by BlackBerry Smartphone Simulators to acquire a live internet connection at runtime.  It simulates the MDS component of the BlackBerry® Internet Service or BlackBerry® Enterprise Server that a BlackBerry smartphone may be connected to.

 

The BlackBerry WebWorks Plug-in for Eclipse and BlackBerry WebWorks Plug-in for Microsoft Visual Studio install their own copy of the MDS-CS simulator that is lauched automatically when you debug or launch your BlackBerry WebWorks project.

 

Developers may encounter connection issues when trying to access files from their local machine that are accessed over port 8080.  MDS-CS uses this port to provide network connectivity to the requesting BlackBerry Smartphone Simulator.  Changing the port used by the web server installed on your local machine to something other than 8080 will resolve this issue.

 

The following domains cannot be used by a BlackBerry WebWorks application to access content served by the web server running on the same machine as the BlackBerry Smartphone Simulator:

  • http://localhost
  • http://127.0.0.1

Instead developers are advised to use the network domain name or IP address of the target machine, if one is available.  Doing so will avoid network conflicts with MDS-CS accessing web content on the local computer.

 


 

More Links:

 

Users Online
Currently online: 29 members 2,151 guests
Please welcome our newest community members: