alert-controller.js 9.1KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238
  1. import { Injectable } from '@angular/core';
  2. import { Alert } from './alert';
  3. import { App } from '../app/app';
  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.present();
  60. * }
  61. *
  62. * presentConfirm() {
  63. * const alert = this.alertCtrl.create({
  64. * title: 'Confirm purchase',
  65. * message: 'Do you want to buy this book?',
  66. * buttons: [
  67. * {
  68. * text: 'Cancel',
  69. * role: 'cancel',
  70. * handler: () => {
  71. * console.log('Cancel clicked');
  72. * }
  73. * },
  74. * {
  75. * text: 'Buy',
  76. * handler: () => {
  77. * console.log('Buy clicked');
  78. * }
  79. * }
  80. * ]
  81. * });
  82. * alert.present();
  83. * }
  84. *
  85. * presentPrompt() {
  86. * const alert = this.alertCtrl.create({
  87. * title: 'Login',
  88. * inputs: [
  89. * {
  90. * name: 'username',
  91. * placeholder: 'Username'
  92. * },
  93. * {
  94. * name: 'password',
  95. * placeholder: 'Password',
  96. * type: 'password'
  97. * }
  98. * ],
  99. * buttons: [
  100. * {
  101. * text: 'Cancel',
  102. * role: 'cancel',
  103. * handler: data => {
  104. * console.log('Cancel clicked');
  105. * }
  106. * },
  107. * {
  108. * text: 'Login',
  109. * handler: data => {
  110. * if (User.isValid(data.username, data.password)) {
  111. * // logged in!
  112. * } else {
  113. * // invalid login
  114. * return false;
  115. * }
  116. * }
  117. * }
  118. * ]
  119. * });
  120. * alert.present();
  121. * }
  122. * ```
  123. * @advanced
  124. *
  125. *
  126. * Alert options
  127. *
  128. * | Property | Type | Description |
  129. * |-----------------------|-----------|------------------------------------------------------------------------------|
  130. * | title | `string` | The title for the alert. |
  131. * | subTitle | `string` | The subtitle for the alert. |
  132. * | message | `string` | The message for the alert. |
  133. * | cssClass | `string` | Additional classes for custom styles, separated by spaces. |
  134. * | inputs | `array` | An array of inputs for the alert. See input options. |
  135. * | buttons | `array` | An array of buttons for the alert. See buttons options. |
  136. * | enableBackdropDismiss | `boolean` | Whether the alert should be dismissed by tapping the backdrop. Default true. |
  137. *
  138. *
  139. * Input options
  140. *
  141. * | Property | Type | Description |
  142. * |-------------|-----------|-----------------------------------------------------------------|
  143. * | type | `string` | The type the input should be: text, tel, number, etc. |
  144. * | name | `string` | The name for the input. |
  145. * | placeholder | `string` | The input's placeholder (for textual/numeric inputs) |
  146. * | value | `string` | The input's value. |
  147. * | label | `string` | The input's label (only for radio/checkbox inputs) |
  148. * | checked | `boolean` | Whether or not the input is checked. |
  149. * | id | `string` | The input's id. |
  150. *
  151. * Button options
  152. *
  153. * | Property | Type | Description |
  154. * |----------|----------|-----------------------------------------------------------------|
  155. * | text | `string` | The buttons displayed text. |
  156. * | handler | `any` | Emitted when the button is pressed. |
  157. * | cssClass | `string` | An additional CSS class for the button. |
  158. * | role | `string` | The buttons role, null or `cancel`. |
  159. *
  160. * ### Dismissing And Async Navigation
  161. *
  162. * After an alert has been dismissed, the app may need to also transition
  163. * to another page depending on the handler's logic. However, because multiple
  164. * transitions were fired at roughly the same time, it's difficult for the
  165. * nav controller to cleanly animate multiple transitions that may
  166. * have been kicked off asynchronously. This is further described in the
  167. * [`Nav Transition Promises`](../../nav/NavController) section. For alerts,
  168. * this means it's best to wait for the alert to finish its transition
  169. * out before starting a new transition on the same nav controller.
  170. *
  171. * In the example below, after the alert button has been clicked, its handler
  172. * waits on async operation to complete, *then* it uses `pop` to navigate
  173. * back a page in the same stack. The potential problem is that the async operation
  174. * may have been completed before the alert has even finished its transition
  175. * out. In this case, it's best to ensure the alert has finished its transition
  176. * out first, *then* start the next transition.
  177. *
  178. * ```ts
  179. * const alert = this.alertCtrl.create({
  180. * title: 'Hello',
  181. * buttons: [{
  182. * text: 'Ok',
  183. * handler: () => {
  184. * // user has clicked the alert button
  185. * // begin the alert's dismiss transition
  186. * const navTransition = alert.dismiss();
  187. *
  188. * // start some async method
  189. * someAsyncOperation().then(() => {
  190. * // once the async operation has completed
  191. * // then run the next nav transition after the
  192. * // first transition has finished animating out
  193. *
  194. * navTransition.then(() => {
  195. * this.nav.pop();
  196. * });
  197. * });
  198. * return false;
  199. * }
  200. * }]
  201. * });
  202. *
  203. * alert.present();
  204. * ```
  205. *
  206. * It's important to note that the handler returns `false`. A feature of
  207. * button handlers is that they automatically dismiss the alert when their button
  208. * was clicked, however, we'll need more control regarding the transition. Because
  209. * the handler returns `false`, then the alert does not automatically dismiss
  210. * itself. Instead, you now have complete control of when the alert has finished
  211. * transitioning, and the ability to wait for the alert to finish transitioning
  212. * out before starting a new transition.
  213. *
  214. *
  215. * @demo /docs/demos/src/alert/
  216. */
  217. export class AlertController {
  218. constructor(_app, config) {
  219. this._app = _app;
  220. this.config = config;
  221. }
  222. /**
  223. * Display an alert with a title, inputs, and buttons
  224. * @param {AlertOptions} opts Alert. See the table below
  225. */
  226. create(opts = {}) {
  227. return new Alert(this._app, opts, this.config);
  228. }
  229. }
  230. AlertController.decorators = [
  231. { type: Injectable },
  232. ];
  233. /** @nocollapse */
  234. AlertController.ctorParameters = () => [
  235. { type: App, },
  236. { type: Config, },
  237. ];
  238. //# sourceMappingURL=alert-controller.js.map