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';
blackberry.ui.toast.show(message); 

  

 You can check out the Toast sample on github: https://github.com/blackberry/BB10-WebWorks-Samples/tree/master/Toast

 

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){
  alert(selection.return);
}
 
function standardDialog() {
  try {
    blackberry.ui.dialog.standardAskAsync("Save?", blackberry.ui.dialog.D_SAVE, dialogCallBack, {title : "Save Dialog"});
  }catch (e) {
    alert("Exception in standardDialog: " + e);
  }
}
 
</script>

 

 

Dialog Type Samples

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

 

  1. D_OK
  2. D_SAVE
  3. D_DELETE
  4. D_YES_NO
  5. D_OK_CANCEL
  6. D_PROMPT

 

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.

 

 dialogOK.png

 dialogSAVE.png

D_OK: OK

 

D_SAVE: Discard and Save

 

 dialogDELETE.png

 dialogYESNO.png

D_DELETE: Cancel and Delete

 

D_YES_NO: No and Yes

 

 dialogOKCANCEL.png

 dialogPROMPT.png

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