If you find any errors, typos or have general feedback, select the text and click CTRL+ALT+ENTER.

Introduction

When building a mobile web app, almost everything that happens in your app is based around events. For example, clicking a button is a click event, and based on this event, you can navigate to another page or invoke some JavaScript, among many other options.

Another example; when you change a value inside an input field, that’s a value change event. And again, once the event fires, you can pretty much go wherever you want from there.

All events are browser events, not Appery.io events. There are also PhoneGap events, which are native device events.

To see the events added to a component, open the Events tab:
001-Events

If you select a component and then open Events, only events for that particular component will be shown. To see events/actions defined for another component, select it from the Component drop-down list. To see all events defined on this page, click Show All on the right-hand side.

Event types

The events are divided into several categories: HTML (these should be familiar to most of you), jQuery Mobile, Service, Carousel component, PhoneGap (device) and Push notifications events.

HTML events

  • Before unload – fires when the page is about to be unloaded. When adding this event, you have the ability to display a confirmation dialog, where the user can confirm whether he/she wants to stay or leave the current page.
  • Blur – fires when an element loses focus. This event is the opposite of the Focus event.
  • Click – fires when the user clicks on an element.
  • Contextmenu – fires when the user calls the context menu by right-clicking. It allows you to disable the context menu.
  • Double click – fires when the user double-clicks on an element.
  • Drag – fires during a drag and drop operation.

    Only Drag events are fired; mouse events, such as mousemove are not fired during a drag operation.

  • Drag end – fires when the drag operation is complete, whether it was successful or not.
  • Drag enter – fires when the mouse is first moved over an element while a drag is occurring.
  • Drag leave – fires when the mouse leaves an element while a drag is occurring.
  • Drag over – fires as the mouse is moved over an element when a drag is occurring.
  • Drag start – fires when a drag is started.
  • Drop – fires on the element where the drop occurred at the end of the drag operation. This event is fired only if a drop is desired. It will not fire if the user cancelled the drag operation.
  • Error – fires if the page was not loaded correctly.
  • Focus – fires when an element gets focus. This event is opposite to the blur event.
  • Form change – fires when the user makes any changes in the form. For select checkboxes and radio buttons, the event is fired immediately when the user makes a selection with the mouse, but for the other element types, the event is deferred until the element loses focus.
  • Form input – fires when an element receives user input.
  • History changes – fires when the history changes; that is, the list of actions to undo or redo is changed. The event is triggered when the user navigates between two history entries for the same document.
  • Input – fires when an element gets user input.
  • Invalid value – fires when an element gets an invalid value.
  • Keydown – fires when the user is pressing a key (on the keyboard).
  • Keypress – fires when the user presses a key (on the keyboard).
  • Keyup – fires when the user releases a key (on the keyboard).
  • Message – fires when a message is received.
  • Message is triggered – fires when the message is triggered.
  • Mouse down – fires when a user presses a mouse button over an element.
  • Mouse move – fires when the pointer is moving while it is over an element.
  • Mouse out – fires when a user moves the mouse pointer out of an element.
  • Mouse over – fires when the pointer is moved on to an element.
  • Mouse up – fires when a user releases a mouse button over an element.
  • Mouse wheel – fires when the mouse wheel is being rotated.
  • Offline – fires when the app switches into offline mode.
  • Online – fires when the app switches into online mode.
  • Resize – fires when the size of the page is changed.
  • Scroll – fires when the user scrolls to a different place in the element.
  • Selected – fires after text has been selected in an element.
  • Submit – fires when the user is attempting to submit a form. Different events may cause form submission (e.g., clicking the Enter key or the Submit button), that’s why it is better to bind the app behavior with specific events.
  • Unload – fires when the user navigates away from the page (by clicking a link, navigating to another page, closing the application, etc.).
  • Value change – is sent to an element when its value changes. For select checkboxes and radio buttons, the event is fired immediately when the user makes a selection with the mouse, but for the other element types, the event is deferred until the element loses focus.

You can find all the standard HTML events here.

jQuery Mobile events

  • Before load – fires before any load request is made.
  • Before show – fires when navigating to a page already active after the transition animation has completed.
  • Before unload – fires when the user navigates away from the page. This could be caused by one of several things: by clicking a link to another page, clicking the forward/backward buttons, or even by triggering a page reload. These could all create an unload event.
  • Collapse – fires when a collapsible is collapsed.
  • Document hash changed – fires when the page’s hash changes.
  • Expand – fires when a collapsible is expanded.
  • Hide – fires when the user hides the selected element.
  • Load – fires after the page is successfully loaded and inserted into the DOM.
  • Page hide – fires when the user navigates away from the page after the transition animation has completed.
  • Page show – fires every time the page is displayed after the transition animation has completed.
  • Search – fires before a search is performed.
  • Swipe – fires when a horizontal drag occurs with a 1 second duration.
  • Swipeleft – fires when a swipe event occurs, moving in the left direction.
  • Swiperight – fires when a swipe event occurs, moving in the right direction.
  • Tap – fires after a quick, complete touch.
  • Taphold – fires after a held, complete touch.
  • Virtual click – can be used instead of touch or click events, and will choose the right one depending on the platform you are running.

Service events

  • Before send – fires before a request is started, allows you to modify the jqXHR request object before it is sent.
  • Success – fires only if the request was successful. A variable data contains full service response You can handle it as a usual JavaScript object. Each service has a different response structure. Here is a sample database List service response. It can be mapped to storage or to components:
  • Error – fires only if the request fails. The function receives three arguments (jqXHRtextStatus and errorThrown). There are are the jqXHR object, a string describing the type of error that occurred and an optional exception object, if one occurred. Possible values for the second argument (besides null) are timeout, error, abort, and parsererror. When an HTTP error occurs, errorThrown receives the textual portion of the HTTP status, such as “Not Found” or “Internal Server Error.”
    Sometimes the actual error message from the service invocation is needed (for example when you running the app on the device), you can use following JavaScript code:
  • Complete – fires regardless of if the request was successful, or not (after success and error callbacks are executed). You will always receive a complete callback, even for synchronous requests. The function receives two arguments: The jqXHR object and a string textStatus categorizing the status of the request (success, notmodified, nocontent, error, timeout, abort, or parsererror).

Saving full service response into a storage variable

First, go to Project > Model and Storage > Model and create a model with the same data structure as in a service response.

Then, open Storage and create a storage variable myVariable using the created model.

Use the following JavaScript to save service response to this variable :

Saving a list of database items IDs in an array

Use the following JavaScript code:

Here myIDs is a storage variable declared as an array.

Carousel component events

  • Before next – fires before sliding to the next frame.
  • Before prev – fires before sliding to the previous frame.
  • Clear all – fires before removing all frames.
  • Goto – fires when the user jumps to another frame.
  • Item remove – fires:
    • Before removing DOM element of the frame, when the indicator still exists.
    • Before removing DOM element of the indicator, when the frame is already removed.
  • Ready – fires on loading the frame. For image-type frame, this event fires when the image is loaded.
  • Show – fires on showing the frame.
  • Sliding done – fires after sliding to the next frame (when the animation is completed).
  • Sliding start – fires before any sliding starts, but after beforeshow-event for frame.

PhoneGap events

  • Backbutton – fires when the user clicks the back button on the device.
  • Batterycritical – fires when an app detects the battery has reached the critical level threshold.
  • Batterylow – fires when an app detects the battery has reached the low level threshold.
  • Batterystatus – fires when the battery charge percentage changes by at least 1 percent, or if the device is plugged in or unplugged.
  • Device ready – fires when the app is fully loaded.
  • Endcallbutton – fires when the user clicks the end call button on the device. Use this event if you need to override the default end call button behavior on the device.
  • Menu button – fires when the user clicks the menu button on the device. Use if you need to override the default menu button behavior on the device.
  • Offline – fires when a PhoneGap application is not connected to the Internet (when the application’s network connection changes to offline).
  • Online – fires when a PhoneGap application is connected to the Internet (when the application’s network connection changes to online).
  • Pause – fires when an app is put into the background.
  • Resume – fires when an app is retrieved from the background.
  • Search button – fires when the user clicks the search button on the device. Use if you need to override the default search button behavior on the device.
  • Startcallbutton – fires when the user clicks the start call button on the device. Use if you need to override the default start call button behavior on the device.
  • Volumedownbutton – fires when the user clicks the volume down button on the device. Use if you need to override the default volume down button behavior on the device.
  • Volumeupbutton – fires when the user clicks the volume up button on the device. Use if you need to override the default volume up button behavior on the device.

Push notifications events

If your app uses push notifications, the following events appear in the list:

  • Push initialize – fires when the app initializes connection with server.
  • Push notification – fires when the device receives a notification. You can access message data in handler of this event. For example, code below will display the push notification message:
  • Push registration fail – fires when device registration fails.
  • Push registration success – fires when device registration is successful.

Read more about push notifications events here.

Adding new events & actions

To add a new event and action:

  • Open the Events tab, then select a component to which you want to add the event.
  • It’s a good idea to rename components to have meaningful names. This will make it easier to find the component in the list.
  • If you select a component on the page and then open the Events tab, the component will be selected automatically in the Component list.
  • Some components have default events, as they are most frequently used. For example:
    • Select a Button component; a click event will be selected.
    • Select Input component; a value change event will be selected.
    • The following is an example of selecting the Button component, and opening the Events tab:
      002-NewEvent
  • You can always select a different event from the Event list.
  • Once an event is defined, select an action to run. For example, select the Run JavaScript action:
    003-AddingCode

A list of all the available actions, with descriptions, can be found in the Actions section.

  • To save the event/action, click Save:
    004-AddedEvent
  • It’s possible to edit an existing event. Click the “green pencil” icon, and from the Events drop-down list, pick the new event for your component, and then click Save:
    005-EditingEvent
  • To delete an event, click the red “x” icon.

Multiple events

You can add any number of events to components, and every event may have several actions defined. The event/action combination will be processed in the order defined. For example, a component with two events:
006-MultipleEvents

The actions order can be changed by clicking the up and down arrows.

Events order

Events/actions will be invoked in the order defined. It’s important to keep in mind that JavaScript is asynchronous. For example, if you defined two click events and invoke a service:

  1. Click/invoke service.
  2. Click/invoke service.

The first action will be invoked, but the browser will not wait for the first action to complete and will simply move to invoke the second action. The solution is to use service callback events to invoke the next service.

For example, say you have two services added to the page. To invoke one service after the other one has completed, in the Data view, add the following event:
007-EventsOrder

This way you can add the following events:

  • Before send
  • Success
  • Fail
  • Complete

The list of actions is the same for design and data events.

Actions

The following actions are available:

  • Set HTML attribute
  • Set property
  • Set storage variable
  • Navigate to page
  • Navigate to link
  • Open dialog
  • Close dialog
  • Open popup
  • Close popup
  • Open panel
  • Close panel
  • Invoke service
  • Run JavaScript
  • Mapping

While the app builder defined a number of actions, it’s primary purpose is to make development easier and faster. All actions can be defined in JavaScript, via the Run JavaScript action.

Set HTML attribute

This action allows you to set any attribute on an HTML element.

  1. For the component name, select the component on which you want to set the attribute. The drop-down list includes only components on the active page.

    To make it simpler to find and reference the component, set a clear component name in Properties.

  2. For Property name, enter any valid property on this particular HTML element. Make sure the property you enter is actually available on this element.

    Here are two good sites to tell you which properties are available on which elements: http://simon.html5.org/html-elements and http://htmldog.com.

  3. Set the property value. When this action is invoked, the property you specified will be set to the value you specified. Here is an example of running the action on page load event:
    008-Set-HTML-attribute

Optionally, you can set the property value from the local storage variable by checking the Read from storage variable option.

Set property

This action is the basic version of the Set HTML Attribute action. It works in the same way, except that you are limited to properties available in the drop-down list for each component:
009-SetProperty

As you can see, Property name is limited to values from a list. In the Set HTML Attribute action, you can enter any supported attribute.

Set local storage variable

Sets a value for an existing local storage variable:

  1. Select variable name from a list, for example: id.
  2. Enter value, for example: 12345:
    010-SetStorageVariable

This will set a local storage variable with a name of id and a value of 12345. It’s equivalent to running this in JavaScript:

It’s also possible to bind the variable to a component by checking Bind to Component. This means that when the local storage variable value will be taken (read) from the component to which it’s bound.

For example, the value of id will be set to the current value mobilebutton_2 component:
011-SetStorageVariable(bind)

Learn how to create local storage variables via the link.

Navigate to page

The Navigate to page action allows you to define navigation between mobile screens:
012-NavigateToPage

  • Page – select the page to which you want to navigate. The Page list is ordered alphabetically:
    013-NavigateToPage(page)
  • Transition effect – select a jQuery transition effect:
    • Default (left to right transition)
    • Slide
    • Slideup
    • Slidedown
    • Pop
    • Fade
    • Flip
  • Reverse – if you want to do the transitions in reverse.
  • Use full screen refresh – standard full page refresh.

Navigate to link

Navigates to a page specified in URL. Optionally, you can open the URL in a new window.

Open dialog

Allows you to open a dialog:

  1. To use this action, make sure at least one dialog exists in the project. To create a dialog, select Project view > Create new > Dialog. It’s a good idea to set a name for the dialog in Properties, in order to make it easier to refer to.
  2. Once the Open dialog action is added, select a dialog name from the drop-down list.

Close dialog

Allows you to close a page opened via an Open dialog action.

Open popup

Allows you to open a popup.

  1. To use this action, make sure at least one popup exists in the project.

    Read more about popup component.

  2. Once the Open popup action is added, select a popup name from the drop-down list.
  3. Choose Transition effect your want or leave it as none.

Close popup

Allows you to close a popup.

Open panel

Allows you to open a panel.

  1. To use this action, make sure at least one panel exists in the project.

    Read more about panel component.

  2. Once the Open panel action is added, select a panel name from the drop-down list.

Close panel

Allows you to close a panel.

Invoke service

Invokes a service selected from the list. First, you need to define the service and add it to a page:
014-InvokeService

Learn how to define and add services to the page via the link.

Run JavaScript

This action allows you to run any JavaScript. You can also reference any JavaScript you created from Create New > JavaScript.
014-RunJavaScript

You have access to this element inside this function. This is the jQuery Mobile component to which the event was attached. In the example above, it’s the Button component. For example, if you do:

You will get:

You can access an event object in the same way.

Mapping

Opens Mapping to edit.