Page tree

Have questions? Stuck? Please check our FAQ for some common questions and answers.

Skip to end of metadata
Go to start of metadata

DialogService

DialogService is an Angular Factory in the Layer module implemented by dialog.js. It provides an API to create (and show) a dialog panel with title, arbitrary content, and action buttons.

Here is the dialog in action in the Application View:

 

Name Summary
openDialogOpens (creates if necessary) the dialog.
closeDialogCloses the dialog.
createDivCreates an unattached <div> element.

 

Function Descriptions

openDialog

Creates the dialog panel if necessary, resets its content, then shows it on the screen. This function returns an API that allows the dialog box to be configured (more information below).

Example UsageArgumentsReturn Value
dialog = ds.openDialog(id, opts);id - a unique DOM identifier
opts - options for the dialog (see below) 
an API to configure the dialog. See below.

Both the id and opts arguments are passed through to the createPanel() function of the PanelService.

The opts object is angular.extended with the default options, shown below:

var defaultSettings = {
        width: 300,
        edge: 'left'
    };

If a cssCls property is defined on the options object, it's value is used as a CSS class that is applied to the dialog element.

 

closeDialog

Closes the dialog panel. This function is idempotent.

Example UsageArgumentsReturn Value
ds.closeDialog();nonenone

Note that the user action of pressing one of the dialog buttons closes the dialog panel implicitly. Typically, closeDialog() should be invoked when navigating away from the view, to make sure the dialog is cleaned up if it was left open by the user.

createDiv

Creates a detached <div> element, returning a D3 selection. Optionally, a CSS class may be specified to be applied to the element. 

Example UsageArgumentsReturn Value
content = ds.createDiv('my-class');
content.append('p').text('Some text');
cssCls - optional CSS class to apply to the div element.D3 selection of a detached div element.

This is a convenience function to help in the construction of content for the dialog. See below for a more complete example.

Dialog API

The API returned from openDialog() provides methods to set the title, add content, and add buttons.

Example UsageArgumentsReturn Value
dialog.setTitle(title);title - the text to set as the titledialog API
dialog.addContent(content);content - a D3 selection to be appended to the content section of the dialogdialog API

dialog.addButton(cb, text, key, chained);

cb - the callback function to be invoked when the button is pressed 

text - the text to display on the button

key - the logical name of the keyboard key bound to the button

chained - boolean true prevents dialog from being hidden when the button is pressed

dialog API
dialog.addOk(cb, text);

cb - the callback function to be invoked when the button is pressed

text - the text to display on the button [defaults to "OK"]

dialog API
dialog.addOkChained(cb, text);

cb - the callback function to be invoked when the button is pressed

text - the text to display on the button [defaults to "OK"]

dialog API
dialog.addCancel(cb, text);

cb - the callback function to be invoked when the button is pressed

text - the text to display on the button [defaults to "Cancel"]

dialog API
dialog.bindKeys();(none)(none)

Notes:

  • addOk() is shorthand for invoking addButton() bound to the enter key, with chained == false
  • addOkChained() is shorthand for invoking addButton() bound to the enter key, with chained == true
  • addCancel() is shorthand for invoking addButton bound to the escape key, with chained == false
  • specifying chained == true prevents the dialog from being dismissed; this allows the dialog to be reconfigured with a follow-on question
  • bindKeys() is required to be called as the last function, to bind the keys to the key service.

 

 

The following dialog box might have code structured as listed below:

 

A More Complete Example

// ds is a reference to the DialogService.
 
var dialogId = 'app-dialog',
    dialogOpts = {
        edge: 'right'
    };
 
function createConfirmationText(action, itemId) {
    var content = ds.createDiv();
    content.append('p').text(action + ' ' + itemId);
    return content;
}

function confirmAction(action) {
    var itemId = $scope.selId,
    spar = $scope.sortParams;

    function dOk() {
        $log.debug('Initiating', action, 'of', itemId);
        wss.sendEvent(appMgmtReq, {
            action: action,
            name: itemId,
            sortCol: spar.sortCol,
            sortDir: spar.sortDir
        });
    }

    function dCancel() {
        $log.debug('Canceling', action, 'of', itemId);
    }

    ds.openDialog(dialogId, dialogOpts)
        .setTitle('Confirm Action')
        .addContent(createConfirmationText(action, itemId))
        .addOk(dOk)
        .addCancel(dCancel)
        .bindKeys();
}
 
// e.g. confirmAction('activate');
//      $scope.selId contains the ID of the selected item


Notice how buttons added to the dialog appear right to left.

Also note, since addButton() takes just a function reference as its first argument, any data required for the function should be defined in the closure.

  

  • No labels