[
https://issues.apache.org/jira/browse/CB-10351?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=15130895#comment-15130895
]
ASF GitHub Bot commented on CB-10351:
-------------------------------------
Github user nikhilkh commented on a diff in the pull request:
https://github.com/apache/cordova-docs/pull/480#discussion_r51769377
--- Diff: www/docs/en/dev/cordova/events/events.md ---
@@ -22,29 +22,384 @@ title: Events
# Events
-> Cordova lifecycle events.
+There are various events provided by cordova to be used by the
application.
+The application code could add listeners for these events. For example:
-## Event Types
+**HTML File**
-- [deviceready](events.deviceready.html)
-- [pause](events.pause.html)
-- [resume](events.resume.html)
-- [backbutton](events.backbutton.html)
-- [menubutton](events.menubutton.html)
-- [searchbutton](events.searchbutton.html)
-- [startcallbutton](events.startcallbutton.html)
-- [endcallbutton](events.endcallbutton.html)
-- [volumedownbutton](events.volumedownbutton.html)
-- [volumeupbutton](events.volumeupbutton.html)
+ <!DOCTYPE html>
+ <html>
+ <head>
+ <title>Device Ready Example</title>
-## Events added by
[cordova-plugin-battery-status](https://github.com/apache/cordova-plugin-battery-status/blob/master/README.md)
+ <script type="text/javascript" charset="utf-8"
src="cordova.js"></script>
+ <script type="text/javascript" charset="utf-8"
src="example.js"></script>
+ </head>
+ <body onload="onLoad()">
+ </body>
+ </html>
-- batterycritical
-- batterylow
-- batterystatus
+**JS File**
-## Events added by
[cordova-plugin-network-information](https://github.com/apache/cordova-plugin-network-information/blob/master/README.md)
+ // example.js file
+ // Wait for device API libraries to load
+ //
+ function onLoad() {
+ document.addEventListener("deviceready", onDeviceReady, false);
+ }
-- online
-- offline
+ // device APIs are available
+ //
+ function onDeviceReady() {
+ document.addEventListener("pause", onPause, false);
+ document.addEventListener("resume", onResume, false);
+ document.addEventListener("menubutton", onMenuKeyDown, false);
+ // Add similar listeners for other events
+ }
+ function onPause() {
+ // Handle the pause event
+ }
+
+ function onResume() {
+ // Handle the resume event
+ }
+
+ function onMenuKeyDown() {
+ // Handle the menubutton event
+ }
+
+ // Add similar event handlers for other events
+
+**Note**: Applications typically should use `document.addEventListener` to
+attach an event listener once the [deviceready](#link-deviceready)
+event fires.
+
+The following table lists the cordova events and the supported platforms:
+
+<!-- START HTML -->
+
+<table class="compat" width="100%">
+
+<thead>
+ <tr>
+ <th>Supported Platforms/<br/>Events</td>
+ <th>amazon-fireos</th>
+ <th>android</th>
+ <th>blackberry10</th>
+ <th>ios</th>
+ <th>Windows Phone 8</th>
+ <th>Windows</th>
+ </tr>
+</thead>
+
+<tbody>
+ <tr>
+ <th><a href="#link-deviceready">deviceready</a></th>
+ <td data-col="amazon-fireos" class="y"></td>
+ <td data-col="android" class="y"></td>
+ <td data-col="blackberry10" class="y"></td>
+ <td data-col="ios" class="y"></td>
+ <td data-col="winphone8" class="y"></td>
+ <td data-col="win" class="y"></td>
+ </tr>
+
+ <tr>
+ <th><a href="#link-pause">pause</a></th>
+ <td data-col="amazon-fireos" class="y"></td>
+ <td data-col="android" class="y"></td>
+ <td data-col="blackberry10" class="y"></td>
+ <td data-col="ios" class="y"></td>
+ <td data-col="winphone8" class="y"></td>
+ <td data-col="win" class="y"></td>
+ </tr>
+
+ <tr>
+ <th><a href="#link-resume">resume</a></th>
+ <td data-col="amazon-fireos" class="y"></td>
+ <td data-col="android" class="y"></td>
+ <td data-col="blackberry10" class="y"></td>
+ <td data-col="ios" class="y"></td>
+ <td data-col="winphone8" class="y"></td>
+ <td data-col="win" class="y"></td>
+ </tr>
+
+ <tr>
+ <th><a href="#link-backbutton">backbutton</a></th>
+ <td data-col="amazon-fireos" class="y"></td>
+ <td data-col="android" class="y"></td>
+ <td data-col="blackberry10" class="y"></td>
+ <td data-col="ios" class="n"></td>
+ <td data-col="winphone8" class="n"></td>
+ <td data-col="win" class="y"></td>
+ </tr>
+
+ <tr>
+ <th><a href="#link-menubutton">menubutton</a></th>
+ <td data-col="amazon-fireos" class="y"></td>
+ <td data-col="android" class="y"></td>
+ <td data-col="blackberry10" class="y"></td>
+ <td data-col="ios" class="n"></td>
+ <td data-col="winphone8" class="n"></td>
+ <td data-col="win" class="n"></td>
+ </tr>
+
+ <tr>
+ <th><a href="#link-searchbutton">searchbutton</a></th>
+ <td data-col="amazon-fireos" class="n"></td>
+ <td data-col="android" class="y"></td>
+ <td data-col="blackberry10" class="n"></td>
+ <td data-col="ios" class="n"></td>
+ <td data-col="winphone8" class="n"></td>
+ <td data-col="win" class="n"></td>
+ </tr>
+
+ <tr>
+ <th><a href="#link-startcallbutton">startcallbutton</a></th>
+ <td data-col="amazon-fireos" class="n"></td>
+ <td data-col="android" class="n"></td>
+ <td data-col="blackberry10" class="y"></td>
+ <td data-col="ios" class="n"></td>
+ <td data-col="winphone8" class="n"></td>
+ <td data-col="win" class="n"></td>
+ </tr>
+
+ <tr>
+ <th><a href="#link-endcallbutton">endcallbutton</a></th>
+ <td data-col="amazon-fireos" class="n"></td>
+ <td data-col="android" class="n"></td>
+ <td data-col="blackberry10" class="y"></td>
+ <td data-col="ios" class="n"></td>
+ <td data-col="winphone8" class="n"></td>
+ <td data-col="win" class="n"></td>
+ </tr>
+
+ <tr>
+ <th><a href="#link-volumedownbutton">volumedownbutton</a></th>
+ <td data-col="amazon-fireos" class="n"></td>
+ <td data-col="android" class="y"></td>
+ <td data-col="blackberry10" class="y"></td>
+ <td data-col="ios" class="n"></td>
+ <td data-col="winphone8" class="n"></td>
+ <td data-col="win" class="n"></td>
+ </tr>
+
+ <tr>
+ <th><a href="#link-volumeupbutton">volumeupbutton</a></th>
+ <td data-col="amazon-fireos" class="n"></td>
+ <td data-col="android" class="y"></td>
+ <td data-col="blackberry10" class="y"></td>
+ <td data-col="ios" class="n"></td>
+ <td data-col="winphone8" class="n"></td>
+ <td data-col="win" class="n"></td>
+ </tr>
+</tbody>
+</table>
+
+<!-- END HTML -->
+
+
+## deviceready
+
+The deviceready event fires when Cordova is fully loaded. This event is
+essential to any application. It signals that Cordova's device APIs have
+loaded and are ready to access.
+
+Cordova consists of two code bases: native and JavaScript. While the
+native code loads, a custom loading image displays. However,
+JavaScript only loads once the DOM loads. This means the web app may
+potentially call a Cordova JavaScript function before the
+corresponding native code becomes available.
+
+The `deviceready` event fires once Cordova has fully loaded. Once the
+event fires, you can safely make calls to Cordova APIs. Applications
+typically attach an event listener with `document.addEventListener`
+once the HTML document's DOM has loaded.
+
+The `deviceready` event behaves somewhat differently from others. Any
+event handler registered after the `deviceready` event fires has its
+callback function called immediately.
+
+### Quick Example
+
+ document.addEventListener("deviceready", onDeviceReady, false);
+
+ function onDeviceReady() {
+ // Now safe to use device APIs
+ }
+
+## pause
+
+The pause event fires when the native platform puts the application into
the background,
+typically when the user switches to a different application.
+
+### Quick Example
+
+ document.addEventListener("pause", onPause, false);
+
+ function onPause() {
+ // Handle the pause event
+ }
+
+### iOS Quirks
+
+In the `pause` handler, any calls to the Cordova API or to native
+plugins that go through Objective-C do not work, along with any
+interactive calls, such as alerts or `console.log()`. They are only
+processed when the app resumes, on the next run loop.
+
+The iOS-specific `resign` event is available as an alternative to
+`pause`, and detects when users enable the __Lock__ button to lock the
+device with the app running in the foreground. If the app (and
+device) is enabled for multi-tasking, this is paired with a subsequent
+`pause` event, but only under iOS 5. In effect, all locked apps in iOS
+5 that have multi-tasking enabled are pushed to the background. For
+apps to remain running when locked under iOS 5, disable the app's
+multi-tasking by setting
[UIApplicationExitsOnSuspend][UIApplicationExitsOnSuspend]
+to `YES`. To run when locked on iOS 4, this setting does not matter.
+
+## resume
+
+The `resume` event fires when the native platform pulls the application
out from the background.
+
+### Quick Example
+
+ document.addEventListener("resume", onResume, false);
+
+ function onResume() {
+ // Handle the resume event
+ }
+
+### iOS Quirks
+
+Any interactive functions called from a [pause](#link-pause) event handler
execute
+later when the app resumes, as signaled by the `resume` event. These
+include alerts, `console.log()`, and any calls from plugins or the
+Cordova API, which go through Objective-C.
+
+- __active__ event
+
+ The iOS-specific `active` event is available as an alternative to
+`resume`, and detects when users disable the __Lock__ button to unlock
+the device with the app running in the foreground. If the app (and
+device) is enabled for multi-tasking, this is paired with a subsequent
+`resume` event, but only under iOS 5. In effect, all locked apps in
+iOS 5 that have multi-tasking enabled are pushed to the background.
+For apps to remain running when locked under iOS 5, disable the app's
+multi-tasking by setting
[UIApplicationExitsOnSuspend][UIApplicationExitsOnSuspend]
+to `YES`. To run when locked on iOS 4, this setting does not matter.
+
+- __resume__ event
+
+ When called from a `resume` event handler, interactive functions such
+as `alert()` need to be wrapped in a `setTimeout()` call with a
+timeout value of zero, or else the app hangs. For example:
+
+ document.addEventListener("resume", onResume, false);
+ function onResume() {
+ setTimeout(function() {
+ // TODO: do your thing!
+ }, 0);
+ }
+
+### Android Quirks
+
+Refer [Android Life Cycle Guide][AndroidLifeCycleGuide] for details on
android quirks with
+the `resume` event.
+
+## backbutton
+
+The event fires when the user presses the back button. To override the
default
+back-button behavior, register an event listener for the `backbutton`
event.
+It is no longer necessary to call any other method to override the
+back-button behavior.
+
+### Quick Example
+
+ document.addEventListener("backbutton", onBackKeyDown, false);
+
+ function onBackKeyDown() {
+ // Handle the back button
+ }
+
+## menubutton
+
+The event fires when the user presses the menu button. Applying an event
handler
+overrides the default menu button behavior.
+
+### Quick Example
+
+ document.addEventListener("menubutton", onMenuKeyDown, false);
+
+ function onMenuKeyDown() {
+ // Handle the back button
+ }
+
+## searchbutton
+
+The event fires when the user presses the search button on Android. If you
need to
+override the default search button behavior on Android you can register an
event
+listener for the 'searchbutton' event.
+
+### Quick Example
+
+ document.addEventListener("searchbutton", onSearchKeyDown, false);
+
+ function onSearchKeyDown() {
+ // Handle the search button
+ }
+
+## startcallbutton
+
+The event fires when the user presses the start call button. If you need
to override
+the default start call behavior you can register an event listener for the
`startcallbutton` event.
+
+### Quick Example
+
+ document.addEventListener("startcallbutton", onStartCallKeyDown,
false);
+
+ function onStartCallKeyDown() {
+ // Handle the start call button
+ }
+
+## endcallbutton
+
+This event fires when the user presses the end call button. The event
overrides the
+default end call behavior.
+
+### Quick Example
+
+ document.addEventListener("endcallbutton", onEndCallKeyDown, false);
+
+ function onEndCallKeyDown() {
+ // Handle the end call button
+ }
+
+## volumedownbutton
+
+The event fires when the user presses the volume down button. If you need
to override
+the default volume down behavior you can register an event listener for
the `volumedownbutton` event.
+
+### Quick Example
+
+ document.addEventListener("volumedownbutton", onVolumeDownKeyDown,
false);
+
+ function onVolumeDownKeyDown() {
+ // Handle the volume down button
+ }
+
+## volumeupbutton
+
+The event fires when the user presses the volume up button. If you need to
override
+the default volume up behavior you can register an event listener for the
`volumeupbutton` event.
+
+### Quick Example
+
+ document.addEventListener("volumeupbutton", onVolumeUpKeyDown, false);
+
+ function onVolumeUpKeyDown() {
+ // Handle the volume up button
+ }
+
+[UIApplicationExitsOnSuspend]:
http://developer.apple.com/library/ios/#documentation/general/Reference/InfoPlistKeyReference/Articles/iPhoneOSKeys.html
+[AndroidLifeCycleGuide]: {{ site.baseurl
}}/docs/en/dev/guide/platforms/android/lifecycle.html
--- End diff --
Should this be a relative reference instead?
> Make Events page a reference
> ----------------------------
>
> Key: CB-10351
> URL: https://issues.apache.org/jira/browse/CB-10351
> Project: Apache Cordova
> Issue Type: Task
> Components: Docs
> Reporter: Raghav
> Assignee: Sarangan Rajamanickam
> Labels: Docs-6.x
>
> Events page
> (https://cordova.apache.org/docs/en/latest/cordova/events/events.html) needs
> to be converted as per the new reference structure. Also add small
> descriptions to the events added by plugin-battery-status and
> plugin-network-information.
> General guidelines:
> - While giving examples, keep them short. Do not repeat for all
> plugins/platforms.
> - Remove all references to cordova plugin registry.
> - Remove Tizen references. The platform is deprecated
> (http://markmail.org/message/hryg6sjswecpgndu)
> - Keep information up to date for the platforms, CLI and plugins
--
This message was sent by Atlassian JIRA
(v6.3.4#6332)
---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]
