Merge pull request blackberry#70 from sterlingwes/sendmenu

"Send ..." Menu Extension for BlackBerry 7
starpax · Jul 16, 2012 · de629bb · de629bb
2 parents 47be17c + c8d3207
commit de629bb
Show file tree

Hide file tree

Showing 4 changed files with 400 additions and 0 deletions.
diff --git a/Smartphone/SendMenu/README.md b/Smartphone/SendMenu/README.md
@@ -0,0 +1,74 @@
+# SendMenu Extension
+
+This extension exposes the Blackberry Java Send/"Share" Menu API for use within WebWorks applications (Twitter, Facebook, SocialFeed, SMS, E-mail, PIN, etc).
+
+**Authors:** [Wes Johnson](https://twitter.com/SterlingWes)
+
+## Tested On
+
+* BlackBerry Bold 9900 (OS 7.1.0.267)
+
+**OS Requirement:** This API requires > OS 7.0
+
+Have a problem with this extension?  [Log an Issue](https://github.com/blackberry/WebWorks-Community-APIs/issues) or contact the [Author](https://github.com/sterlingwes)
+
+## How to install this extension
+
+1. Download the source from this repository and extract it to a location on your computer.
+
+2. Using File Explorer browse to the downloaded source code for this extension: _**Smartphone\SendMenu**_.
+
+3. Copy the downloaded _**Smartphone\SendMenu\blackberry.sendmenu**_ directory to the extensions directory for the BlackBerry WebWorks SDK for Smartphone. The default path for this location is _**C:\Program Files\Research In Motion\BlackBerry WebWorks Packager\ext**_.
+
+**NOTE:** Be sure to back-up this _**ext\blackberry.sendmenu**_ directory in your WebWorks SDK extensions directory before performing a WebWorks SDK upgrade. Simply copy it back into the _**ext**_ directory after you have completed your SDK upgrade.
+
+## Required Feature ID
+Whenever you use the below feature id in any of your WebWorks applications this extension will be loaded for use.
+
+    <feature id="blackberry.ui.sendmenu" />
+
+## Usage
+
+### Constants
+
+SendCommand Types (the primary data type you're looking to send):
+
+* blackberry.ui.sendmenu.TYPE_PATH
+* blackberry.ui.sendmenu.TYPE_TEXT
+
+Context JSON Keys:
+
+* blackberry.ui.sendmenu.PATH
+* blackberry.ui.sendmenu.SUBJECT
+* blackberry.ui.sendmenu.TEXT
+
+###  Methods
+
+#### blackberry.ui.sendmenu.add( TYPE, CONTEXT [, GET_ALL, ORDERING, PRIORITY, FILTER ] )
+
+Adds the Send Menu to the app's menu.
+
+Arguments:
+
+* `TYPE` is one of the above `TYPE_PATH` or `TYPE_TEXT` constants
+* `CONTEXT` is a JSON string with valid keys `PATH`, `SUBJECT` and/or `TEXT`
+* `GET_ALL` (optional) is a boolean indicating whether to get all commands, regardless of availability (defaults to `FALSE`)
+* `ORDERING` (optional) is an integer indicating menu ordering (defaults to 0)
+* `PRIORITY` (optional) is an integer indicating menu priority (defaults to 0)
+* `FILTER` (optional) is a JSON string similar to `CONTEXT` which replaces values in `CONTEXT` based on command filters (in testing this had no affect on commands I thought it would, ie: Twitter or SMS limits), leave null for none
+
+#### blackberry.ui.sendmenu.remove()
+
+Removes the Send Menu previously added in the current application session (the menu will not persist between sessions).
+
+#### blackberry.ui.sendmenu.setLabel( STRING_LABEL )
+
+Sets the parent menu label for the sub menu containing all send commands. Defaults to `Share`.
+
+## Example
+
+	var context = {};
+	blackberry.ui.sendmenu.setLabel('Send...');
+	context[blackberry.ui.sendmenu.SUBJECT] = 'This is an e-mail subject';
+	context[blackberry.ui.sendmenu.TEXT] = 'This message was sent from my WebWorks app!';
+	blackberry.ui.sendmenu.add(blackberry.ui.sendmenu.TYPE_TEXT,JSON.stringify(context));
diff --git a/Smartphone/SendMenu/blackberry.sendmenu/blackberry/ui/sendmenu/SendMenuExtension.java b/Smartphone/SendMenu/blackberry.sendmenu/blackberry/ui/sendmenu/SendMenuExtension.java
@@ -0,0 +1,82 @@
+/*
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package blackberry.ui.sendmenu;
+
+import org.w3c.dom.Document;
+
+import net.rim.device.api.browser.field2.BrowserField;
+import net.rim.device.api.script.ScriptEngine;
+import net.rim.device.api.web.WidgetConfig;
+import net.rim.device.api.web.WidgetExtension;
+
+import java.lang.ref.WeakReference;
+
+public class SendMenuExtension implements WidgetExtension 
+{
+	private static WeakReference _browserField = null;
+    private String NAME = "blackberry.ui.sendmenu";
+
+    /**
+     * @see net.rim.device.api.web.WidgetExtension#getFeatureList()
+     */
+	public String[] getFeatureList()
+	{
+		return new String[] { NAME };
+	}
+
+	/**
+     * @see   net.rim.device.api.web.WidgetExtension#loadFeature(String, String, Document, ScriptEngine)
+	 */
+	public void loadFeature(String feature, String version, Document doc, ScriptEngine scriptEngine) throws Exception
+	{
+		Object obj = null;
+		if (feature.equals(NAME))
+		{
+			obj = new SendMenuNamespace();
+		}
+
+		if( obj != null ) {
+			scriptEngine.addExtension( feature, obj );
+		}
+	}
+
+    /**
+     * Get the current BrowserFiled. 
+     * 
+     * @return the current BrowserFiled
+     */
+    public static BrowserField getBrowserField() {
+        return ( BrowserField ) _browserField.get();
+    }
+
+	/**
+     * @see   net.rim.device.api.web.WidgetExtension#register(WidgetConfig, BrowserField)
+	 */
+	public void register(WidgetConfig config, BrowserField bf)
+	{
+		_browserField = new WeakReference(bf);
+	}
+
+
+	/**
+     * @see   net.rim.device.api.web.WidgetExtension#unloadFeatures(Document)
+	 */
+	public void unloadFeatures(Document doc)
+	{
+		// no cleanup required
+	}
+
+
+}
diff --git a/Smartphone/SendMenu/blackberry.sendmenu/blackberry/ui/sendmenu/SendMenuNamespace.java b/Smartphone/SendMenu/blackberry.sendmenu/blackberry/ui/sendmenu/SendMenuNamespace.java
@@ -0,0 +1,218 @@
+/*
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package blackberry.ui.sendmenu;
+
+import net.rim.device.api.script.Scriptable;
+import net.rim.device.api.script.ScriptableFunction;
+
+import net.rim.blackberry.api.sendmenu.*;
+import net.rim.device.api.ui.menu.SubMenu;
+
+import org.json.me.JSONException;
+import org.json.me.JSONObject;
+import java.util.Hashtable;
+import java.util.Enumeration;
+import net.rim.device.api.ui.container.MainScreen;
+
+public class SendMenuNamespace extends Scriptable 
+{
+
+	// SendCommand Types
+	public static final String PROPERTY_TYPE_PATH  	= "TYPE_PATH";
+	public static final String PROPERTY_TYPE_TEXT 	= "TYPE_TEXT";
+
+	// SendCommand JSON Keys
+	public static final String PROPERTY_PATH 		= "PATH";
+	public static final String PROPERTY_SUBJECT		= "SUBJECT";
+	public static final String PROPERTY_TEXT 		= "TEXT";
+
+	// JS API Methods
+	public static final String FUNCTION_ADD     	= "add";
+	public static final String FUNCTION_REMOVE     	= "remove";
+	public static final String FUNCTION_LABEL		= "setLabel";
+
+    private Hashtable _fields;
+
+	private SubMenu menu = null;
+	private String menuLabel = "Share";
+
+	public SendMenuNamespace()
+	{
+        _fields = new Hashtable();
+        _fields.put( PROPERTY_TYPE_PATH, new Integer(SendCommand.TYPE_PATH) );
+        _fields.put( PROPERTY_TYPE_TEXT, new Integer(SendCommand.TYPE_TEXT) );
+		_fields.put( PROPERTY_PATH, SendCommandContextKeys.PATH );
+		_fields.put( PROPERTY_SUBJECT, SendCommandContextKeys.SUBJECT );
+		_fields.put( PROPERTY_TEXT, SendCommandContextKeys.TEXT );
+
+        _fields.put( FUNCTION_ADD, new SendMenuAddFunction() );
+		_fields.put( FUNCTION_REMOVE, new SendMenuRemoveFunction() );
+		_fields.put( FUNCTION_LABEL, new SetLabelFunction() );
+	}
+
+	/**
+	 * Adds the SendMenu
+	 *
+	 * Arguments Expected (by array index):
+	 *
+	 * 0: SendCommand Type (from exposed constant: TYPE_PATH or TYPE_TEXT) [REQUIRED]
+	 * 1: JSON Context Object with valid keys (from exposed constants: PATH, SUBJECT, and/or TEXT) [REQUIRED]
+	 * 2: Boolean for whether to get all send commands, regardless of availability (Default FALSE)
+	 * 3: Integer for Send Menu ordering (Default 0)
+	 * 4: Integer for Send Menu priority (Default 0)
+	 * 5: JSON Filter Object for context filter, or null for none
+	 */
+	public class SendMenuAddFunction extends ScriptableFunction {
+
+		public Object invoke(Object obj, Object[] args) throws Exception 
+		{
+			Object result = Boolean.FALSE;
+
+			if (args.length >= 2 && menu == null)
+			{
+				MainScreen screen = (MainScreen) SendMenuExtension.getBrowserField().getScreen();
+
+				int sendType = Integer.parseInt(args[0].toString());
+				boolean getAll = (args.length>=3) ? ((Boolean) args[2]).booleanValue() : false;
+				int ordering = (args.length>=4) ? Integer.parseInt(args[3].toString()) : 0;
+				int priority = (args.length>=5) ? Integer.parseInt(args[4].toString()) : 0;
+
+				try
+				{
+					JSONObject context = new JSONObject(args[1].toString());
+
+					SendCommand[] sendCommands = SendCommandRepository.getInstance().get(sendType,context,getAll);
+
+					if(sendCommands != null && sendCommands.length > 0)
+					{
+						if(args.length >= 6 && args[5] != null)
+						{
+							try
+							{
+								JSONObject filterArgs = new JSONObject(args[5].toString());
+								SendContextFilter filter = new SendContextFilter(filterArgs);
+								for (int i = 0; i < sendCommands.length; i++)
+								{
+									sendCommands[i].setSendCommandContextFilter(filter);
+								}
+							} catch (JSONException e) {
+								System.out.println(e.toString());
+							}
+						}
+						SendCommandMenu sendCommandmenu = new SendCommandMenu(sendCommands, 0, 0);
+						SendCommandMenuItem[] menuItems = sendCommandmenu.getSendCommandMenuItems();
+						menu = new SubMenu(menuItems,menuLabel,ordering,priority);
+						screen.addMenuItem(menu.getMenuItem());
+						result = Boolean.TRUE;
+					}
+				}
+				catch (JSONException e)
+				{
+					System.out.println(e.toString());
+				}
+			} 
+
+			return result;
+		}
+
+	}
+
+	/*
+	 * Used in SendMenuAdd if a context filter is defined
+	 */
+	public class SendContextFilter implements SendCommandContextFilter
+	{
+		private JSONObject filter = null;
+
+		public SendContextFilter(JSONObject filterArgs)
+		{
+			filter = filterArgs;
+		}
+
+		public JSONObject filterContext(SendCommand sendCommand)
+		{
+			JSONObject newContext = sendCommand.getContext();
+			try
+			{
+				Enumeration keys = filter.keys();
+				while( keys.hasMoreElements() ){
+					String key = (String)keys.nextElement();
+					if( filter.get(key) instanceof String ){
+						newContext.put(key, filter.get(key));
+					}
+				}
+			}
+			catch (JSONException e)
+			{
+				System.out.println(e.toString());
+			}
+
+			return newContext;
+		}
+	}
+
+	/**
+	 * Removes the SendMenu, if it exists
+	 *
+	 * No arguments required
+	 */
+	public class SendMenuRemoveFunction extends ScriptableFunction {
+
+		public Object invoke(Object obj, Object[] args) throws Exception 
+		{
+			if (menu != null)
+			{
+				MainScreen screen = (MainScreen) SendMenuExtension.getBrowserField().getScreen();
+				screen.removeMenuItem(menu.getMenuItem());
+				menu = null;
+				return Boolean.TRUE;
+			}
+
+			return Boolean.FALSE;
+		}
+	}
+
+	/**
+	 * Sets the label for the Send Menu in the parent menu
+	 * (opens to sub menu with send commands)
+	 *
+	 * Arguments:
+	 * 0: String for label
+	 */
+	public class SetLabelFunction extends ScriptableFunction {
+
+		public Object invoke(Object obj, Object[] args) throws Exception
+		{
+			if (args.length == 1)
+			{
+				menuLabel = args[0].toString();
+			}				
+			return UNDEFINED;
+		}
+
+	}
+
+    /**
+     * @see net.rim.device.api.script.Scriptable#getField(String)
+     */
+	public Object getField(String name) throws Exception 
+	{
+		if(_fields.containsKey( name ))
+			return _fields.get( name );
+
+		return UNDEFINED;
+	}
+
+}