Context Menu

The contextmenu namespace provides the facility to interact with the context menu api to control whether context menus are enabled, listen to events, add items to appear based on the context, and set the theme of the context menu.

Device showing a context menu.

Context Menu

Webworks applications can choose to use an in app contextmenu as opposed to the default operating system menu. The contextmenu provides several facilities to developers to allow them to control the elements that appear in the menu, as well as listen to specific events related to the context menu being triggered and displayed.

Enabling

The contextmenu can be enabled by calling the blackberry.ui.contextmenu.enabled property. When set to true, the contextmenu will capture the context menu events, and pass any events that the user has registered for. When set to false the contextmenu will default to the system, and the developer will have no access to the events described below.

Context Information

Context information is available from the window object through a contextmenu event "window.oncontextmenu". This event is triggered whenever there is a context menu request from the client. This event provides all the contextual information needed to store the context yourself and save what element the context menu was triggered on. This allows you to perform a multitude of different actions once a context menu has been requested.


Code Example:
<script type="text/javascript">
function addMenuItemToCustomContext() {
    var myItem = {actionId: '7', label: 'itemForCustom', icon:'local:///img/myIcon.png'},
        contexts = ["myContext"];
    blackberry.ui.contextmenu.addItem(contexts, myItem);
}

function addAdditionalItemsFromCustomContext) {
    var options = {
        includeContextItems: [blackberry.ui.contextmenu.CONTEXT_IMAGE, blackberry.ui.contextmenu.CONTEXT_IMAGE_LINK],
        includePlatformItems: true,
        includeMenuService: true
    };
    blackberry.ui.contextmenu.defineCustomContext("myContext", options);
}

function removeAdditionalItemsFromCustomContext) {
    var options = {
        includeContextItems: [],
        includePlatformItems: false,
        includeMenuService: false
    };
    blackberry.ui.contextmenu.defineCustomContext("myContext", options);
}
</script>
<div data-webworks-context="myContext">I am a custom context!</div>


Learning Resources:

Sample - Using Custom Context Sample that demonstrates how to use the BlackBerry Custom Context API [BlackBerry on GitHub].
<script type="text/javascript">

// Update the path from a small icon to a full image
function translateIcontoFullImage (path) {
    if (path && path.indexOf('.ico') !== -1) {
        return path.replace('.ico', '.jpeg');
    }
}

function onContextMenu (contextEvent) {
    var srcElement = contextEvent.srcElement;
    blackberry.invoke.interrupter = function (request) {
        // Check if this is an image we wish to translate
        if (srcElement && srcElement.src {
            request.uri = translateIcontoFullImage(srcElement.src);
        }

        // Return the updated request object
        return request;
    };

}

window.addEventListener('oncontextmenu', onContextMenu);

</script>

Custom Context Menu

Webworks applications can give Dom elements custom context by using the data-webworks-context xml attribute. When a Dom element contains this attribute, custom context menus will be activated when the element is long pressed. Once you have created a custom context using the data-webworks-context attribute, you can then use addItem to add items to the custom context. You can also optionally use defineCustomContext to further define the items shown.

Supported Platform(s)

- BlackBerry 10
- Ripple Emulator
View Supported Platform Table
APIBB5.0BB6.0BB7.0PB1.0PB2.0BB10Ripple
blackberry.ui.contextmenu.addItem           YY
blackberry.ui.contextmenu.defineCustomContext           YY
blackberry.ui.contextmenu.removeItem           YY
enabled             
CONTEXT_ALL           YY
CONTEXT_LINK           YY
CONTEXT_IMAGE           YY
CONTEXT_IMAGE_LINK           YY
CONTEXT_INPUT           YY
CONTEXT_TEXT           YY
ACTION_CANCEL           YY
ACTION_CLEAR_FIELD           YY
ACTION_COPY           YY
ACTION_COPY_IMAGE_LINK           YY
ACTION_COPY_LINK           YY
ACTION_CUT           YY
INSPECT_ELEMENT           YY
ACTION_PASTE           YY
ACTIONE_SAVE_IMAGE           YY
ACTION_SAVE_LINK_AS           YY
ACTION_SELECT           YY
ACTION_VIEW_IMAGE           YY

Configuration Document Settings

To use all of the API described for this object, you must ensure the following settings are in your configuration document:

You must declare the feature element(s) below in your configuration document:

Feature IDBB5.0BB6.0BB7.0PB1.0PB2.0BB10Ripple
<feature id="blackberry.ui.contextmenu" />           YY

Permission Elements (PlayBook and BlackBerry 10+)
This API does not require a <permission> element to be declared in the configuration document of your BlackBerry WebWorks Application.


Properties

boolean enabled

Functions

static void blackberry.ui.contextmenu.addItem (contexts : String[], action : Object, callback: function(sourceId : String))


Allows the developer to add custom items to the context menu. The items will be appended to the end of the list of operating system defined functions. Developers must provide the following parameters to successfully add items to the context menu.


Supported Platforms
 - BlackBerry 10
 - Ripple Emulator


Parameters
contexts An array of constants defining which contexts this new item should appear.
action An object which defines the menu item to be added.

actionId: A property that uniquely defines the action to be added to the context menu.
label: A string that will be displayed to the user describing the custom context to be performed. ie: Edit
icon: A path to the an image to display in the context menu
callback A function which runs when the menu item action is executed

sourceId: The returned sourceId from the element which defined the custom context and the context was invoked on.

Code Example:
<script type="text/javascript">

function addMyItem() {
    var myItem = {actionId: 'MyItem', label: 'My Item', icon:'http://mysite.com/icon.png'},
        contexts = [blackberry.ui.contextmenu.CONTEXT_IMAGE, blackberry.ui.contextmenu.CONTEXT_INPUT];
    blackberry.ui.contextmenu.addItem(contexts, myItem, function() { console.log('hi') });
}

//Perform an action on custom context, with a custom item
function deleteItem(sourceId) {
    var element = document.getElementById(sourceId);
        element.parentNode.removeChild(element);
}

function greyOutItem(sourceId) {
    var element = document.getElementById(sourceId);
        element.className = "greyed-out";
}

var options = {
        includeContextItems: [blackberry.ui.contextmenu.CONTEXT_ALL],
        includePlatformItems: true,
        includeMenuServiceItems: true
     },
     item,
     contexts = [blackberry.ui.contextmenu.CONTEXT_ALL];

// Define the custom context with the options that we want used
blackberry.ui.contextmenu.defineCustomContext("PrincessContext", options);

// Create a menu item and add it to the context
item = {actionId: '1', label: 'Delete Item', icon:'local:///images/icon.png'};
blackberry.ui.contextmenu.addItem(contexts, item, deleteItem);

// And another
item = {actionId: '2', label: 'Grey Out', icon:'local:///images/icon.png'};
blackberry.ui.contextmenu.addItem(contexts, item, greyOutItem);

 //Override the system Copy action by actionId using the ACTION_COPY constant
 function overridePlatformWithIcon() {
  var myItem = {actionId: blackberry.ui.contextmenu.ACTION_COPY, label: 'Custom Copy!',
      icon:'local:///icon.png'},
      contexts = [blackberry.ui.contextmenu.CONTEXT_ALL];

  blackberry.ui.contextmenu.addItem(contexts, myItem, function() {
      alert("Wow you succesfully overrode the platform menu item Copy");
  });
}
 //Override the system Copy action by actionId using the ACTION_SAVE_IMAGE constant
 // this example does not provide a icon, and uses the system default
 function overridePlatformNoIcon() {
  var myItem = {actionId: blackberry.ui.contextmenu.ACTION_SAVE_IMAGE, label: 'Save Image'},
      contexts = [blackberry.ui.contextmenu.CONTEXT_ALL];

  blackberry.ui.contextmenu.addItem(contexts, myItem, function() {
      alert("Custom Save using system icon");
  });
}

</script>

static void blackberry.ui.contextmenu.defineCustomContext (context : String, options : Object)


Allows the developer to define a custom context.


Supported Platforms
 - BlackBerry 10
 - Ripple Emulator


Parameters
context A String representing the custom context.
options An Object that contains the various options to set for the custom context.

includeContextItems: An Array that defines a list of contexts to which custom items will be used from when applicable.
includePlatformItems: An boolean indicating whether to include the default platform items.
includeMenuServiceItems: An boolean indicating whether to add menu items provided by the menu service.

Code Example:
<script type="text/javascript">

function defineCustomContext() {
    var options = {
        includeContextItems: [blackberry.ui.contextmenu.CONTEXT_IMAGE],//Includes custom items added for CONTEXT_IMAGE
        includePlatformItems: true,
        includeMenuServiceItems: true
    };

    blackberry.ui.contextmenu.defineCustomContext("myContext", options)
}
</script>

static void blackberry.ui.contextmenu.removeItem (contexts : String[], actionId : String)


Allows the developer to remove previously added custom items from the context menu.


Supported Platforms
 - BlackBerry 10
 - Ripple Emulator


Parameters
contexts An array of constants defining which contexts this new item should appear.
actionId An id that uniquely defines the action to be removed from the context menu.

Code Example:
<script type="text/javascript">

function addMyItem() {
    var myItem = {actionId: 'MyItem', label: 'My Item', icon:'http://mysite.com/icon.png'},
        contexts = [blackberry.ui.contextmenu.CONTEXT_IMAGE, blackberry.ui.contextmenu.CONTEXT_INPUT];
    blackberry.ui.contextmenu.addItem(contexts, myItem);
}

function removeMyItem() {
    var myItem = {actionId: 'MyItem', label: 'My Item', icon:'http://mysite.com/icon.png'},
        contexts = [blackberry.ui.contextmenu.CONTEXT_IMAGE, blackberry.ui.contextmenu.CONTEXT_INPUT];
    blackberry.ui.contextmenu.removeItem(contexts, myItem.actionId);
}

</script>

Properties

static boolean enabled


Context Menu enabled allows the developer to enabled and disable crosscut context menus for their application.


Supported Platforms


Parameters
enabled property that sets the contextmenu to enabled or disabled

Code Example:
<script type="text/javascript">

function disabledContextMenu() {
    blackberry.ui.contextmenu.enabled = false;
}

if(!blackberry.ui.contextmenu.enabled){
    console.log("context menu is currently disabled");
}
</script>

Constants

static String CONTEXT_ALL


Constant denoting all contexts.


Supported Platforms
 - BlackBerry 10
 - Ripple Emulator

static String CONTEXT_LINK


Constant denoting the context of links.


Supported Platforms
 - BlackBerry 10
 - Ripple Emulator

static String CONTEXT_IMAGE


Constant denoting the context of images.


Supported Platforms
 - BlackBerry 10
 - Ripple Emulator

static String CONTEXT_IMAGE_LINK


Constant denoting the context of image links.


Supported Platforms
 - BlackBerry 10
 - Ripple Emulator

static String CONTEXT_INPUT


Constant denoting the context of input fields.


Supported Platforms
 - BlackBerry 10
 - Ripple Emulator

static String CONTEXT_TEXT


Constant denoting the context of text.


Supported Platforms
 - BlackBerry 10
 - Ripple Emulator

static String ACTION_CANCEL


Constant denoting the actionId of cancel


Supported Platforms
 - BlackBerry 10
 - Ripple Emulator

static String ACTION_CLEAR_FIELD


Constant denoting the actionId of clear field.


Supported Platforms
 - BlackBerry 10
 - Ripple Emulator

static String ACTION_COPY


Constant denoting the actionId of copy.


Supported Platforms
 - BlackBerry 10
 - Ripple Emulator

static String ACTION_COPY_IMAGE_LINK


Constant denoting the actionId of copy image link.


Supported Platforms
 - BlackBerry 10
 - Ripple Emulator

static String ACTION_COPY_LINK


Constant denoting the actionId of copy link.


Supported Platforms
 - BlackBerry 10
 - Ripple Emulator

static String ACTION_CUT


Constant denoting the actionId of cut.


Supported Platforms
 - BlackBerry 10
 - Ripple Emulator

static String INSPECT_ELEMENT


Constant denoting the actionId of inspect element


Supported Platforms
 - BlackBerry 10
 - Ripple Emulator

static String ACTION_PASTE


Constant denoting the actionId of paste.


Supported Platforms
 - BlackBerry 10
 - Ripple Emulator

static String ACTIONE_SAVE_IMAGE


Constant denoting the actionId of save image.


Supported Platforms
 - BlackBerry 10
 - Ripple Emulator

static String ACTION_SAVE_LINK_AS


Constant denoting the actionId of save link as.


Supported Platforms
 - BlackBerry 10
 - Ripple Emulator

static String ACTION_SELECT


Constant denoting the actionId of select.


Supported Platforms
 - BlackBerry 10
 - Ripple Emulator

static String ACTION_VIEW_IMAGE


Constant denoting the actionId of view image.


Supported Platforms
 - BlackBerry 10
 - Ripple Emulator

Documentation generated by JsDoc Toolkit 2.4.0 on Mon Feb 11 2013 14:51:05 GMT-0500 (EST)