| 1 | import { Alert } from './alert';
|
| 2 | import { App } from '../app/app';
|
| 3 | import { AlertOptions } from './alert-options';
|
| 4 | import { Config } from '../../config/config';
|
| 5 | /**
|
| 6 | * @name AlertController
|
| 7 | * @description
|
| 8 | * An Alert is a dialog that presents users with information or collects
|
| 9 | * information from the user using inputs. An alert appears on top
|
| 10 | * of the app's content, and must be manually dismissed by the user before
|
| 11 | * they can resume interaction with the app. It can also optionally have a
|
| 12 | * `title`, `subTitle` and `message`.
|
| 13 | *
|
| 14 | * You can pass all of the alert's options in the first argument of
|
| 15 | * the create method: `create(opts)`. Otherwise the alert's instance
|
| 16 | * has methods to add options, such as `setTitle()` or `addButton()`.
|
| 17 | *
|
| 18 | *
|
| 19 | * ### Alert Buttons
|
| 20 | *
|
| 21 | * In the array of `buttons`, each button includes properties for its `text`,
|
| 22 | * and optionally a `handler`. If a handler returns `false` then the alert
|
| 23 | * will not automatically be dismissed when the button is clicked. All
|
| 24 | * buttons will show up in the order they have been added to the `buttons`
|
| 25 | * array, from left to right. Note: The right most button (the last one in
|
| 26 | * the array) is the main button.
|
| 27 | *
|
| 28 | * Optionally, a `role` property can be added to a button, such as `cancel`.
|
| 29 | * If a `cancel` role is on one of the buttons, then if the alert is
|
| 30 | * dismissed by tapping the backdrop, then it will fire the handler from
|
| 31 | * the button with a cancel role.
|
| 32 | *
|
| 33 | *
|
| 34 | * ### Alert Inputs
|
| 35 | *
|
| 36 | * Alerts can also include several different inputs whose data can be passed
|
| 37 | * back to the app. Inputs can be used as a simple way to prompt users for
|
| 38 | * information. Radios, checkboxes and text inputs are all accepted, but they
|
| 39 | * cannot be mixed. For example, an alert could have all radio button inputs,
|
| 40 | * or all checkbox inputs, but the same alert cannot mix radio and checkbox
|
| 41 | * inputs. Do note however, different types of "text"" inputs can be mixed,
|
| 42 | * such as `url`, `email`, `text`, etc. If you require a complex form UI
|
| 43 | * which doesn't fit within the guidelines of an alert then we recommend
|
| 44 | * building the form within a modal instead.
|
| 45 | *
|
| 46 | *
|
| 47 | * @usage
|
| 48 | * ```ts
|
| 49 | * import { AlertController } from 'ionic-angular';
|
| 50 | *
|
| 51 | * constructor(public alertCtrl: AlertController) { }
|
| 52 | *
|
| 53 | * presentAlert() {
|
| 54 | * const alert = this.alertCtrl.create({
|
| 55 | * title: 'Low battery',
|
| 56 | * subTitle: '10% of battery remaining',
|
| 57 | * buttons: ['Dismiss']
|
| 58 | * });
|
| 59 | * alert.onDidDismiss(() => console.log('Alert was dismissed by the user'));
|
| 60 | * alert.present();
|
| 61 | * }
|
| 62 | *
|
| 63 | * presentConfirm() {
|
| 64 | * const alert = this.alertCtrl.create({
|
| 65 | * title: 'Confirm purchase',
|
| 66 | * message: 'Do you want to buy this book?',
|
| 67 | * buttons: [
|
| 68 | * {
|
| 69 | * text: 'Cancel',
|
| 70 | * role: 'cancel',
|
| 71 | * handler: () => {
|
| 72 | * console.log('Cancel clicked');
|
| 73 | * }
|
| 74 | * },
|
| 75 | * {
|
| 76 | * text: 'Buy',
|
| 77 | * handler: () => {
|
| 78 | * console.log('Buy clicked');
|
| 79 | * }
|
| 80 | * }
|
| 81 | * ]
|
| 82 | * });
|
| 83 | * alert.onDidDismiss(() => console.log('Alert was dismissed by the user'));
|
| 84 | * alert.present();
|
| 85 | * }
|
| 86 | *
|
| 87 | * presentPrompt() {
|
| 88 | * const alert = this.alertCtrl.create({
|
| 89 | * title: 'Login',
|
| 90 | * inputs: [
|
| 91 | * {
|
| 92 | * name: 'username',
|
| 93 | * placeholder: 'Username'
|
| 94 | * },
|
| 95 | * {
|
| 96 | * name: 'password',
|
| 97 | * placeholder: 'Password',
|
| 98 | * type: 'password'
|
| 99 | * }
|
| 100 | * ],
|
| 101 | * buttons: [
|
| 102 | * {
|
| 103 | * text: 'Cancel',
|
| 104 | * role: 'cancel',
|
| 105 | * handler: data => {
|
| 106 | * console.log('Cancel clicked');
|
| 107 | * }
|
| 108 | * },
|
| 109 | * {
|
| 110 | * text: 'Login',
|
| 111 | * handler: data => {
|
| 112 | * if (User.isValid(data.username, data.password)) {
|
| 113 | * // logged in!
|
| 114 | * } else {
|
| 115 | * // invalid login
|
| 116 | * return false;
|
| 117 | * }
|
| 118 | * }
|
| 119 | * }
|
| 120 | * ]
|
| 121 | * });
|
| 122 | * alert.present();
|
| 123 | * }
|
| 124 | * ```
|
| 125 | * @advanced
|
| 126 | *
|
| 127 | *
|
| 128 | * Alert options
|
| 129 | *
|
| 130 | * | Property | Type | Description |
|
| 131 | * |-----------------------|-----------|------------------------------------------------------------------------------|
|
| 132 | * | title | `string` | The title for the alert. |
|
| 133 | * | subTitle | `string` | The subtitle for the alert. |
|
| 134 | * | message | `string` | The message for the alert. |
|
| 135 | * | cssClass | `string` | Additional classes for custom styles, separated by spaces. |
|
| 136 | * | inputs | `array` | An array of inputs for the alert. See input options. |
|
| 137 | * | buttons | `array` | An array of buttons for the alert. See buttons options. |
|
| 138 | * | enableBackdropDismiss | `boolean` | Whether the alert should be dismissed by tapping the backdrop. Default true. |
|
| 139 | *
|
| 140 | *
|
| 141 | * Input options
|
| 142 | *
|
| 143 | * | Property | Type | Description |
|
| 144 | * |-------------|-----------|-----------------------------------------------------------------|
|
| 145 | * | type | `string` | The type the input should be: text, tel, number, etc. |
|
| 146 | * | name | `string` | The name for the input. |
|
| 147 | * | placeholder | `string` | The input's placeholder (for textual/numeric inputs) |
|
| 148 | * | value | `string` | The input's value. |
|
| 149 | * | label | `string` | The input's label (only for radio/checkbox inputs) |
|
| 150 | * | checked | `boolean` | Whether or not the input is checked. |
|
| 151 | * | disabled | `boolean` | Whether or not the input is disabled. |
|
| 152 | * | id | `string` | The input's id. |
|
| 153 | *
|
| 154 | * Button options
|
| 155 | *
|
| 156 | * | Property | Type | Description |
|
| 157 | * |----------|----------|-----------------------------------------------------------------|
|
| 158 | * | text | `string` | The buttons displayed text. |
|
| 159 | * | handler | `any` | Emitted when the button is pressed. |
|
| 160 | * | cssClass | `string` | An additional CSS class for the button. |
|
| 161 | * | role | `string` | The buttons role, null or `cancel`. |
|
| 162 | *
|
| 163 | * ### Detecting dismissal
|
| 164 | *
|
| 165 | * Any dismissal of the alert (including backdrop) can be detected
|
| 166 | * using the method `onDidDismiss(() => {})`.
|
| 167 | *
|
| 168 | * ### Dismissing And Async Navigation
|
| 169 | *
|
| 170 | * After an alert has been dismissed, the app may need to also transition
|
| 171 | * to another page depending on the handler's logic. However, because multiple
|
| 172 | * transitions were fired at roughly the same time, it's difficult for the
|
| 173 | * nav controller to cleanly animate multiple transitions that may
|
| 174 | * have been kicked off asynchronously. This is further described in the
|
| 175 | * [`Nav Transition Promises`](../../nav/NavController) section. For alerts,
|
| 176 | * this means it's best to wait for the alert to finish its transition
|
| 177 | * out before starting a new transition on the same nav controller.
|
| 178 | *
|
| 179 | * In the example below, after the alert button has been clicked, its handler
|
| 180 | * waits on async operation to complete, *then* it uses `pop` to navigate
|
| 181 | * back a page in the same stack. The potential problem is that the async operation
|
| 182 | * may have been completed before the alert has even finished its transition
|
| 183 | * out. In this case, it's best to ensure the alert has finished its transition
|
| 184 | * out first, *then* start the next transition.
|
| 185 | *
|
| 186 | * ```ts
|
| 187 | * const alert = this.alertCtrl.create({
|
| 188 | * title: 'Hello',
|
| 189 | * buttons: [{
|
| 190 | * text: 'Ok',
|
| 191 | * handler: () => {
|
| 192 | * // user has clicked the alert button
|
| 193 | * // begin the alert's dismiss transition
|
| 194 | * const navTransition = alert.dismiss();
|
| 195 | *
|
| 196 | * // start some async method
|
| 197 | * someAsyncOperation().then(() => {
|
| 198 | * // once the async operation has completed
|
| 199 | * // then run the next nav transition after the
|
| 200 | * // first transition has finished animating out
|
| 201 | *
|
| 202 | * navTransition.then(() => {
|
| 203 | * this.nav.pop();
|
| 204 | * });
|
| 205 | * });
|
| 206 | * return false;
|
| 207 | * }
|
| 208 | * }]
|
| 209 | * });
|
| 210 | *
|
| 211 | * alert.present();
|
| 212 | * ```
|
| 213 | *
|
| 214 | * It's important to note that the handler returns `false`. A feature of
|
| 215 | * button handlers is that they automatically dismiss the alert when their button
|
| 216 | * was clicked, however, we'll need more control regarding the transition. Because
|
| 217 | * the handler returns `false`, then the alert does not automatically dismiss
|
| 218 | * itself. Instead, you now have complete control of when the alert has finished
|
| 219 | * transitioning, and the ability to wait for the alert to finish transitioning
|
| 220 | * out before starting a new transition.
|
| 221 | *
|
| 222 | *
|
| 223 | * @demo /docs/demos/src/alert/
|
| 224 | */
|
| 225 | export declare class AlertController {
|
| 226 | private _app;
|
| 227 | config: Config;
|
| 228 | constructor(_app: App, config: Config);
|
| 229 | /**
|
| 230 | * Display an alert with a title, inputs, and buttons
|
| 231 | * @param {AlertOptions} opts Alert. See the table below
|
| 232 | */
|
| 233 | create(opts?: AlertOptions): Alert;
|
| 234 | }
|