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
Created event
Instanced 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
Events variables

App events

App Mounted event

The app Mounted event is the first one which is fired when 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 Created event

The app Created event is fired when the app internal component is created. This method is only for advanced users! You commonly will use the app Mounted event, for example, to establish some app global reactive variable ready to use along the app. The app Created event allows us, for example, to prepare some JavaScript object for a component (to be used inside an HTML control, for example, placed in some view or dialog) established in the app Instanced event. See below the app Instanced event for more information about this.

App Instanced event

The app Instanced event allows to advanced users to use the instance object of the app. You need more or less knowledge about the Vue framework in order to use this app method appropriately, as well also knowledge of the app JavaScript template (app.js). Inside this app method you can use the "appInstance" JavaScript variable. Using this variable you can configure some aspects of the app, as well, for example, to insert components to be available in all the app views and app dialogs.

Note that if you want to extend the app with new components, a possible better approach is to create your own app plugin: an app plugin allows you, for example, to share the plugin among various apps only by adding that plugin available for them.

To prepare a custom component in the app Instanced event you can start writing your component in the app Instanced event like below:


// This is the app Instance event.

// Define our "myCustomButton" component:
const myCustomButton = {
  props: {
    text: String,
    title: String,
    clickHandler: Function
  },
  data() {
    return {
	  // This is not 100% required, but, allows us to use
	  // the app variable inside our component template.
      app: this.$root
    }
  },
  template: `<button :title="title" @click="clickHandler">{{text}} {{app.name}}</button>`
};

// Use the "appInstance" variable to add your component.
appInstance.component('my-custom-button', myCustomButton);

After your write your component definition in the app Instanced event you can use the app view Created event, the app dialog Created event or even the app Created event, to prepare a Javascript object which instantiantes your component: if you use the app Created event then that component will be available to use in all app views and dialogs, and, if you use the app view Created event or the app dialog Created event, then the component will be only available for that app view or app dialog. You can write in one of the Created events a Javascript object like below:


// This can be placed in an app view Created event,
// an app dialog event or the app Created event.

// Here "this.myCustomButton" refers to a JavaScript
// object of the app view, app dialog or the app itself,
// depending what Created event you are using.

this.myCustomButton = {
  text: 'My custom button!',
  title: 'My custom button!',
  clickHandler(event) {
    let
      self = this,
	  // Accesing internal methods of the app variable (see app.js) is
	  // completely optional and depends on your component needs.
      view = app._getCurrentView(),
      views = app._getLoadedViews(),
      frames = app._getLoadedFrames(),
      dialogs = app._getLoadedDialogs();
    self.event = event;

    alert('Hello from my custom button!');
  }
};

Once you prepare the above stuff, you will be capable to use the "myCustomButton" component in your app view, app dialog or in all of them if you use the app Created event. To use the component you can place the right HTML markup in the HTML property of an HTML control, for example, just like below:


<!-- This HTML markup can be placed in an HTML control, for example -->

<div class="text-center">
 <my-custom-button v-bind="app.myCustomButton"></my-custom-button>
</div>

There is a Instanced sample app included with the installation of the product, so you can take a look at it to see the above working!

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.

Note that you can change the app theme, but also the app ThemeColor property using the app.setAppThemeColor() method.

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 for uncaught errors propagating from within the application. Here in this event you have at your disposition the app Error property which is a JavaScript object with the below properties:

Name	Type	Description
app.error.error	String	The error itself.
app.error.instance	Object	The component instance that triggered the error.
app.error.info	String	An information string specifying the error source type.

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 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.