Class: SC.AlertPane


Extends SC.PanelPane.

Displays a preformatted modal alert pane.

Alert panes are a simple way to provide modal messaging that otherwise blocks the user's interaction with your application. Alert panes are useful for showing important error messages and confirmation dialogs. They provide a substantially better user experience than using the OS-level alert dialogs.

Displaying an Alert Pane

The easiest way to display an alert pane is to use one of the various class methods defined on SC.AlertPane, passing the message and an optional detailed description and caption.

There are four variations of this method can you can invoke:

Each method takes a single argument: a hash of options. These options include:

Responding to User Actions

Often, you may wish to be notified when the user has dismissed to your alert. You have two options: you may specify a delegate in the options hash, or you may customize each button with a target & action.

If you specify a delegate, it must implement a method with the following signature: alertPaneDidDismiss(pane,buttonKey). When the user dismisses your alert, this method will be called with the pane instance and a key indicating which button was pressed (one of either SC.BUTTON1_STATUS, SC.BUTTON2_STATUS or SC.BUTTON3_STATUS).

If you specify a target/action for a button (see "Customizing Buttons" below) and the user dismisses the alert with that button, that action will be triggered. If you specify a delegate but no target, the delegate will be used as the target. The action will be called with the alert pane itself as the sender (first argument).

Customizing Buttons

SC.AlertPane allows you to specify up to three buttons, arranged from right to left (as on Mac OS X). You can customize them by passing an array of up to three options hashes on the buttons property. By default, the first, rightmost button is the default (i.e. it is triggered when the user hits the enter key), and the second button is the "cancel" button (triggered by the escape key).

If you don't specify any buttons, a single default "OK" button will appear.

You may customize the following button options:

(You may also specify a layerId for the button if needed. As always, using custom layerIds is dangerous and should be avoided unless you know what you're doing.)

Examples

Show a simple AlertPane with a warning (!) icon and an OK button:

SC.AlertPane.warn({
  message: "Could not load calendar",
  description: "Your internet connection may be unavailable or our servers may be down.",
  caption: "Try again in a few minutes."
});

Show an AlertPane with a customized OK button title (title will be 'Try Again'):

SC.AlertPane.warn({
  message: "Could not load calendar",
  description: "Your internet connection may be unavailable or our servers may be down.",
  caption: "Try again in a few minutes.",
  buttons: [
    { title: "Try Again" }
  ]
});

Show an AlertPane with fully customized buttons:

SC.AlertPane.show({
  message: "Could not load calendar",
  description: "Your internet connection may be unavailable or our servers may be down.",
  caption: "Try again in a few minutes.",
  buttons: [
    { title: "Try Again", toolTip: "Retry the connection", isDefault: true },
    { title: "More Info...", toolTip: "Get more info" },
    { title: "Cancel", toolTip: "Cancel the action", isCancel: true }
  ]
});

Show an alert pane, using the delegate pattern to respond to how the user dismisses it.

MyApp.calendarController = SC.Object.create({
  alertPaneDidDismiss: function(pane, status) {
    switch(status) {
      case SC.BUTTON1_STATUS:
        this.tryAgain();
        break;
      case SC.BUTTON2_STATUS:
        // do nothing
        break;
      case SC.BUTTON3_STATUS:
        this.showMoreInfo();
        break;
    }
  },
  ...
});

SC.AlertPane.warn({
  message: "Could not load calendar",
  description: "Your internet connection may be unavailable or our servers may be down.",
  caption: "Try again in a few minutes.",
  delegate: MyApp.calendarController,
  buttons: [
    { title: "Try Again" },
    { title: "Cancel" },
    { title: "More Info…" }
  ]
});

Show an alert pane using the target/action pattern on each button to respond to how the user dismisses it.

SC.AlertPane.warn({
  message: "Could not load calendar",
  description: "Your internet connection may be unavailable or our servers may be down.",
  caption: "Try again in a few minutes.",
  buttons: [
    {
      title: "Try Again",
      action: "doTryAgain",
      target: MyApp.calendarController
    },
    {
      title: "Cancel",
      action: "doCancel",
      target: MyApp.calendarController
    },
    {
      title: "More Info…",
      action: "doGiveMoreInfo",
      target: MyApp.calendarController
    }
  ]
});

Defined in: alert.js

Since:
SproutCore 1.0

Field Summary

Fields borrowed from SC.PanelPane:
acceptsKeyPane, ariaDescribedBy, ariaLabelledBy, contentView, isModal, isPanelPane, modalPane, renderDelegateName
Fields borrowed from SC.Pane:
currentWindowSize, firstResponder, isKeyPane, isMainPane, isPane, page, rootResponder, touchZ, wantsTouchIntercept, zIndex
Fields borrowed from SC.View:
acceptsFirstResponder, acceptsMultitouch, ariaHidden, attributeBindings, autoMixins, backgroundColor, childViewLayout, childViewLayoutOptions, childViews, childViewsNeedLayout, classNameBindings, concatenatedProperties, createdByParent, designMode, displayProperties, enabledState, firstKeyView, hasLayout, hasTouch, hasVisibility, isBuildingIn, isBuildingOut, isChildViewLayoutLive, isEnabled, isFixedHeight, isFixedPosition, isFixedSize, isFixedWidth, isKeyResponder, isTextSelectable, isView, isVisible, lastKeyView, layerLocationNeedsUpdate, layerNeedsUpdate, modeAdjust, nextKeyView, pane, parentView, previousKeyView, shouldInheritCursor, shouldInheritEnabled, tagName, themeName, toolTip, touchBoundary, transitionAdjust, transitionAdjustOptions, transitionHide, transitionHideOptions, transitionIn, transitionInOptions, transitionOut, transitionOutOptions, transitionShow, transitionShowOptions, useStaticLayout
Fields borrowed from SC.Responder:
hasFirstResponder, isFirstResponder, responderContext
Fields borrowed from SC.Object:
isDestroyed, isObject, nextProperty, object, property, target, toInvalidate
Fields borrowed from SC.Observable:
isObservable

Class Methods

Instance Methods

Field Detail

ariaLabel
The ARIA label for the alert is the message, by default.
ariaRole String
The WAI-ARIA role for alert pane.
Default value:
'alertdialog'
button1 SC.ButtonView
The button view for button 1 (OK).
button2 SC.ButtonView
The button view for the button 2 (Cancel).
button3 SC.ButtonView
The button view for the button 3 (Extra).
buttonThreeWrapper SC.View
The view for the button 3 (Extra) wrapper.
caption String

An optional detailed caption. Use this string to provide further fine print explanation of the condition and, optionally, ways the user can resolve the problem.

Default value:
""
classNames Array
Default value:
['sc-alert']
See:
SC.View#classNames
delegate Object

If defined, the delegate is notified when the pane is dismissed. If you have set specific button actions, they will be called on the delegate object

The method to be called on your delegate will be:

alertPaneDidDismiss: function(pane, status) {}

The status will be one of SC.BUTTON1_STATUS, SC.BUTTON2_STATUS or SC.BUTTON3_STATUS depending on which button was clicked.

Default value:
null
description String

An optional detailed description. Use this string to provide further explanation of the condition and, optionally, ways the user can resolve the problem.

Default value:
""
displayCaption String
An escaped and formatted version of the caption property.
displayDescription String
An escaped and formatted version of the description property.
icon String

The icon URL or class name. If you do not set this, an alert icon will be shown instead.

Default value:
'sc-icon-alert-48'
layout Hash message String

The primary message to display. This message will appear in large bold type at the top of the alert.

Default value:
""

Class Method Detail

error(args)

Same as show() just that it uses sc-icon-error-48 CSS classname as the dialog icon

Parameters:
args Hash
Returns:
SC.AlertPane
the pane shown
info(args)

Same as show() just that it uses sc-icon-info-48 CSS classname as the dialog icon

Parameters:
args Hash
Returns:
SC.AlertPane
the pane shown
plain(args)

Same as show() just that it uses blank CSS classname as the dialog icon

Parameters:
args Hash
Returns:
SC.AlertPane
the pane shown
show(args)

Show a dialog with a given set of hash attributes:

SC.AlertPane.show({ message: "Could not load calendar", description: "Your internet connection may be unavailable or our servers may be down.", caption: "Try again in a few minutes.", delegate: MyApp.calendarController });

See more examples for how to configure buttons and individual actions in the
documentation for the `SC.AlertPane` class.
Parameters:
args Hash
Returns:
SC.AlertPane
the pane shown
warn(args)

Same as show() just that it uses sc-icon-alert-48 CSS classname as the dialog icon

Parameters:
args Hash
Returns:
SC.AlertPane
the pane shown

Instance Method Detail

dismiss(sender)

Action triggered whenever any button is pressed. Also the hides the alertpane itself.

This will trigger the following chain of events:

  1. If a delegate was given, and it has alertPaneDidDismiss it will be called
  2. Otherwise it will look for the action of the button and call: a) The action function reference if one was given b) The action method on the target if one was given c) If both a and b are missing, call the action on the rootResponder
Parameters:
sender SC.View
- the button view that was clicked
Documentation generated by JsDoc Toolkit 2.4.0 on Wed Apr 08 2015 10:02:20 GMT-0600 (CST)