Providing Native Dialog Prompts in your WebWorks Application

by Retired on ‎03-13-2013 02:40 PM (3,442 Views)

Dialog prompts can provide information about the state of the app, prompt for user input, or inform the user of the result of an action.


In general web development, developers can use the “alert()” or “confirm()” functions to prompt the user with a notification or prompt for a response.


In a BlackBerry® WebWorks™ app, there are APIs that provide a more native experience to the user: BlackBerry Toast and Dialog User Interface API.


A “toast” is equivalent to an “alert” which provides the user with information about the app and the “dialog” is equivalent to using a “confirmation”, which prompts the user to accept or cancel an action.


Comparison Screenshots


Toast vs Alert


simple.png IMG_00000033.png

BlackBerry Toast

JavaScript Alert




Dialog vs Confirm


dialog1.png confirm.png

BlackBerry Dialog 

*note the customized dialog title

JavaScript Confirm



Toast : blackberry.ui.toast



In your config.xml file ensure you have the following feature ID in order to use the BlackBerry Toast API


<feature id="blackberry.ui.toast" />


In your application source file, use the show() function to display a toast:


var message = 'This is a simple Toast';; 


 You can check out the Toast sample on github:


Dialog : blackberry.ui.dialog


The dialog box provides a customizable alternative to using the Javascript® confirm() method. Customization is available in the prompt text and prompt buttons.



In your config.xml file ensure you have the following feature ID in order to use the BlackBerry Dialog API:


<feature id="blackberry.ui.dialog" />


In your application source file, the following code will create a dialog box offering the user the option to “Save” or “Cancel”:


<script type="text/javascript">
function dialogCallBack(selection){
function standardDialog() {
  try {
    blackberry.ui.dialog.standardAskAsync("Save?", blackberry.ui.dialog.D_SAVE, dialogCallBack, {title : "Save Dialog"});
  }catch (e) {
    alert("Exception in standardDialog: " + e);



Dialog Type Samples

The dialog API allows 6 different types of dialogs to be displayed to the user:


  1. D_OK
  2. D_SAVE
  4. D_YES_NO


See the below screenshots for a sample of the different types of Dialog types you can specify using the blackberry.ui.dialog API.


*Note the default buttons that are displayed depending on the Dialog type.






D_SAVE: Discard and Save




D_DELETE: Cancel and Delete


D_YES_NO: No and Yes




D_OK_CANCEL: Cancel and OK


D_PROMPT: Prompts for input from the user, Cancel and OK




Learning Resources

For more information on using these APIs in your WebWorks applications, check out the following learning resources.


Dialog API

Toast API

Toast Sample on Github