Introduction

In this tutorial, you’ll learn how to build a mobile app that displays a list of data from a cloud database. The app communicates with the database via a REST API. You will also see how to add native functionality and build binaries for Android and iOS (.apk and .ipa). At the very end there is a section that describes how to show details on item click (master-detail pattern).

The app will look like:

Try it yourself

Live demo

See the live demo of this app here.

Creating from the backup

You can create this app from the backup (Download backup) to see how it’s built. If this is the first Appery.io app that you are building, it’s strongly recommended that you create it step-by-step.

To create an app from the backup:

1. Click Create new app.
2. Type an app name.
3. Click From backup and select the project backup file.
4. Click Create.

You still have to create the database manually as described in this section below. If you have already created the database, locate the X-Appery-Database-Id:

Then paste it into the WarehouseDB_settings > database_id:

Before you begin

• Tutorial level: beginner; your first mobile app.
• Prerequisites: an Appery.io account.

Creating a new app

Create a new app; from the Apps tab, click Create new app. Name it WarehouseApp and click Create:

Building the UI

1. Every new app comes with a default first page. Open Pages > startScreen:

2. Click the app header, and then change the text to Warehouse App in PROPERTIES.

3. From the PALETTE, drag and drop the list component. When the list is inserted onto the page, it will have three static items.

4. With the list selected, find the items property in PROPERTIES view, and change it to 1, then click Apply”. Using breadcrumbs can help you select components on a page. We’re going to load the data from a database (via a REST service), so that we can simply iterate over the item, in turn building the list.

Your page should look like:

5. Since you always start with a mobile web app (HTML5), you can instantly test the app in the browser. Simply click TEST to launch the app in a new window/tab (make sure popups are enabled for the domain “appery.io”).

Creating a database

Now you’ll create a new database and collection, and populate the collection with sample data.

1. From the app builder, click the Database button to open the Database page (it opens in a new tab):

2. Once the Database tab is open, click Create new database.

3. For the database name, enter: WarehouseDB and click Create.

When the database is created, you will see this page:

• The Users collection is predefined for user management, such as implementing sign-in and registration.
• The Files collection is predefined for uploading files.
• The Devices collection is predefined for registering and working with devices.

Creating a collection

The term Collection in Appery.io databases corresponds to the term Table in SQL databases.

1. To create a new (custom) collection to save data click Create new collection. For the name, enter: Goods and click Add. The newly created collection is now listed under Collections.
2. Each collection has a number of built-in columns (such as _id, _createdAt). You are going to create a new column by clicking +Col. For the column name, enter: item (keeping Type as String). Click Create column. You should see the new column listed in the collection.

Populating the collection with data

To populate the collection with sample data, click +Row and add the data that you want.

An example of a collection with three objects (rows):

Now you’re going to create a REST service to read the data from the database. Notice that every collection has a REST section that displays various REST curl commands. This means that the collection and its data are instantly exposed via REST APIs.

Reading data via REST service

1. In the app builder, select CREATE NEW > Database Services.

2. Select WarehouseDB from the list. Expand the Goods collection to see all of the available methods:

3. Since we only want to display data, check the List service.

4. Click Import selected services.

Under Services, you’ll see two services generated. One is the Settings service that holds the API key for the database, the other is the REST service that receives data from the database:

5. Open the WarehouseDB_Goods_list_service. You’ll see that it has everything you need: the URL and the request and response parameters.

6. Switch to the Test tab. You can test the service here (same as executing a curl command). Click Test.

You can see the objects you created in the collection:

Binding the service

1. Open startScreen and switch to the DATA tab, located just to the left of the Components palette.

2. For Add datasource, select Service > WarehouseDB_Goods_list_service. Click Add. This service has been added to the page.

3. The system generates two mapping actions for Before send and Success events by default; there’s nothing to map for Before send as the database key is being set from the Settings service automatically:

4. Next, click Mapping for Success event and create the following mapping:

• Mapping $ to the list item gives us an automatic looping feature. This allows you to display all the items from the database.
• item is the name of the merchandise, and it’s mapped to the Text property of the list.

4. Click Save and return.

Invoking the service

1. Go to DESIGN view, and select startScreen in the breadcrumbs:

2. Open the EVENTS tab, located towards the bottom of the screen, and change the event to Page show. For the action, select Invoke Service > restservice1. Click Save:

3. Click SAVE in the upper-left side of the screen.

Running the app

Click TEST to launch the app in the browser (when you test the app, it simply runs in the browser, it’s not a simulator):

Running the app on a mobile device

You can also launch the app on your mobile device by scanning the QR code (you must have a QR app on the device). First, be sure to make the app public by checking Public:

If you don’t have a QR code reader on your phone, you can also email the link (without a frame) to your device.

Adding native features

It would also be nice to add some native device capabilities to the app. To keep it simple, you can add a button, and on clicking the button, you can display some information about the device and the Apache Cordova (PhoneGap) version used.

1. Drag and drop a Button inside the footer.

• Change its text to Device Info.
• In PROPERTIES, uncheck the Corners option to make the corners square:
  

2. Select the button and open the EVENTS tab.

3. The button and the click event are selected. Select the Run JavaScript action.

4. Paste the following JavaScript code:

5. Click Save.

Publishing for Android

To publish the app for Android, click Export:

When building binary for Android a certificate is generated automatically, but you can also use your own one – read here for more.

Click the .apk button under the Binary app column to start building for Android. Keep in mind that building the .apk file could take up to 40-50 seconds.

Once the build is completed, the .apk file can be downloaded and you can also see a QR code:

You can scan this QR code to download the file directly on your Android phone and install it.

Publishing for iOS

Since iOS is more demanding in terms of certificates, some additional actions are required to build an .ipa.

Before you can build an iOS binary, you need to sign up for the iOS Developer Program and provide all developer information and certificates below. More information on certificate management can be found here.

If you are new to this, this is a good link to get you started: managing your signing and provisioning assets.

Before you build the binary file, make sure you have the:

• Apple certificate (***.p12).
• Apple provision profile (***.provision).
• Bundle ID (com.company.***) – you can find it in your Apple certificate.

1. Go to Resources > Certificates tab:
   
2. Click Import Certificates > iOS.
3. Click Choose file and select your iOS Distribution .p12 file:
4. Type your password for this certificate and click Import certificate:
   
5. Go to the Appery.io Builder, App Settings > iOS binary.
6. For Bundle ID, type the bundle ID that you provided for the uploaded certificate (you made this when registering the app on the Apple website). For example – com.exadel.apperyio:
   
   
7. Scroll down the page and under the Distribution certificate section, select from drop-down menu the earlier-uploaded .p12 certificate.
8. Click the Change button for the Provisioning profile section and upload the .mobileprovision file:
   
9. Click SAVE.
10. To publish the app for iOS, click Export:
    
11. Click the .ipa button under the Binary app column to start building for iOS. Note that building the .ipa file could take up to 40-50 seconds.
12. Once the build is completed, the .ipa file can be downloaded and you’ll also see a QR code:
    

You can scan this QR code (use the Qrafter app, for example) to download the file directly on your iOS device and install it.

Using the Appery.io Tester to test native apps

Since this API uses native device features, you can no longer just test it in your browser. One option is to build the binary again and then update the app on the device. Another (better) option is to test the app with the Appery.io Tester (Android, iOS):

The Appery.io Tester is a native app,  which you can test apps built in Appery.io. Since you don’t need to install the app each time a change is made, the Appery.io Tester makes it easy to test native apps. The Appery.io Tester is free, and available for iOS and Android. Both versions are open source.

You can find the app in the Google Play Store and iOS App Store. Once the app is installed, launch it and sign in (use your https://appery.io credentials). Find your app in the list, and tap it to launch it.

Look here fore more information on Appery.io Tester app.

Publishing as mobile web app

You can also publish your app as a mobile web app on an Appery.io or custom domain.

Inside the app builder, click CLOSE (upper-left corner) and then choose Back to app list and save scroll down to the Hosting section:

Enter a domain on which you want to host your app, and click Publish. After a few seconds, your mobile app will be available on name.app.appery.io.

Showing details on item click

Often users want  advanced info about certain items  by clicking on a item, this is called Master-Detail pattern. You can extend your Warehouse App with this functionality by following a simple steps below:

1. First, we need to add extra info about certain item in the database. Go to WarehouseDB, open Goods collection and click +Col. Type quantity for a name a select Number as Type:
   
   Click Create column.
2. Now, you can provide a numerical value for each item as following:
   
3. As the collection structure has been changed, the REST Service response should be changed too. Switch back to Appery.io Builder and open the WarehouseDB_Goods_list_service (under the Services folder). Click Test on the Test tab:
   
4. As you can see here, the response now contains new quantity fields and its values. Click Import as Response and response structure of this REST Service will be automatically changed based on the returned data. You can make sure about it by switching to Response tab.
5. As the flow of the app becomes more complicated with the implementation of the master-detail pattern, two new Appery.io innovations can assist you – Model and Storage. These features are really powerful for managing your app data flow and working with local storage. Go to Model and Storage (under the Project folder) and create the following models:
   
6. Switch to the Storage tab and create the local storage variables, as following:
   
   Take a look at the Type column where models created earlier are now used as the type for local storage variables. This means that variables will take the same structure as models.

   You can find more examples of the usage of Model and Storage features in this tutorial. Or see the Model and Storage doc.

7. Now, with the help of Appery.io mapping, you can fill the created variables with the data that REST Service returns. Go to the startScreen page and switch to the DATA tab. Click the Mapping action to the right of Success of restservice1:
   
8. Create the following mapping:
   
   That will fill the items_array local storage variable with the returned data from the DB.
9. Click Save and return and create another Mapping action for Success (you’ll have two in a row):
   
10. Create the following mapping:
    
    This will cyclically display the data contained in the items_array variable on the page via List component. You can now launch the app and if everything was done correctly, you’ll see the familiar list of items with only one difference – the data will be displayed from the local storage variable instead of direct REST Service response.
11. Details of each item will be displayed on another page, to do this create one by clicking CREATE NEW > Page:
    
    Give it the details name and click Create Page:
    
12. Let’s create the details page UI. Select Header and type Details for Text property. Also, by checking the “Back” button – it will navigate the user on the previously visited page:
    
13. Drag and drop two Label components on the page:
    
14. The page UI is ready. Let’s add a mapping that will output item local storage variable data to the two added labels. Expand the EVENTS tab and add the following event: details > Page Show > Mapping. Create the following mapping:
    
15. Click the JS icon to the right of the mapping arrow led from the quantity parameter. Add the following JavaScript code:
    
    1	return 'Quantity: ' + value;

16. Click Save. The JS button becomes blue – this means there is a custom JavaScript code that will be executed during mapping:
    
    Click Save and return.
17. This leaves two things left: handle an item click and to navigate the details page. Go to the startScreen page and select the List item. Create the following event: mobilelistitem_3 > Click > Run JavaScript. Add the following JavaScript code:
    
    1 2 3

    var clickedItemIndex = $(this).closest("li").index(); //Determine clicked list item index var currentItemArray = Apperyio.storage.items_array.get()[clickedItemIndex]; //Get the array item by determined index Apperyio.storage.item.set(currentItemArray); //Set the "item" variable with value of that array item

    The same can be written:
    
    1	Apperyio.storage.item.set(Apperyio.storage.items_array.get()[$(this).closest("li").index()]);

    Click Save.
18. Add another event for the List item: mobilelistitem_3 > Click > Navigate to page > details.
    Click Save.
19. Here is how all the events of the startScreen page should look:
    
20. Here you go. Test the app and try to click the List item. You’ll see the details page with the item name and its quantity.

Adding social login feature

Appery.io provides the convenient way to authenticate users via the social networks.

Read more about Social Login here.

Of course, it concerns the cases when your app needs users authorization in general. In the app built during this tutorial, the login feature hasn’t been described, so let’s extend this app by allowing the users to sign in:

1. You should create an app on the Twitter side. Go to https://apps.twitter.com/. Enter the required information and click Create your Twitter application. Once your Twitter app will be created, you can find API Key and API Secret under Keys and Access Tokens tab.
2. Go to the database you’ve created before (WarehouseDB). Switch to Social connections tab, and click Add an app. Type the app name you want, paste the Consumer Key for Client Id and Consumer Secret for Secret Id. Click Save app.
3. Go to Collections tab, click Security and permissions and check the Secure collection option. This way, token became required to get the info from the database, so you will know, if the social login works or not.
4. Go back to the app and add new page named loginPage by going CREATE NEW > Page.
5. Go to Project > App settings and select loginPage for Start page.
6. Go back to loginPage and change the Text property of Header to Sign in.
7. Also, place a Button to the page, change its Text property to Sign in with Twitter and its Name to sign_in_tw.
8. Add the following JavaScript on Click event to the sign_in_tw button:
   
   1 2 3 4 5 6

   Apperyio.User.loginTwitter("<Your Twitter app Consumer Key (API Key)>", "http://appery.io/app/view/<YOUR APPERY.IO APP ID>/app/loginPage.html", "<YOUR APPERY.IO DATABASE ID>").then(function(token) {     Apperyio.storage.token.set(token); //Store the retrieved token to storage variable     Apperyio.navigateTo("startScreen"); //And navigate to different page }, function(error) {     alert("error_" + JSON.stringify(error)); });

   Note, that you should use your Twitter Consumer Key, Appery.io App id (it’s in the URL, between project/ and /app) and your Appery.io database id (id of the WarehouseDB).

   If you’re using libraries version below 3.0, the URL will look as following:

   1	https://appery.io/app/view/{ENTER HERE YOUR APPERY.IO APP ID}/loginPage.html

9. The code above will work on the device, but it requires one more step to make it work in the browser. In the EVENTS tab, select loginPage as COMPONENT and Load as EVENT. Add the following code:
   1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21

   Apperyio.User.setDefaultDB('5492b499e4b0262b47c39fdc');   //If not on the device if (!(document.URL.indexOf('http://') === -1 && document.URL.indexOf('https://') === -1)) {       checkStatus(); }   function checkStatus() {     if (Apperyio.User.getStatus() === "authorized") { //Check if authentication is already finished         Apperyio.storage.token.set(Apperyio.User.getToken()); //If so, store the retreived token to storage variable         Apperyio.navigateTo("startScreen"); //And navgiate to diffferent page     } else {         if (Apperyio.User.getStatus() != "error") //If status not equals to error         {             document.addEventListener("dbloginend", function() { //Add event listener on dbloginEnd and check the status again                 checkStatus();             });         }     } }

10. Both code snippets store the token to the storage variable, so it should be created. Go to Project > Model and Storage > Storage and add token variable.
11. You’re almost done. The last step – is to add the token to request. Go to the startScreen page and open the DATA tab. Click Mapping for Before send of the restservice1 datasource. Create the following mapping:
    

Now, test the app and try to login with your Twitter credentials.

Where to go from here

Of course, this app isn’t a complete mobile app, but you’ve seen the basics for creating apps via the Appery.io Visual Builder. You may want to extend the app logic with Server Code (code that works on backend) or enable Push Notifications. By using plugins, you can rapidly add 3rd party services (as Facebook or Twilio) support to your app. You can even collaborate with teammates to build apps with Appery.io.

There are many more helpful Appery.io tutorials here, and all the docs you might need are here.

Let support know if you have any issues via the forum or email.