phonegap: How To:How to Debug a PhoneGap Plugin for BlackBerry WebWorks

There are two way to debug a PhoneGap Plugin for BlackBerry WebWorks : the eas y way and the hard way. The eas y way to is to debug with log mes s ages , which is a quick way to dis cover the problem, fix it, and move on. The hard way is to us e Eclips e and s tep-debug your s ource code, which will give you a detailed unders tanding of the problem but cons ume a lot of time.

Debugging with Log Messages

The eas ies t way to debug your PhoneGap application and WebWorks plugin is with s tandard log mes s ages . On WebWorks , all log mes s ages are written to the BlackBerry s ys tem log. From Java, you can log mes s ages with: import com.phonegap.util.Logger; Logger.log("Hello world"); From JavaScript, you can log mes s ages with: console.log(Hello world); You can view the BlackBerry event logs with a free BlackBerry application called ShowEventLog. To download it, jus t point your BlackBerry brows er to: http://www.s 4bb.net/ota100920/free/s howeventlog.jad

Debugging with Eclipse

There are s ituations where log mes s ages do not offer enough information or control, s uch as working with threading. In thes e s ituations , you can configure Eclips e to s tep-debug your Java s ource code. Warning: BlackBerry WebWorks does not s upport s tep-debugging of a WebWorks extens ion. The following approach is a workaround that was dis covered by the PhoneGap maintainers . In the following approach, you will create a new Eclips e BlackBerry project bas ed on the the generate the s ource code of your WebWorks project. After debugging the s ource code, you will need to copy your plugins s ource code back into your WebWorks project.

1. Download BlackBerry Eclipse Plugin

Download and ins tall the BlackBerry Java Plugin for Eclips e (full ins taller). Debugging with Eclips e will only work us ing BlackBerry JRE 6.0. Unfortunately, the BlackBerry JRE 6.0 cannot be ins talled as a plugin us ing the Eclips e web ins taller. Ins tead, you mus t download and ins tall the BlackBerry Java Plugin for Eclips e (full ins taller).

2. Generate Source Code of your WebWorks Project

Unfortunately, we cannot s imply open a WebWorks application in Eclips e and debug Java extens ions . Ins tead, we mus t generate the s ource code of our WebWorks project and import it into a new Eclips e project. 1. Open C:\path\to\myapp\build.xml 2. Add <arg value="/s" /> to the end of each argument lis t Lines 150 and 158 of the following image:

3. Generate the s ource code by building the project Run ant build or ant load-simulator or ant load-device This will generate the s ource code to C:\path\to\myapp\build\src

3. Create an Eclipse BlackBerry Java Project

1. Open the Eclips e ins tallation that includes the BlackBerry JRE 6.0 plugin 2. Select File -> New -> BlackBerry Project

3. Enter project name 4. Select BlackBerry JRE 6.0.0 5. Select Finish

4. Delete Project's Source and Resources

Delete src/mypackage Delete res/img

5. Import the Generated WebWorks Source Code

1. Right-click on src/ 2. Select Import -> File System -> Browse...

3. Select C:\path\to\myapp\build\src\blackberry

4. After importing, you s hould s ee errors on the blackberry packages :

6. Fix Generated Package Names

1. Highlight the project name in the project tree 2. Select Search -> File... 3. Set Containing Text to blackberry.web.widget[^;.]*

4. Set Scope to Enclosing Projects 5. Select Replace... 6. Set Replace with to blackberry.web.widget 7. Select OK

8. There s hould now be only one error.

7. Import PhoneGap Source Files

1. Right-click on src/ 2. Select Import -> File System -> Browse... 3. Select C:\path\to\myapp\build\src\extension 4. Uncheck library.xml 5. Select Finish

6. There s hould now be a number of phonegap packages .

8. Import Resource Files

1. Right-click on res/ 2. Select Import -> File System -> Browse... 3. Select C:\path\to\myap\www 4. Uncheck ext/ 5. Select Finish

6. Your web as s ets s hould now be under the res/ directory.

9. Delete org.json.me
1. Right-click on src/org.json.me 2. Select Delete

10. Update Icon

1. Open BlackBerry_App_Descriptor.xml 2. Remove the application icon 3. Select Add... -> res/resources/icon.png 4. Select Save

11. Begin Debugging

1. Add breakpoints 2. Run in debug mode 3. Make s ure that you are us ing the debug pers pective

12. After Debugging

After debugging your PhoneGap WebWorks plugin, you will need to: 1. Copy the plugin s ource code files back to your plugin's project 2. Generate the JAR 3. Copy the JAR to your application project (C:\path\to\myapp\www\ext)