Events and Actions

🚧

Important Note!

The option of creating new apps with the jQuery Mobile framework was removed but we still support the projects that were created with it earlier.

Introduction

When building a mobile web app, almost everything that happens in your app is based on 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 is when you change a value inside an input field; value change event. After the event fires you can pretty much go wherever you want from there.

📘

Events

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:

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

jQuery Mobile Events

Service Events

[
    {
        "_id":"56824c78675adbb40d27149c",
        "Name":"Michael",
        "_createdAt":"2015-12-29 09:06:00.040",
        "_updatedAt":"2015-12-29 09:06:00.040"
    },
    {
        "_id":"56824cff975adbb63077149e",
        "Name":"Igor",
        "_createdAt":"2015-12-29 09:06:07.711",
        "_updatedAt":"2015-12-29 09:06:07.711"
    }
]

📘

Assistance With Error Messages

Sometimes the actual error message from the service invocation is needed (for example when you running the app on the device), you can use the below JavaScript code:

alert(JSON.stringify(jqXHR));

Saving Full Service Response Into A Storage Variable

1. First, go to Project > Model and Storage > Model and create a model with the same data structure as in a service response.
2. Then, open Storage and create a storage variable myVariable using the created model.
3. Use the following JavaScript to save service response to this variable:

Apperyio.storage.myVariable.set(data);

Saving A List Of Database Items IDs In An Array

Use the following JavaScript code:

var myIDs = [];
$.each( data.results, function( key, value ) {
  myIDs.push(value._id);
});
Apperyio.storage.myIDs.set(myIDs);

Here myIDs is a storage variable declared as an array.

Carousel Component Events

PhoneGap Events

Push Notifications Events

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

alert(data.message);

Read more about push notification events here.

Adding New Events & Actions

To add a new event and action:
1)Open the Events tab, then select a component to which you want to add the event. It’s a good idea to rename components, this will make it easier to find the component in the list.

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

• You can always select a different event from the Event list.
• After the event is defined, select an action to run. For example, select the Run JavaScript action.

📘

Note

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

• To save the event/action, click Save.
• 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.
• 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:

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:

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

📘

Note

While the app builder defines 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.
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.
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:

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 the properties available in the drop-down list for each component. As you can see, the Property name is limited to values from a list. In the Set HTML Attribute action, you can enter any supported attribute.

Set Storage Variable

Sets a value for an existing storage variable:

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

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:

localStorage.setItem('id', '12345');

It’s also possible to bind the variable to a component by checking Bind to Component. This means that when the 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:

A storage is created by going to Project > Model and Storage > Storage. The Storage is a wrapper on top of standard browser storage APIs.

Navigate To Page

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

• Page – select the page to which you want to navigate. The Page list is ordered alphabetically.
• 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.

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.
2. After 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.
2. After 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 then add it to a page:

Run JavaScript

This action allows you to run any JavaScript. You can also reference any JavaScript you created from Create New > JavaScript. 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:

console.log(this);

You will get:

<a data-role="button" name="saveButton" dsid="saveButton" class="b utton mobilebutton1 ui-btn ui-shadow ui-btn-corner-all ui-btn-blo ck ui-btn-icon-left ui-focus ui-btn-up-a" id="j_8" data-corners=" true" data-iconpos="left" data-inline="false" data-theme="a" tabi ndex="1" data-shadow="true" data-iconshadow="true" data-wrapperel s="span"><span class="ui-btn-inner ui-btn-corner-all"><span class ="ui-btn-text">Save
</span></span></a>

You can also reference the service which has been defined in the DATA tab and invoke it with JavaScript (use the name of the service from the DATA tab)

service_name.execute({});

Mapping

Opens Mapping to edit.