BlackBerry 10 WebWorks development tips

This page describes tips for WebWorks development for BB10.

I never had BlackBerry experience before January 2012. At that moment the prices dropped for the PlayBook and I bought my first BlackBerry device. Soon after that I could participate in a contest to start developing PlayBook applications. I created a developer account and was introduced to the WebWorks approach. I created my first WebWorks application in two weeks. Development was a joy!

When BlackBerry announced the new phones early 2012 I was interested, but since it would take about a year before the devices would be available I did not pay attention to it. This caused me to miss out on the Dev Alpha A devices. Which was not wise when you read some my troubles below.

My main troubles are in these areas:

  • Examples are not working on latest WebWorks version.
  • Ripple simulator limitations.
  • Windows 8 and Ripple installation troubles.
  • VMWare simulator not working, not knowing how to debug, redeployment slow.


  • My main conclusion: You need test hardware.
  • My second conclusion: If you do not have hardware you should skip Ripple and focus on the VMWare simulator.

The good part is Ken Wallis from BlackBerry. I attended one of his presentations at BlackBerry Jam Europe 2013 in Amsterdam. The demo was about pim.contacts and 'cards', exactly what I wanted to use but could not use due to bugs and limitations in Ripple and the VMWare simulator. After the presentation I told him about my concerns for developers who don't have test hardware. In the mean time I lost trust in Ripple. Was still excited about the possibilities. Somehow I still tried on and on. Last resort when you do not have hardware: I needed to get the VMWare simulator working.

My requirements:

  • Debugging must work
  • Redeployment must work without Packaging and Launching (Ripple terms). I cannot wait 30 seconds or more for a redeployment. I need direct editing capabilities.

I searched around but missed web inspector debugging documentation first (was it there half February 2013?). The support forums helped me a bit: but after the first answer I requested more detail, but I got no reply. So I contacted Ken Wallis again and I got a useful response. See the support forum message.


  • Debugging WebWorks application that is deployed on VMWare simulator works using the Chrome browser
    • Next requirement: get debugging work in my IDE (Netbeans 7.3 for example)
  • Redeployment works without Packaging and Launch.

Now I can finally start enjoying development a WebWorks application. Read my steps below.

Examples not working on latest WebWorks version

When you want to start your first Hello World and you read the documentation you will be directed to GitHub. You will download the examples and will try to use them. However you must keep in mind that the examples not always work out of the box. This can cost you quite some time.

  • Positive: Lots of examples are on GitHub.
  • Negative: You loose faith if the examples do not work out of the box.
  • Negative: MOST examples do NOT work in Ripple! TIP: try them with the VMWare simulator!
  • Negative: When using the VMWare simulator you MUST understand how to package your application.
  • Time wasted: 1 hour to fix it locally and create GitHub issue. Luckily I had a suspicion where to look. New developers would not have found it.

Example issue I created:

Ripple simulator

Once installed it is easy to get Hello World working. But when trying to use blackberry APIs like 'pim.contacts' you run into problems. Not all APIs are simulated in Ripple. This is a big issue.

  • Positive: not much needed to write your first WebWorks application and see it in your browser
  • Positive: No hardware needed to develop your application
  • Negative: Only very basic HTML application can be developed this way.
  • Time wasted: 3 hours.
    • I planned a nice tool. Required pim.contacts.
    • Wrote the first version of the app, found out it was not supported in Ripple.
    • Tested on VMWare simulator, ran into a bug in simulator. See tweet below.

Example bug:

Bug in old VMWare simulator which luckily has been fixed in the meantime:

Windows 8 and Ripple

Installing Ripple is not easy. Read this bug where I describe all steps needed to get Ripple working on Windows 8:

  • Positive: In the end you can get it working.
  • Negative: Way too difficult to start using Ripple. Java required while no warnings are given. License prevents first use.
  • Negative: Settings screen is way too difficult and values have to be entered again and again, for each example you want to try. See bug:
  • Time wasted: 4 to 6 hours
    • Trial and error and writing manual on GitHub.
    • Luckily I had Ripple experience (on older version without the license stuff) and Java experience.
    • Luckily I attended BlackBerry Jam Europe WebWorks workshop session to retest what I had done in Windows 7 earlier that day.

Getting debugging and redeployment without repackaging to work

  1. Install latest Q10 image (BlackBerry10Simulator-Installer-BB10_1_X-807-Win-201303050726.exe)
  2. Start Q10
  3. Check if development mode is enabled (settings → security)
  4. Write down ip address of VMWare (lower left corner)
  5. Package your app and upload to the image, ensuser -d option is used to enable debugging (I use Ripple Build & Launch and enable web inspector flag)
  6. Check your application is being installed in the VMWare.
  7. Check when your application opens that a pop up (like javascript alert message) is shown: Web inspector enabled.
  8. Try to connect web inspector by opening the url in the Chrome browser, example:
  9. Easiest check: check if some of your console.log lines are showing output in the Web inspector console screen.

Ok web inspector is working. Now redeployment.

  1. Install a webserver locally.
  2. Deploy your webworks application on your local webserver.
    • Copy Webworks app into new folder in C:\apache-tomcat-7.0.37\webapps
    • Example: copy index.html and the other webworks files into C:\apache-tomcat-7.0.37\webapps\testapp\
    • Open your browser to http://localhost:8080/testapp/ and your Webworks app should be shown
  3. Find your ip address and replace localhost with it.
  4. Change config.xml:
    • Replace <content src="index.html" /> with <content src="" />
    • Replace <access uri="*" subdomains="true" /> with (or add above author node) <access uri="" subdomains="true" />
  5. Package your app and upload to the image, ensuser -d option is used to enable debugging (I use Ripple Build & Launch and enable web inspector flag)
    • If you made a mistake in the config.xml I experienced that changes were not picked up by Ripple Package and launch.
    • What helped for me:
      • close your application in VMWare
      • delete your application (long press icon)
      • clean package output directory so no old bar file can be reused
      • Package and launch again.
    • Kept failing for me, luckily web inspector could still connect. Output log showed:
  6. You should now be ready! You can test as follows:
    • Package and deploy your application to the Q10 VMWare simulator.
    • Check if your application starts (and shows the Web inspector enabled popup if you enabled debugging)
    • Change the source code in C:\apache-tomcat-7.0.37\webapps\testapp\ and save the changes.
    • Close your application in the Q10 VMWare simulator.
    • Start your application in the Q10 VMWare simulator. The web page is now reloaded, your change should be visible.

Not tested but might work:

  • Create a reload method in your application (e.g. when using a specific button for development purposes).
blackberry10webworks.txt · Last modified: 2013/03/15 00:49 by rmorrien
Recent changes RSS feed Donate Powered by PHP Valid XHTML 1.0 Valid CSS Driven by DokuWiki