incubator-callback-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
Subject [2/2] docs commit: Blackberry echo plugin guide
Date Thu, 19 Jul 2012 19:39:30 GMT
Blackberry echo plugin guide


Branch: refs/heads/master
Commit: 755d1f9f2f514adc3a797af3ae796ad01abc0034
Parents: 085581a
Author: Tim Kim <>
Authored: Thu Jul 19 12:39:03 2012 -0700
Committer: Tim Kim <>
Committed: Thu Jul 19 12:39:03 2012 -0700

 .../guide/plugin-development/blackberry/   |  116 +++++++++++++++
 1 files changed, 116 insertions(+), 0 deletions(-)
diff --git a/docs/en/edge/guide/plugin-development/blackberry/ b/docs/en/edge/guide/plugin-development/blackberry/
index 76764c2..ab8f28c 100644
--- a/docs/en/edge/guide/plugin-development/blackberry/
+++ b/docs/en/edge/guide/plugin-development/blackberry/
@@ -19,3 +19,119 @@ license: Licensed to the Apache Software Foundation (ASF) under one
 Developing a Plugin on BlackBerry
+## How to make the Echo plugin on Blackberry
+In this article, we will explore how to develop the Echo plugin on BlackBerry. If you haven't
read the
+top level article about the JavaScript part of the plugin, it would be best if you read that
+and then this article. In addition, please download the Cordova Blackberry repo from here:
+To note, the Corodova-BlackBerry project allows you to deploy to BlackBerry devices like
+Torch, Bold, etc and as well as the Playbook. There exists a distinction between deploying
+normal BlackBerry hand held devices (ie, Torch and Bold) and the Playbook. The code base
+the two are separate so when you develop for one, you have to duplicate your efforts for
the other!
+Therefore in this article, the focus will be on the hand held devices and not the tablet.
In the future,
+this guide should cover both platforms.
+Continuing on from the previous article, the Echo plugin is essentially returning whatever
message a user 
+provides to the window.echo function. 
+The Echo function:
+    window.echo = function(str, callback) {
+            cordova.exec(callback, function(err) {
+                callback('Nothing to echo.');
+            }, "Echo", "echo", [str]);
+        };
+## Modifying plugins.xml
+This file resides in your project's www folder and contains all of the references to the
plugins that 
+your Cordova project uses. We are going to add an additional reference so that when cordova.exec
is called,
+Cordova will know how to map the "Echo" argument of cordova.exec to the Echo class that we
want to write natively.
+  ...
+  <plugin name="Echo" value="org.apache.cordova.echo.Echo"/>
+  ...
+## Adding
+If you notice the structure of the value attribute, you'll see a defined path that leads
to the Echo
+plugin. In the root folder of the Cordova BlackBerry Webworks repo, look for a folder called
+This folder contains all of the source code that runs natively on the BlackBerry. cd into
the folder 
+structure until you reach the path: framework/ext/src/org/apache/cordova. At this point,
you'll see
+all of the plugin folders and inside each folder is the plugins' source code. So, we will
+the folder echo to framework/ext/src/org/apache/cordova/echo and create a file called
+at framework/ext/src/org/apache/cordova/echo/
+## Writing
+The basic idea of writing a plugin is to create a class that extends the Plugin class and
+a method called execute to return a PluginResult class. Any call to cordova.exec will pass
+the action that we want to execute within the class as well as the arguments. In this case,
+"echo" is the action we want to execute within the class "Echo" and [str] are the arguments
we are passing in.
+package org.apache.cordova.echo;
+import org.apache.cordova.api.Plugin;
+import org.apache.cordova.api.PluginResult;
+import org.apache.cordova.json4j.JSONArray;
+import org.apache.cordova.json4j.JSONException;
+import org.apache.cordova.json4j.JSONObject;
+import org.apache.cordova.util.Logger;
+ * A simple plugin to demonstrate how to build a plugin for Blackberry
+ * Basically echos back the msg that a user calls to this plugin 
+ */
+public final class Echo extends Plugin {
+	public static final String echo = "echo";
+	public PluginResult execute(String action, JSONArray args, String callbackId) {
+		PluginResult result = new PluginResult(PluginResult.Status.INVALID_ACTION, "Echo: Invalid
action:" + action);
+		if(action.equals(echo)){
+			try {
+				JSONObject echoObj = new JSONObject();
+				String theMsg = args.getString(0);
+				if(theMsg.length()>0){   
+				    result = new PluginResult(PluginResult.Status.OK, theMsg);
+				}else{
+				    result = new PluginResult(PluginResult.Status.ERROR, theMsg);
+				}
+			} catch (JSONException e) {
+				result = new PluginResult(PluginResult.Status.JSON_EXCEPTION, e.getMessage());
+			}
+		}
+		return result;
+	}
+So if we look at the code above, we can see that within the execute method, we are first
looking for
+what actions are coming in. The Echo plugin has only one action, "echo" so we will be only
checking for 
+that. If our plugin had more actions, it's simply a matter of adding more if-conditionals
to check
+for those actions.
+We are then going to grab the message coming in from the arguments which is supplied by the
args parameter.
+We can grab the first argument by simply doing String theMsg = args.getString(0);
+We will do some error checking and if the message looks okay, we will instantiate a new PluginResult
+an ok status: PluginResult.Status.OK and return the message: theMsg. After this, we will
then return the 
+result which will then pass back to JavaScript to be fired in the success callback. If something
should fail, 
+we can return various status exceptions like PluginResult.Status.ERROR, PluginResult.Status.JSON_EXCEPTION,
+or PluginResult.Status.INVALID_ACTION. When these types of results are passed back, they
will fire the fail 
+callback in JavaScript. 
+## Updating the .jar in your project's www folder
+The addition of the needs to be updated in your project so to build the .jar file,
+to the root directory of the BlackBerry Webworks repo. Use the ant command: ant update -Dproject.path="~/path_to_my_project"
+This will build a new .jar file in the build/ext folder. Copy the build/ext/cordova___.jar
file into your
+project/www/ext folder. 
+If all goes well, that should allow you to use the Echo plugin in BlackBerry.
+## Common Pitfalls
+## Debugging

View raw message