1 | ---
|
2 | title: Dialogs
|
3 | description: Use native dialog UI elements
|
4 | ---
|
5 |
|
6 | # license: Licensed to the Apache Software Foundation (ASF) under one
|
7 | # or more contributor license agreements. See the NOTICE file
|
8 | # distributed with this work for additional information
|
9 | # regarding copyright ownership. The ASF licenses this file
|
10 | # to you under the Apache License, Version 2.0 (the
|
11 | # "License"); you may not use this file except in compliance
|
12 | # with the License. You may obtain a copy of the License at
|
13 | #
|
14 | # http://www.apache.org/licenses/LICENSE-2.0
|
15 | #
|
16 | # Unless required by applicable law or agreed to in writing,
|
17 | # software distributed under the License is distributed on an
|
18 | # "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
|
19 | # KIND, either express or implied. See the License for the
|
20 | # specific language governing permissions and limitations
|
21 | # under the License.
|
22 | -->
|
23 |
|
24 | |Android|iOS| Windows 8.1 Store | Windows 8.1 Phone | Windows 10 Store | Travis CI |
|
25 | |:-:|:-:|:-:|:-:|:-:|:-:|
|
26 | |[![Build Status](http://cordova-ci.cloudapp.net:8080/buildStatus/icon?job=cordova-periodic-build/PLATFORM=android,PLUGIN=cordova-plugin-dialogs)](http://cordova-ci.cloudapp.net:8080/job/cordova-periodic-build/PLATFORM=android,PLUGIN=cordova-plugin-dialogs/)|[![Build Status](http://cordova-ci.cloudapp.net:8080/buildStatus/icon?job=cordova-periodic-build/PLATFORM=ios,PLUGIN=cordova-plugin-dialogs)](http://cordova-ci.cloudapp.net:8080/job/cordova-periodic-build/PLATFORM=ios,PLUGIN=cordova-plugin-dialogs/)|[![Build Status](http://cordova-ci.cloudapp.net:8080/buildStatus/icon?job=cordova-periodic-build/PLATFORM=windows-8.1-store,PLUGIN=cordova-plugin-dialogs)](http://cordova-ci.cloudapp.net:8080/job/cordova-periodic-build/PLATFORM=windows-8.1-store,PLUGIN=cordova-plugin-dialogs/)|[![Build Status](http://cordova-ci.cloudapp.net:8080/buildStatus/icon?job=cordova-periodic-build/PLATFORM=windows-8.1-phone,PLUGIN=cordova-plugin-dialogs)](http://cordova-ci.cloudapp.net:8080/job/cordova-periodic-build/PLATFORM=windows-8.1-phone,PLUGIN=cordova-plugin-dialogs/)|[![Build Status](http://cordova-ci.cloudapp.net:8080/buildStatus/icon?job=cordova-periodic-build/PLATFORM=windows-10-store,PLUGIN=cordova-plugin-dialogs)](http://cordova-ci.cloudapp.net:8080/job/cordova-periodic-build/PLATFORM=windows-10-store,PLUGIN=cordova-plugin-dialogs/)|[![Build Status](https://travis-ci.org/apache/cordova-plugin-dialogs.svg?branch=master)](https://travis-ci.org/apache/cordova-plugin-dialogs)|
|
27 |
|
28 | # cordova-plugin-dialogs
|
29 |
|
30 | This plugin provides access to some native dialog UI elements
|
31 | via a global `navigator.notification` object.
|
32 |
|
33 | Although the object is attached to the global scoped `navigator`, it is not available until after the `deviceready` event.
|
34 |
|
35 | document.addEventListener("deviceready", onDeviceReady, false);
|
36 | function onDeviceReady() {
|
37 | console.log(navigator.notification);
|
38 | }
|
39 |
|
40 | Report issues on the [Apache Cordova issue tracker](https://issues.apache.org/jira/issues/?jql=project%20%3D%20CB%20AND%20status%20in%20%28Open%2C%20%22In%20Progress%22%2C%20Reopened%29%20AND%20resolution%20%3D%20Unresolved%20AND%20component%20%3D%20%22Plugin%20Dialogs%22%20ORDER%20BY%20priority%20DESC%2C%20summary%20ASC%2C%20updatedDate%20DESC)
|
41 |
|
42 | ## Installation
|
43 |
|
44 | cordova plugin add cordova-plugin-dialogs
|
45 |
|
46 | ## Methods
|
47 |
|
48 | - `navigator.notification.alert`
|
49 | - `navigator.notification.confirm`
|
50 | - `navigator.notification.prompt`
|
51 | - `navigator.notification.beep`
|
52 |
|
53 | ## navigator.notification.alert
|
54 |
|
55 | Shows a custom alert or dialog box. Most Cordova implementations use a native
|
56 | dialog box for this feature, but some platforms use the browser's `alert`
|
57 | function, which is typically less customizable.
|
58 |
|
59 | navigator.notification.alert(message, alertCallback, [title], [buttonName])
|
60 |
|
61 | - __message__: Dialog message. _(String)_
|
62 |
|
63 | - __alertCallback__: Callback to invoke when alert dialog is dismissed. _(Function)_
|
64 |
|
65 | - __title__: Dialog title. _(String)_ (Optional, defaults to `Alert`)
|
66 |
|
67 | - __buttonName__: Button name. _(String)_ (Optional, defaults to `OK`)
|
68 |
|
69 |
|
70 | ### Example
|
71 |
|
72 | function alertDismissed() {
|
73 | // do something
|
74 | }
|
75 |
|
76 | navigator.notification.alert(
|
77 | 'You are the winner!', // message
|
78 | alertDismissed, // callback
|
79 | 'Game Over', // title
|
80 | 'Done' // buttonName
|
81 | );
|
82 |
|
83 | ### Supported Platforms
|
84 |
|
85 | - Amazon Fire OS
|
86 | - Android
|
87 | - BlackBerry 10
|
88 | - Browser
|
89 | - Firefox OS
|
90 | - iOS
|
91 | - Tizen
|
92 | - Windows Phone 7 and 8
|
93 | - Windows 8
|
94 | - Windows
|
95 |
|
96 | ### Windows Phone 7 and 8 Quirks
|
97 |
|
98 | - There is no built-in browser alert, but you can bind one as follows to call `alert()` in the global scope:
|
99 |
|
100 | window.alert = navigator.notification.alert;
|
101 |
|
102 | - Both `alert` and `confirm` are non-blocking calls, results of which are only available asynchronously.
|
103 |
|
104 | ### Firefox OS Quirks:
|
105 |
|
106 | Both native-blocking `window.alert()` and non-blocking `navigator.notification.alert()` are available.
|
107 |
|
108 | ### BlackBerry 10 Quirks
|
109 | `navigator.notification.alert('text', callback, 'title', 'text')` callback parameter is passed the number 1.
|
110 |
|
111 | ## navigator.notification.confirm
|
112 |
|
113 | Displays a customizable confirmation dialog box.
|
114 |
|
115 | navigator.notification.confirm(message, confirmCallback, [title], [buttonLabels])
|
116 |
|
117 | - __message__: Dialog message. _(String)_
|
118 |
|
119 | - __confirmCallback__: Callback to invoke with index of button pressed (1, 2, or 3) or when the dialog is dismissed without a button press (0). _(Function)_
|
120 |
|
121 | - __title__: Dialog title. _(String)_ (Optional, defaults to `Confirm`)
|
122 |
|
123 | - __buttonLabels__: Array of strings specifying button labels. _(Array)_ (Optional, defaults to [`OK,Cancel`])
|
124 |
|
125 |
|
126 | ### confirmCallback
|
127 |
|
128 | The `confirmCallback` executes when the user presses one of the
|
129 | buttons in the confirmation dialog box.
|
130 |
|
131 | The callback takes the argument `buttonIndex` _(Number)_, which is the
|
132 | index of the pressed button. Note that the index uses one-based
|
133 | indexing, so the value is `1`, `2`, `3`, etc.
|
134 |
|
135 | ### Example
|
136 |
|
137 | function onConfirm(buttonIndex) {
|
138 | alert('You selected button ' + buttonIndex);
|
139 | }
|
140 |
|
141 | navigator.notification.confirm(
|
142 | 'You are the winner!', // message
|
143 | onConfirm, // callback to invoke with index of button pressed
|
144 | 'Game Over', // title
|
145 | ['Restart','Exit'] // buttonLabels
|
146 | );
|
147 |
|
148 | ### Supported Platforms
|
149 |
|
150 | - Amazon Fire OS
|
151 | - Android
|
152 | - BlackBerry 10
|
153 | - Browser
|
154 | - Firefox OS
|
155 | - iOS
|
156 | - Tizen
|
157 | - Windows Phone 7 and 8
|
158 | - Windows 8
|
159 | - Windows
|
160 |
|
161 | ### Windows Phone 7 and 8 Quirks
|
162 |
|
163 | - There is no built-in browser function for `window.confirm`, but you can bind it by assigning:
|
164 |
|
165 | window.confirm = navigator.notification.confirm;
|
166 |
|
167 | - Calls to `alert` and `confirm` are non-blocking, so the result is only available asynchronously.
|
168 |
|
169 | ### Windows Quirks
|
170 |
|
171 | - On Windows8/8.1 it is not possible to add more than three buttons to MessageDialog instance.
|
172 |
|
173 | - On Windows Phone 8.1 it's not possible to show dialog with more than two buttons.
|
174 |
|
175 | ### Firefox OS Quirks:
|
176 |
|
177 | Both native-blocking `window.confirm()` and non-blocking `navigator.notification.confirm()` are available.
|
178 |
|
179 | ## navigator.notification.prompt
|
180 |
|
181 | Displays a native dialog box that is more customizable than the browser's `prompt` function.
|
182 |
|
183 | navigator.notification.prompt(message, promptCallback, [title], [buttonLabels], [defaultText])
|
184 |
|
185 | - __message__: Dialog message. _(String)_
|
186 |
|
187 | - __promptCallback__: Callback to invoke with index of button pressed (1, 2, or 3) or when the dialog is dismissed without a button press (0). _(Function)_
|
188 |
|
189 | - __title__: Dialog title _(String)_ (Optional, defaults to `Prompt`)
|
190 |
|
191 | - __buttonLabels__: Array of strings specifying button labels _(Array)_ (Optional, defaults to `["OK","Cancel"]`)
|
192 |
|
193 | - __defaultText__: Default textbox input value (`String`) (Optional, Default: empty string)
|
194 |
|
195 | ### promptCallback
|
196 |
|
197 | The `promptCallback` executes when the user presses one of the buttons
|
198 | in the prompt dialog box. The `results` object passed to the callback
|
199 | contains the following properties:
|
200 |
|
201 | - __buttonIndex__: The index of the pressed button. _(Number)_ Note that the index uses one-based indexing, so the value is `1`, `2`, `3`, etc.
|
202 |
|
203 |
|
204 |
|
205 | - __input1__: The text entered in the prompt dialog box. _(String)_
|
206 |
|
207 | ### Example
|
208 |
|
209 | function onPrompt(results) {
|
210 | alert("You selected button number " + results.buttonIndex + " and entered " + results.input1);
|
211 | }
|
212 |
|
213 | navigator.notification.prompt(
|
214 | 'Please enter your name', // message
|
215 | onPrompt, // callback to invoke
|
216 | 'Registration', // title
|
217 | ['Ok','Exit'], // buttonLabels
|
218 | 'Jane Doe' // defaultText
|
219 | );
|
220 |
|
221 | ### Supported Platforms
|
222 |
|
223 | - Amazon Fire OS
|
224 | - Android
|
225 | - Browser
|
226 | - Firefox OS
|
227 | - iOS
|
228 | - Windows Phone 7 and 8
|
229 | - Windows 8
|
230 | - Windows
|
231 |
|
232 | ### Android Quirks
|
233 |
|
234 | - Android supports a maximum of three buttons, and ignores any more than that.
|
235 |
|
236 | - On Android 3.0 and later, buttons are displayed in reverse order for devices that use the Holo theme.
|
237 |
|
238 | ### Windows Quirks
|
239 |
|
240 | - On Windows prompt dialog is html-based due to lack of such native api.
|
241 |
|
242 | ### Firefox OS Quirks:
|
243 |
|
244 | Both native-blocking `window.prompt()` and non-blocking `navigator.notification.prompt()` are available.
|
245 |
|
246 | ## navigator.notification.beep
|
247 |
|
248 | The device plays a beep sound.
|
249 |
|
250 | navigator.notification.beep(times);
|
251 |
|
252 | - __times__: The number of times to repeat the beep. _(Number)_
|
253 |
|
254 | ### Example
|
255 |
|
256 | // Beep twice!
|
257 | navigator.notification.beep(2);
|
258 |
|
259 | ### Supported Platforms
|
260 |
|
261 | - Amazon Fire OS
|
262 | - Android
|
263 | - BlackBerry 10
|
264 | - Browser
|
265 | - iOS
|
266 | - Tizen
|
267 | - Windows Phone 7 and 8
|
268 | - Windows 8
|
269 |
|
270 | ### Amazon Fire OS Quirks
|
271 |
|
272 | - Amazon Fire OS plays the default __Notification Sound__ specified under the __Settings/Display & Sound__ panel.
|
273 |
|
274 | ### Android Quirks
|
275 |
|
276 | - Android plays the default __Notification ringtone__ specified under the __Settings/Sound & Display__ panel.
|
277 |
|
278 | ### Windows Phone 7 and 8 Quirks
|
279 |
|
280 | - Relies on a generic beep file from the Cordova distribution.
|
281 |
|
282 | ### Tizen Quirks
|
283 |
|
284 | - Tizen implements beeps by playing an audio file via the media API.
|
285 |
|
286 | - The beep file must be short, must be located in a `sounds` subdirectory of the application's root directory, and must be named `beep.wav`.
|