# Mojo.Controller

## Namespace Detail

webOS' user experience architecture provides for a greater degree of application scope than is normally considered in a web application; to support this and specific functions of the framework, Palm has introduced a structure for webOS applications built around stages and scenes.

The framework has a number of Controller functions specifically designed to assist you in managing stages and scenes.

1. See Mojo.Controller.AppController
2. See Mojo.Controller.StageController
3. See Mojo.Controller.SceneController

## Summary

- Mojo.Controller.errorDialog
- Mojo.Controller.getAppController
- Mojo.Controller.showAlertDialog
- Mojo.Controller.showDialog

## Detail

### Mojo.Controller.errorDialog

#### Overview

The simplest dialog case is a modal error dialog with a fixed dialog title of 'Error', a short message and an confirmation button. Dialogs are accessed through controller functions rather than as widgets. We've included them here because we think that fit more closely with the UI widgets than with the other UI APIs.

#### Function Call

>     Mojo.Controller.errorDialog(message);

#### Arguments

>     Argument        Type        Required    Default     Description
>     ------------------------------------------------------------------------------------
>     message         String      Required    Null        Displayed message in modal dialog

#### Styles

>     Class Names                 Properties
>     ------------------------------------------------------------------------------------
>     TBD

### {Object} Mojo.Controller.getAppController

Utility function to return a reference to the application controller. Works correctly in parent or child windows.

### Mojo.Controller.showAlertDialog

#### Overview

To display a short message to the user, use an Alert Dialog with a message and one or more selection options presented as HTML buttons. When an option is selected, your specified callback function is called with the value assigned to the selection. If there is no selection (e.g., the user gestures back to exit the dialog) then the onChoose function is called with an undefined value.

#### Function Call

>     this.controller.showAlertDialog({
>       onChoose: function(value) {
>           this.outputDisplay.innerHTML = $L("Alert result = ") + value;},
>           title: $L("Filet Mignon"),
>           message: $L("How would you like your steak done?"),
>           choices:[
>               {label:$L('Rare'), value:"rare", type:'affirmative'},
>               {label:$L("Medium"), value:"med"},
>               {label:$L("Overcooked"), value:"well", type:'negative'},
>               {label:$L("Nevermind"), value:"cancel", type:'dismiss'}
>           ]
>       }
>     );

#### Arguments

>     Argument         Type        Required    Default     Description
>     ------------------------------------------------------------------------------------
>     onChoose         Function    Required    None        Called when user makes a choice and the dialog is dismissed
>     title            String      Optional    None        Title of the dialog
>     message          String      Optional    None        Text message to display in the dialog.
>     preventCancel    Boolean     Optional    FALSE       If true, back gesture or other alerts will not cancel the dialog.
>                                                          Defaults to 'false' if unspecified.
>     choices          Array       Required    None        List of actions the user can choose, currently rendered as buttons in the dialog.
>          label       String      Required    None        Display name of this choice
>          value       Any         Required    None        Value to return if this choice is made
>          type        String      Optional    primary     One of the button classes for styling
>     allowHTMLMessage Boolean     Optional    false       If true, the message string will not have HTML escaped.

### Mojo.Controller.showDialog

#### Overview

Dialogs can be used to display custom content to the user in the form of a modal dialog box. You can put anything into a Dialog that you'd put into a scene, which is any web content or Mojo UI content. To create a dialog, you'll call this.controller.showDialog with an object containing at least the dialog template (which will look like any other scene view file), any properties referenced in the template, and a dialog assistant object.

The following methods will be called in the dialog assistant if implemented:

- setup(widget) - Called with the dialog widget when the dialog is instantiated.
- cleanup() - Called when the dialog widget has been cleaned up.
- activate() - Called following setup(), after child widgets have been instantiated.
- deactivate() - Called when the dialog is closed, before it's been cleaned up.
- handleCommand(event) - If implemented, the dialog assistant is pushed onto the scene's commander stack while the dialog is active.

#### Function Call

>     this.controller.showDialog({
>       template: 'dialogs/sample-dialog',
>       assistant: new SampleDialogAssistant(this),
>       preventCancel:true
>     });

#### Arguments

>     Argument        Type        Required    Default     Description
>     ------------------------------------------------------------------------------------
>     template        String      Required    None        File Path to HTML template containing content for the dialog.
>                                                         Rendered with properties from this model object.
>     assistant       Object      Required    None        The 'dialog assistant' responsible for running the dialog,
>                                                         which may implement certain methods (see above).
>     preventCancel   Boolean     Optional    FALSE       If true, back gesture or other alerts will not cancel the dialog.
>                                                         Defaults to 'false' if unspecified.