App Builder

Index of ContentsApp events

Every app have some useful events which you can use to, for example, control the lifecycle of your apps in platforms like Android™. This help section describe every event of an app. For events that are available in app views goto the App views help. For events that are available in specific app view controls goto the App controls help. You can use these events to place app actions in order to make whatever you need when the event is fired.

Almost all app view events provide us with the appropiate "Event" variable, which contain information about the fired event.

App events

App Ready event

This event is fired when the app HTML DOM is completely loaded if your app run in a web browser. If you run the app compiled with Apache Cordova, this event is fired when the Cordova API is available and ready to use.

This event is the first event executed when the app is launched, before any other event like the app view Show event.
This event is supported in: Amazon Fire OS, Android, BlackBerry 10, iOS, Tizen, Windows Phone 8, Windows 8 and web browsers.

App Pause event

This event is fired when the app enter in background, typically when the user switches to a different app. You can use this event and the app Resume event to control the life cycle of our app, for example, by save certain app state when the app enter in the background, and load the saved state when the app become into foreground.

This event is supported in: Amazon Fire OS, Android, BlackBerry 10, iOS, Windows Phone 8 and Windows 8.
This event is not supported and therefore not fired if your app is running on a web browser.

App Resume event

This event is fired when the app enter in foreground, typically when the user switches from another to your app. You can use this event and the app Pause event to control the life cycle of our app, for example, by load certain app state when the app enter in the background, and load the saved state when the app become into foreground.

This event is supported in: Amazon Fire OS, Android, BlackBerry 10, iOS, Windows Phone 8 and Windows 8.
This event is not supported and therefore not fired if your app is running on a web browser.

App Hide event

This event is fired when our application browser's tab is hidden or minimized, that is, when our application lost the user focus. This event can be useful, for example, to stop a video if the application is hidden.

This event is supported in all modern desktop and mobile browsers.

App Show event

This event is fired when our application browser's tab is shown or restored, if previously has been hidden or minimized, that is, when our application get again the user focus. This event can be useful, for example, to continue a video reproduction if the application is shown again.

This event is supported in all modern desktop and mobile browsers.

App ViewChange event

This event is fired when an app's view must be changed, that is, for example, just after we call to actions like ShowView and ReplaceView.

Once this event is fired we can take a look at the app's global variables [App.CurrentView] and [App.NextView]. The first one store the current app's view, and, the second one stores the app's view we must to go. We can prevent the default behaviour of this event using the PreventDefault action along with the [App.Event] variable, that is, we can prevent the view's change. Take a look at the "ViewChange" app sample included in the App Builder installation.

App Error event

This event is fired when an app Javascript error occur. Take a look at the [App.LastError] global variable too.

App Resize event

This event is fired when the app device screen is resized.

This event is supported and therefore fired if your app is running on a web browser.

App Orientation event

This event is fired when the app device screen orientation is changed to portrait from landscape or viceversa.

This event may supported by all platforms in which the portrait and landscape orientation change can occur.

App Online event

This event is fired when the app switch from an offline to an online state. Note this event works in an Apache Cordova build application only if the Network plugin is included by the application.

Take a look at the app Offline event and also at the [App.Online] global variable.

App Offline event

This event is fired when the app switch from an online to an offline state. Note this event works in an Apache Cordova build application only if the Network plugin is included by the application.

Take a look at the app Online event and also at the [App.Online] global variable.

App IdleStart event

This event is fired when the idle time established by the IdleStart action is reached.

App IdleEnd event

This event is fired when the user do something over the app (click, touch, mouse move, etc.) after the app become idling.

App BackButton event

This event is fired when the user press the back button of their device. Note this event override the default behaviour of the device back button.

This event is supported in: Amazon Fire OS, Android, BlackBerry 10 and Windows Phone 8.
This event is not supported and therefore not fired if your app is running on a web browser.

App VolumeUp event

This event is fired when the user press the volume up button of their device.

This event is supported in: Android, BlackBerry 10.
This event is not supported and therefore not fired if your app is running on a web browser.

App VolumeDown event

This event is fired when the user press the volume down button of their device.

This event is supported in: Android, BlackBerry 10.
This event is not supported and therefore not fired if your app is running on a web browser.

App KeyUp event

This event is fired when the user press up a key. The [App.Event] global variable store the key event, so, for example, we can access the pressed key code like: [App.Event.keyCode].

This event is intented primary to be used for desktop browsers.

App KeyDown event

This event is fired when the user press down a key. The [App.Event] global variable store the key event, so, for example, we can access the pressed key code like: [App.Event.keyCode].

This event is intented primary to be used for desktop browsers.

App WebExtMessage event

This event can be fired only if our applications is deployed as a WebExtension for modern browsers. This event is initialy a way to communicate our WebExtension app views with the WebExtension Content script, that is, the code we write inside the WebExtContent event. See this last event for more details.

See the WebExtension app sample in order to take a look at how works the related events and this event in particular.

App WebExtContent event

This is a bit particular app event. In the first place, this event is only fired if our application is deployed as a WebExtension for modern browsers. This event is fired after we call to the WebExtSendMessage action.

The code of this event must be Javascript (we can use the jQuery Javascript library inside this event code, since App Builder includes it for us) and we can't use App Builder actions nor access to our app variables or other stuff. So what's the point of this event then?

The point of this event is they are executed in the context of the current browser's page. So, the scenario can be something like the below one:

  1. We want to change the background color for all the current browser's page paragraphs.
  2. Then we call to the WebExtSendMessage action and pass a message like "paragraphs-in-red", for example.
  3. This event receive such message and therefore proceed to change the current browser's page paragraphs background.

Important: Inside the code of this event we have the "message" Javascript variable (case sensitive), which contains the message send by us before using the WebExtSendMessage action. So, for example, supose we call to this action in the below way:

WebExtSendMessage "paragraphs-in-red" ""

Then, inside this event code we can write something like the below one:

if (message == 'paragraphs-in-red') {
  $('p').css('background-color', 'red');
} else {
  window.chrome.runtime.sendMessage(message);
}

Let me to explain a little the above code. As you can see we use the "message" Javascript variable, already available inside this event. Since we know the "message" variable is an string (we send an string before using the WebExtSendMessage action) we look for that string and looks if they are "paragraphs-in-red".

If the message is certainly "paragraphs-in-red" we know what to do: change all the current browser's page paragraphs background color to the red color. So we proceed to it using the power of the jQuery Javascript library, already available for us inside this event.

Finally note the usage of the "window.chrome.runtime.sendMessage" method. This is completely optional and can be used to communicate with our application from this event code. After we call to this method the app WebExtMessage event is fired and receive the message we send stored in the [App.WebExtMessage] app global variable.

See the WebExtension app sample in order to take a look at how works the related events and this event in particular.