Alert
An Alert is a dialog that presents users with information or collects
information from the user using inputs. An alert appears on top
of the app's content, and must be manually dismissed by the user before
they can resume interaction with the app. It can also optionally have a
title
, subTitle
and message
.
You can pass all of the alert's options in the first argument of
the create method: Alert.create(opts)
. Otherwise the alert's instance
has methods to add options, such as setTitle()
or addButton()
.
Alert Buttons
In the array of buttons
, each button includes properties for its text
,
and optionally a handler
. If a handler returns false
then the alert
will not automatically be dismissed when the button is clicked. All
buttons will show up in the order they have been added to the buttons
array, from left to right. Note: The right most button (the last one in
the array) is the main button.
Optionally, a role
property can be added to a button, such as cancel
.
If a cancel
role is on one of the buttons, then if the alert is
dismissed by tapping the backdrop, then it will fire the handler from
the button with a cancel role.
Alert Inputs
Alerts can also include several different inputs whose data can be passed
back to the app. Inputs can be used as a simple way to prompt users for
information. Radios, checkboxes and text inputs are all accepted, but they
cannot be mixed. For example, an alert could have all radio button inputs,
or all checkbox inputs, but the same alert cannot mix radio and checkbox
inputs. Do note however, different types of "text"" inputs can be mixed,
such as url
, email
, text
, etc. If you require a complex form UI
which doesn't fit within the guidelines of an alert then we recommend
building the form within a modal instead.
Usage
constructor(nav: NavController) {
this.nav = nav;
}
presentAlert() {
let alert = Alert.create({
title: 'Low battery',
subTitle: '10% of battery remaining',
buttons: ['Dismiss']
});
this.nav.present(alert);
}
presentConfirm() {
let alert = Alert.create({
title: 'Confirm purchase',
message: 'Do you want to buy this book?',
buttons: [
{
text: 'Cancel',
role: 'cancel',
handler: () => {
console.log('Cancel clicked');
}
},
{
text: 'Buy',
handler: () => {
console.log('Buy clicked');
}
}
]
});
this.nav.present(alert);
}
presentPrompt() {
let alert = Alert.create({
title: 'Login',
inputs: [
{
name: 'username',
placeholder: 'Username'
},
{
name: 'password',
placeholder: 'Password',
type: 'password'
}
],
buttons: [
{
text: 'Cancel',
role: 'cancel',
handler: data => {
console.log('Cancel clicked');
}
},
{
text: 'Login',
handler: data => {
if (User.isValid(data.username, data.password)) {
// logged in!
} else {
// invalid login
return false;
}
}
}
]
});
this.nav.present(alert);
}
Dismissing And Async Navigation
After an alert has been dismissed, the app may need to also transition
to another page depending on the handler's logic. However, because multiple
transitions were fired at roughly the same time, it's difficult for the
nav controller to cleanly animate multiple transitions that may
have been kicked off asynchronously. This is further described in the
Nav Transition Promises
section. For alerts,
this means it's best to wait for the alert to finish its transition
out before starting a new transition on the same nav controller.
In the example below, after the alert button has been clicked, its handler
waits on async operation to complete, then it uses pop
to navigate
back a page in the same stack. The potential problem is that the async operation
may have been completed before the alert has even finished its transition
out. In this case, it's best to ensure the alert has finished its transition
out first, then start the next transition.
let alert = Alert.create({
title: 'Hello',
buttons: [{
text: 'Ok',
handler: () => {
// user has clicked the alert button
// begin the alert's dimiss transition
let navTransition = alert.dismiss();
// start some async method
someAsyncOperation().then(() => {
// once the async operation has completed
// then run the next nav transition after the
// first transition has finished animating out
navTransition.then(() => {
this.nav.pop();
});
});
return false;
}
}]
});
this.nav.present(alert);
It's important to note that the handler returns false
. A feature of
button handlers is that they automatically dismiss the alert when their button
was clicked, however, we'll need more control regarding the transition. Because
the handler returns false
, then the alert does not automatically dismiss
itself. Instead, you now have complete control of when the alert has finished
transitioning, and the ability to wait for the alert to finish transitioning
out before starting a new transition.
Static Members
create(opts)
Alert options
Property | Type | Description |
---|---|---|
title | string |
The string for the alert (optional) |
subTitle | string |
The subtitle for the alert (optional) |
message | string |
The message for the alert (optional) |
cssClass | string |
Any additional class for the alert (optional) |
inputs | array |
An array of inputs for the alert. See input options. (optional) |
buttons | array |
An array of buttons for the alert. See buttons options. (optional) |
enableBackdropDismiss | boolean |
Wheather the alert should be dismissed by tapping the backdrop (optional) |
Input options
Property | Type | Description |
---|---|---|
type | string |
The type the input should be, text, tel, number, etc (optional) |
name | string |
The name for the input (optional) |
placeHolder | string |
The input’s placeholder (optional) |
value | string |
The input’s value (optional) |
label | string |
The input’s label (optional) |
checked | boolean |
Whether or not the input is checked or not (optional) |
id | string |
The input’s id (optional) |
Button options
Property | Type | Description |
---|---|---|
text | string |
The buttons displayed text |
handler | any |
Expression that should be evaluated when the button is pressed |
cssClass | string |
An additional CSS class for the button |
role | string |
The buttons role, null or cancel |
Param | Type | Details |
---|---|---|
opts |
object
|
Alert. See the table above |
Instance Members
setTitle(title)
Param | Type | Details |
---|---|---|
title |
string
|
Alert title |
setSubTitle(subTitle)
Param | Type | Details |
---|---|---|
subTitle |
string
|
Alert subtitle |
setMessage(message)
Param | Type | Details |
---|---|---|
message |
string
|
Alert message content |
addInput(input)
Param | Type | Details |
---|---|---|
input |
object
|
Alert input |
addButton(button)
Param | Type | Details |
---|---|---|
button |
any
|
Alert button |
setCssClass(cssClass)
Param | Type | Details |
---|---|---|
cssClass |
string
|
CSS class name to add to the alert's outer wrapper |