Context Menu

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

The following image shows a context menu on a device:

Device showing a context menu.

Installation:

To use this API in your project, add the contextmenu plugin:

webworks plugin add com.blackberry.ui.contextmenu

WebWorks applications can choose to use an in-app context menu as opposed to the default operating system menu. The Context Menu API allows you to control the elements that appear in the menu and provides event handlers that let you respond when the menu is triggered and displayed.

Note that starting with BlackBerry 10.2 OS, selecting text, a text link, or an input field brings up a Text Selection Menu. Selecting these types of items no longer brings up a context menu.

Enabling

The context menu can be enabled by calling the blackberry.ui.contextmenu.enabled property. When set to true, the context menu captures the context menu events, and passes any events that the user has registered for to the context menu. When set to false, the context menu defaults to the system, and you do not have access to the events described below.

Context Information

Context information is available from the window object through a context menu event called window.oncontextmenu. The oncontextmenu event is triggered whenever there is a context menu request from the client. This event provides all the contextual information your app needs to store the context and save what element the context menu was triggered on. This allows your app to perform different actions once a context menu has been requested.

Example:

<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;
  console.log(srcElement);
}

window.addEventListener('oncontextmenu', onContextMenu);
</script>
        

Learning Resources:

Sample - Using Custom Context Sample that demonstrates how to use the BlackBerry Custom Context API [BlackBerry on GitHub].

Example:

<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 are activated when the element is long pressed. When you create a custom context using the data-webworks-context attribute, you can then use addItem to add items to the custom context. You can also use defineCustomContext to further define the items shown.

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>
        
Properties:
Boolean enabled

addItem()

Allows you to add custom items to the context menu. The items are appended to the end of the list of operating system defined functions. You must provide the following parameters to successfully add items to the context menu.

Synopsis:

void blackberry.ui.contextmenu.addItem(contexts,action,callback)

Parameters:

contexts {String[]}

An array of constants defining which contexts this new item should appear.

action {Object}

An object which defines the menu item to be added.

actionId {String}

Desired title of the dialog.

label {String}

A string that is displayed to the user describing the custom context to be performed. For example, Edit.

icon {String}

A path to an image to display in the context menu.

callback {Function}

A function which runs when the menu item action is executed.

sourceId {String}

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

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("{Platform menu item Copy successfully overridden");
        });
    }

    //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>

clearOverride()

Allows you to clear the override on a platform menu item in the context menu.

Synopsis:

void blackberry.ui.contextmenu.clearOverride(actionId)

Parameters:

actionID {String}

The actionId of the context menu item to clear the override on.

Example:

<script type="text/javascript">

    function clearPlatformCopyOverride() { 
        var actionId = blackberry.ui.contextmenu.ACTION_COPY; 
        blackberry.ui.contextmenu.clearOverride(actionId);
    }

    clearPlatformCopyOverride();

</script>

defineCustomContext()

Allows you to define a custom context.

Synopsis:

void blackberry.ui.contextmenu.defineCustomContext(context,options)

Parameters:

context {String}

A String representing the custom context.

options {Object}

An Object that contains the various options to set for the custom context.

includeContextItems {Array}

An Array that defines a list of contexts to which custom items will be used from when applicable.

includePlatformItems {Boolean}

A Boolean indicating whether to include the default platform items.

includeMenuServiceItems {Boolean}

A Boolean indicating whether to add menu items provided by the menu service.

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>

disablePlatformItem()

Allows you to disable platform-provided menu items in the context menu. You must provide the following parameters to successfully disable platform items.

Synopsis:

Boolean blackberry.ui.contextmenu.disablePlatformItemItem(context,actionId)

Parameters:

context {String}

A string constant defining in which context this platform item should be removed.

actionId {String}

A string constant defining which item should be removed.

Returns:

{Boolean}

True if operation was successful.

Example:

<script type="text/javascript">

    function disableCopyItemForImageContext() {
        var context = blackberry.ui.contextmenu.CONTEXT_IMAGE,
            actionId = blackberry.ui.contextmenu.ACTION_COPY;
        blackberry.ui.contextmenu.disablePlatformItem(context, 
            actionId);
    }
</script>

enablePlatformItem()

Allows you to re-enable a disabled platform-provided menu item in the context menu. You must provide the following parameters to successfully re-enable the disabled platform item.

Synopsis:

Boolean blackberry.ui.contextmenu.enablePlatformItem(context,actionId)

Parameters:

context {String}

A string constant defining in which context this platform item should be restored.

actionId {String}

A string constant defining which item should be restored.

Returns:

{Boolean}

True if operation was successful.

Example:

<script type="text/javascript">

    function enableCopyItemForImageContext() {
        var context = blackberry.ui.contextmenu.CONTEXT_IMAGE,
            actionId = blackberry.ui.contextmenu.ACTION_COPY;
        blackberry.ui.contextmenu.enablePlatformItem(context, actionId);
    }
</script>

listDisabledPlatformItems()

Lists the disabled platform menu items in the context menu.

Synopsis:

Object[] blackberry.ui.contextmenu.listDisabledPlatformItems()

Returns:

{Object[]}

Two-dimensional array of disabled items. First index is context; second index is actionId.

Example:

<script type="text/javascript">

    function listDisabledMenuItems() {
        var imageContext = blackberry.ui.contextmenu.CONTEXT_IMAGE,
            disabledItems = 
                blackberry.ui.contextmenu.listDisabledPlatformItems();
        
        // Print all disabled platform items for the image context
        if (disabledItems[imageContext].length !== 0) {
            disabledItems[imageContext].forEach(function (actionId) {
                console.log(actionId);
            });
        }
    }
</script>

overrideItem()

Allows you to override platform menu items in the context menu.

Synopsis:

void blackberry.ui.contextmenu.overrideItem(action)

Parameters:

action {Object}

An object that should be used to override the platform menu item using the actionId.

actionId {String}

A property that uniquely defines the action to be added to the context menu.

label {String}

A string that is displayed to the user describing the custom context to be performed. For example, Edit.

icon {String}

A path to an image to display in the context menu.

callback {Function}

A function which runs when the menu item action is executed.

Example:

<script type="text/javascript">

    //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'};

        blackberry.ui.contextmenu.overrideItem(myItem, function() {
            alert("Plaform menu item Copy successfully overridden");
        });
    }

    //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'};
        
        blackberry.ui.contextmenu.overrideItem(myItem, function() {
            alert("Custom Save using system icon");
        });
    }
</script>

removeItem()

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

Synopsis:

void blackberry.ui.contextmenu.removeItem(contexts, actionId)

Parameters:

contexts {String[]}

An array of constants defining in which contexts this new item should appear.

actionId {Object}

An id that uniquely defines the action to be removed from the context menu.

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>

enabled

Context Menu enabled allows you to enabled or disable the cross-cut context menus for your application.

Parameters:

boolean {Boolean}

The enabled property that sets the contextmenu to enabled or disabled.

Synopsis:

Boolean blackberry.ui.contextmenu.enabled

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>
            

ACTION_CANCEL

Constant denoting the actionId of cancel.

Synopsis:

constant
String blackberry.ui.contextmenu.ACTION_CANCEL = "Cancel"

ACTION_CLEAR_FIELD

Constant denoting the actionId of clear field.

Synopsis:

constant
String blackberry.ui.contextmenu.ACTION_CLEAR_FIELD = "ClearField"

ACTION_COPY

Constant denoting the actionId of copy.

Synopsis:

constant
String blackberry.ui.contextmenu.ACTION_COPY = "Copy"

ACTION_COPY_IMAGE_LINK

Constant denoting the actionId of copy image link.

Synopsis:

constant {String}
String blackberry.ui.contextmenu.ACTION_COPY_IMAGE_LINK = "CopyImageLink"

ACTION_COPY_LINK

Constant denoting the actionId of copy link.

Synopsis:

constant {String}
String blackberry.ui.contextmenu.ACTION_COPY_LINK = "CopyLink"

ACTION_CUT

Constant denoting the actionId of cut.

Synopsis:

constant
String blackberry.ui.contextmenu.ACTION_CUT = "Cut"

ACTION_PASTE

Constant denoting the actionId of paste.

Synopsis:

constant
String blackberry.ui.contextmenu.ACTION_PASTE = "Paste"

ACTION_SAVE_IMAGE

Constant denoting the actionId of save image.

Synopsis:

constant
String blackberry.ui.contextmenu.ACTIONE_SAVE_IMAGE = "SaveImage"

ACTION_SAVE_LINK_AS

Constant denoting the actionId of save link as.

Synopsis:

constant
String blackberry.ui.contextmenu.ACTION_SAVE_LINK_AS = "SaveLinkAs"

ACTION_SELECT

Constant denoting the actionId of select.

Synopsis:

constant
String blackberry.ui.contextmenu.ACTION_SELECT= "Select"

ACTION_VIEW_IMAGE

Constant denoting the actionId of view image.

Synopsis:

constant
String blackberry.ui.contextmenu.ACTION_VIEW_IMAGE = "ViewImage"

CONTEXT_ALL

Constant denoting all contexts.

Synopsis:

constant
String blackberry.ui.contextmenu.CONTEXT_ALL = "CONTEXT_ALL"

CONTEXT_IMAGE

Constant denoting the context of images.

Synopsis:

constant
String blackberry.ui.contextmenu.CONTEXT_IMAGE = "CONTEXT_IMAGE"

CONTEXT_IMAGE_LINK

Constant denoting the context of image links.

Synopsis:

constant
String blackberry.ui.contextmenu.CONTEXT_IMAGE_LINK = "CONTEXT_IMAGE_LINK"

CONTEXT_INPUT

Constant denoting the context of input fields.

Synopsis:

constant
String blackberry.ui.contextmenu.CONTEXT_INPUT = "CONTEXT_INPUT"

CONTEXT_LINK

Constant denoting the context of links.

Synopsis:

constant
String blackberry.ui.contextmenu.CONTEXT_LINK = "CONTEXT_LINK"

CONTEXT_TEXT

Constant denoting the context of text.

Synopsis:

constant
String blackberry.ui.contextmenu.CONTEXT_TEXT = "CONTEXT_TEXT"

INSPECT_ELEMENT

Constant denoting the actionId of inspect element.

Synopsis:

constant
String blackberry.ui.contextmenu.INSPECT_ELEMENT = "InspectElement"

Last modified: 2014-05-14



Got questions about leaving a comment? Get answers from our Disqus FAQ.

comments powered by Disqus