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:

• warn({}) -- displays an alert pane with a warning icon to the left.
• error() -- displays an alert with an error icon.
• info() -- displays an alert with an info icon.
• plain() -- displays an alert with no icon.
• show() -- displays an alert with the icon class you specify.

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

• message -- The alert's title message.
• description -- A longer description of the alert, displayed below the title in a smaller font.
• caption -- A third layer of alert text, displayed below the description in an even-smaller font.
• icon -- This is set for you automatically unless you call show. You may specify any icon class you wish. The icon is displayed at the alert pane's left.
• themeName -- A button theme that is applied to each button. The default is capsule.
• delegate -- A delegate to be notified when the user reacts to your pane. See "Responding to User Actions" below.
• buttons -- An array of up to three hashes used to customize the alert's buttons. See "Customizing Buttons" below.

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:

• title -- The button text. Highly recommended unless you like empty buttons.
• localize -- Whether to localize the title.
• toolTip -- An extra hint to show when the user hovers the mouse over the button. Make sure that the user can get along fine without this, as tooltips are hard to discover and unavailable on touch devices!
• isDefault -- You may specify a different button than the first, rightmost button to be the default (triggered by the enter key, and visually distinct in the default Ace theme).
• isCancel -- You may specify a different button than the second, middle button to be the cancel button (triggered by the escape key).
• target & action -- Supports the target/action pattern (see "Responding to User Actions" above).

(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

Class Methods

• error(args)
• info(args)
• plain(args)
• show(args)
• warn(args)

Instance Methods

• dismiss(sender)

alertPaneDidDismiss: function(pane, status) {}

See more examples for how to configure buttons and individual actions in the
documentation for the `SC.AlertPane` class.