DecSoft App Builder

App events

The app provide to us several events to be used. We can use this events (like any other app view event, app dialog event or app control event) to perform any task that we need. Below are referred all the available and ready to be use app events.

Mounted event
DomReady event
DeviceReady event
ColorSchemeChange event
SidebarItemClick event
SidebarHeaderClick event
JavascriptError event
RenderError event
Pause event
Resume event

Resize event
Message event
Online event
Offline event
ViewChange event
OrientationChange event
BackButton event
BatteryStatus event
BatteryLow event

BatteryCritical event
VolumeUpButton event
VolumeDownButton event
Click event
DblClick event
SwipeRight event
SwipeLeft event
MouseUp event
MouseDown event

MouseMove event
KeyUp event
KeyDown event
ContextMenu event
WebExtMessage event
WebExtContent event
WebExtBackground event
Events variables

App events

App Mounted event

The app Mounted event is the first one which is fired then the app start. Only the "app" variable is available inside this event, of course with their app properties, app methods and the available app user functions. See also the available events variables.

App DomReady event

The app DomReady event is fired when the main first app view DOM (Document Object Model) is ready to be used. For example, you can change the Text property of a Push button control in a secure way, that is, because the Push button control HTML markup is ready to be use and modified. See also the available events variables.

App DeviceReady event

The app DeviceReady event is only fired if our app has been compiled with Apache Cordova, that is, is intended to run in platforms like Android, Apple iOS or Microsoft Windows. When the app DeviceReady event is fired we can access to the Apache Cordova stuff, as well the Apache Cordova plugins that we want to use. In fact, it's mandatory to wait for the app DeviceReady event in order to access to the referred stuff in a secure way, in other words, we can't access to the Apache Cordova stuff from the app Mounted event, just because that stuff has not been properly initialized yet. See also the available events variables.

App ColorSchemeChange event

The app ColorSchemeChange event is fired when the system color scheme is changed, so you can, for example, change the app's theme, according to the used color scheme. To find what color scheme is configured you can use the getAppColorScheme() app method. See also the available events variables.

App SidebarItemClick event

The app SidebarItemClick event is fired when the user click on an item or subitem of the optional app sidebar. Here in this event you have at your disposition the Sidebar.Item, Sidebar.Item.Index and the Sidebar.Item.Subindex app properties.

App SidebarHeaderClick event

The app SidebarHeaderClick event is fired when the user click on the header of the optional app sidebar. Take a look at the app sidebar options for more information.

App JavascriptError event

The app JavascriptError event is fired when a JavaScript error occurs. If so, in this event the app Error property is filled with the below properties:

Name	Type	Description
app.error.message	String	An error message that must describe the JavaScript error.
app.error.url	String	The URL of the script that causes the JavaScript error.
app.error.lineNumber	String	The line number of the script that causes the JavaScript error.

App RenderError event

The app RenderError event is fired in case of render uncaught errors during component render function and watchers. Here in this event you have at your disposition the app Error property with the below properties:

Name	Type	Description
app.error.message	String	An error message that must describe the Render error.
app.error.vm	Object	The Render component instance wich causes the error.
app.error.info	String	Additional information about the Render error.

App Pause event

The app Pause event is only fired if our app has been compiled with Apache Cordova, that is, is intended to run in platforms like Android, Apple iOS or Microsoft Windows. This event is fired when the app become to the platform "background mode" from the platform "foreground mode". In other words, this event is fired when the app user go to another possible device app or anyway put our app in the background.

We are talking here about the platforms app cycle. Once an app is launched by the user, that app become the foreground app. When the user go to another app or just put the foreground app into the background, the operating system is responsible to maintain this app running or to gracefully close it, to save precious device resources.

The app Pause event is the right place to, for example, save certain app states, for example in the app local storage, in order to recover that saved app state when the app starts again or when the app Resume event is fired. See also the available events variables.

App Resume event

The app Resume event is only fired if our app has been compiled with Apache Cordova, that is, is intended to run in platforms like Android, Apple iOS or Microsoft Windows. This event is fired when the app become to the platform "foreground mode" from the platform "background mode". In other words, this event is fired when the app user back to your app (which has been started before) from another possible device app or anyway put our app in the foreground.

Before the app Resume event is fired, the app Pause event has been already fired in the past. The app Resume event is the right place, for example, to recover a previously saved app state, when the Pause event was fired. See also the available events variables.

App Resize event

The app Resize event is fired when the screen has been resized, for example, because the user resizes the browser window. See also the available events variables.

App Message event

The app Message event is fired when the app window receive a message from other browsing context, for example, from an IFrame control. The "app.event" variable stores a "data" property, which contains the message send from the other browsing context. See also the available events variables.


// This code is suposed to be in the app Message event

window.alert('The app receive this message from the IFrame: ' + app.event.data);

There is a IFrame2 sample app included with the installation of DecSoft App Builder. Take a look to see this app event in action!

App Online event

The app Online event is fired when the app goes online, and the device becomes connected to the Internet. This app event requires the Apache Cordova Network information plugin was included in the app. See also the available events variables.

App Offline event

The app Offline event is fired when the app goes offline, and the device is not connected to the Internet. This app event requires the Apache Cordova Network information plugin was included in the app. See also the available events variables.

App ViewChange event

The app ViewChange event is fired when the app are going to change to another app view, because the user navigates to another app view URL, or because you go to another app view by using the showView() method, for example.

It's possible to prevent the app view change if you return "false" in this app event. You can know the app view that is going to be show by using the app.event.nextViewName property, and, you can know the app view which is going to be leaved by using the app.event.prevViewName property.


// This code is suposed to be in the app ViewChange event

if (!views.view1.switch1.value) {
  alert(
    'The app going from the view ' +
    app.event.prevViewName +
    ' to the view ' +
    app.event.nextViewName +
    ' but the change is not allowed'
  );

  // Disallow the app view change
  return false;
}

There is a ViewChange sample app included with the installation of DecSoft App Builder. Take a look to see this app event in action!

App OrientationChange event

The app OrientationChange event is fired when the screen orientation changes. This app event requires the Apache Screen Orientation plugin was included in the app. See also the available events variables.

App BackButton event

The app BackButton event is fired when the user presses the device's back button (Android and Windows only). See also the available events variables.

App BatteryStatus event

The app BatteryStatus event is fired when the battery charge percentage changes by at least 1 percent, or when the device is plugged in or unplugged. This event requires the Apache Cordova Battery Status to be included in the app. Inside this event you can use the referred plugin app.cordova.battery.level and app.cordova.battery.isPlugged variables.

   
// This code is suposed to be in the app BatteryStatus event   

alert(
  'Battery level STATUS event: ' +
  app.cordova.battery.level +
  ' - Device is plugged: ' +
  app.cordova.battery.isPlugged
);

App BatteryLow event

The app BatteryLow event is fired when the battery charge percentage reaches the low charge threshold. This threshold value is device-specific. This event requires the Apache Cordova Battery Status to be included in the app. Inside this event you can use the referred plugin app.cordova.battery.level and app.cordova.battery.isPlugged variables.

   
// This code is suposed to be in the app BatteryStatus event   

alert(
  'Battery level LOW event: ' +
  app.cordova.battery.level +
  ' - Device is plugged: ' +
  app.cordova.battery.isPlugged
);

App BatteryCritical event

The app BatteryCritical event is fired when the battery charge percentage reaches the critical charge threshold. This threshold value is device-specific. This event requires the Apache Cordova Battery Status to be included in the app. Inside this event you can use the referred plugin app.cordova.battery.level and app.cordova.battery.isPlugged variables.

   
// This code is suposed to be in the app BatteryStatus event   

alert(
  'Battery level CRITICAL event: ' +
  app.cordova.battery.level +
  ' - Device is plugged: ' +
  app.cordova.battery.isPlugged
);

App VolumeUpButton event

The app VolumeUpButton event is fired when the user press the device's volume up button (Android only). See also the available events variables.

App VolumDownpButton event

The app VolumeDownButton event is fired when the user press the device's volume down button (Android only). See also the available events variables.

App KeyUp event

The app KeyUp event is fired when the user release up a key in the keyboard while the app has the focus. You can find information about what key has been pressed, for example, using the Event variable which is available also in this control event. See also the available events variables.

app KeyDown event

The app KeyDown event is fired when the user press a key while the app has the focus. You can find information about what key has been pressed, for example, using the Event variable which is available also in this control event. See also the available events variables.

App Click event

The Click event handler is fired when the user click or tap into the app. See also the available events variables.

App DblClick event

The DblClick (Double Click) event handler is fired when the user double click or double tap into the app. See also the available events variables.

App SwipeRight event

The SwipeRight event handler is fired when the user made the swipe right gesture with the mouse (browsers) or with the finger (devices). See also the available events variables.

App SwipeLeft event

The SwipeLeft event handler is fired when the user made the swipe left gesture with the mouse (browsers) or with the finger (devices). See also the available events variables.

App MouseUp event

The MouseUp event handler is fired when the user up the mouse into the app. See also the available events variables.

App MouseDown event

The MouseDown event handler is fired when the user down the mouse into the app. See also the available events variables.

App MouseMove event

The MouseMove event handler is fired when the user move the mouse into the app. See also the available events variables.

App ContextMenu event

The ContextMenu event handler is fired when the browser must shown the context menu of the the app, which occur when the user click with the right mouse button into the app. See also the available events variables.

App WebExtMessage event

The WebExtMessage app event is fired only if the app is deployed as a Web Extension and after you call to the "window.chrome.runtime.sendMessage(message)" JavaScript method. It's a way to communicate the Web Extension browser's tabs content scripts (which run in the context of the browser's tabs) with our app. Take a look too at the app WebExtContent event.

This event put at your disposition the below variables, which can be accessed "as is", without any prefix:

Name	Type	Description
message	Mixed	This is the message that you send using the "window.chrome.runtime.sendMessage(message)" JavaScript method.

   
// This code is suposed to be in the app WebExtMessage event

if (message === 'color-was-changed') {

  alert('The Web Extension content script inform us the color was successfully changed');
}

Take a look at the How Web Extension works help topic to you can see the Web Extension related stuff in a whole manner.

App WebExtContent event

The WebExtContent app event code is loaded only if the app is deployed as a Web Extension.

This app event code is not "fired" but executed when a browser's tab is loaded. You can't use here any app's stuff like methods or user functions, since the JavaScript code placed here don't run in the app context, but in the browser's tab context.

   

// This JavaScript code is executed in the browser's tabs context. We can't use here any app method
// or app user function, for example, since here that stuff are not available to be used.

// Attach an event handler to receive messages from the app context to this browser's tab content script context
chrome.runtime.onMessage.addListener(function (message, sender, responseFunc) {

  // If we press the app view1 "red button"...

  if (message === 'bg-red') {

    // Change the body of the browser's tab body to red
    $('body').css('background-color', 'red');


  // If we press the app view1 "blue button"....

  } else if (message === 'bg-blue') {

    // Change the body of the browser's tab body to blue
    $('body').css('background-color', 'blue');
  }

  // The below is optional.

  // We can use the chrome.runtime.sendMessage() method in order to
  // communicate with the app context from this browser's tab context.

  // As you can see, after the below code is executed, the app
  // WebExtMessage event is fired, and, receives the message that
  // we send to it from here.

  chrome.runtime.sendMessage('color-was-changed');
});

Take a look at the How Web Extension works help topic to you can see the Web Extension related stuff in a whole manner.

App WebExtBackground event

The WebExtBackground app event code is loaded only if the app is deployed as a Web Extension.

This app event code is not "fired" but executed when the extension is installed and enabled by the user. You can't use here any app's stuff like methods or user functions, since the JavaScript code placed here don't run in the app context, but in the browser's tab context.

This app event code are the place to put code that needs to maintain long-term state, or perform long-term operations, independently of the lifetime of any particular web pages or browser windows.

   

window.setInterval(function () {

  console.log(new Date());
  
}, 1000);

Take a look at the How Web Extension works help topic to you can see the Web Extension related stuff in a whole manner.

App events variables

The below JavaScript variables are available in all the referred App events handlers:

Name	Type	Description
event	Mixed	This variable is received in almost all app events. You can use this variable to stop the propagation of the event, to access the HTML element who fire the event and more.
self	Object	Stores the app object. This is a shortcut to the "app" variable, and it's available since we are talking about specific app events.
view	Object	Stores the current app view or dialog. This variable allow us to access to that view or dialog properties and methods and also their controls properties and methods. For example, you can access to a control properties using the variable "view.yourControlName", suposing the control is named "yourControlName".
views	Object	Stores all the loaded app views. Note that loaded views mean that the app views has been previously show to the user. It's possible to access to the app view controls properties like "views.view1.yourControlName", suposing the view is named "view1" and the control is named "yourControlName". In the same way we can access to other controls of the view and to other loaded views and their controls.
frames	Object	Stores all the app frames. You can use this variable to access to all the app frames and their controls.
dialogs	Object	Stores all the app dialogs. You can use this variable to access to all the app dialogs and their controls.
app	Object	Stores all the app properties and methods. You can use this variable to access to all the app properties and app methods.

Note that the app Mounted event, which is the first one to be fired when the app start, don't provide the above referred variables, except the "app" variable, with their app properties and app methods, and, additionally, the available app user functions.