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)
.
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:
- Click
Create new app
. - Type an app name.
- Click
From backup
and select the project backup file. - 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.
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 termTable
in SQL databases.
- To create a new (custom) collection to save data click
Create new collection
. For the name, enter:Goods
and clickAdd
. The newly created collection is now listed underCollections
. - 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
(keepingType
asString
). ClickCreate 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 theText
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 theCorners
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:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 |
//Check if this app is installed as binary if (document.URL.indexOf('http://') === -1 && document.URL.indexOf('https://') === -1) { var msg = 'Model: ' + device.model + '\nCordova: ' + device.cordova + '\nPlatform: ' + device.platform; navigator.notification.alert( msg, alertWindowClosed, 'Appery.io App', 'Close' ); function alertWindowClosed() { // do nothing for now } } else { alert('Install app as binary to see the device details!'); } |
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.
- Go to
Resources > Certificates
tab:
- Click
Import Certificates > iOS
. - Click
Choose file
and select your iOS Distribution.p12
file: - Type your password for this certificate and click
Import certificate
:
- Go to the Appery.io Builder,
App Settings > iOS binary
. - 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
:
- Scroll down the page and under the
Distribution certificate
section, select from drop-down menu the earlier-uploaded.p12
certificate. - Click the
Change
button for theProvisioning profile
section and upload the.mobileprovision
file:
- Click
SAVE
. - To publish the app for iOS, click
Export
:
- Click the
.ipa
button under theBinary app
column to start building for iOS. Note that building the .ipa file could take up to 40-50 seconds. - 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:
- First, we need to add extra info about certain item in the database. Go to
WarehouseDB
, openGoods
collection and click+Col
. Typequantity
for a name a selectNumber
asType
:
ClickCreate column
. - Now, you can provide a numerical value for each item as following:
- 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 theServices
folder). ClickTest
on theTest
tab:
- As you can see here, the response now contains new
quantity
fields and its values. ClickImport 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 toResponse
tab. - 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 toModel and Storage
(under theProject
folder) and create the following models:
- Switch to the
Storage
tab and create the local storage variables, as following:
Take a look at theType
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. - 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 theDATA
tab. Click theMapping
action to the right ofSuccess
ofrestservice1
:
- Create the following mapping:
That will fill theitems_array
local storage variable with the returned data from the DB. - Click
Save and return
and create anotherMapping
action forSuccess
(you’ll have two in a row):
- Create the following mapping:
This will cyclically display the data contained in theitems_array
variable on the page viaList
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. - Details of each item will be displayed on another page, to do this create one by clicking
CREATE NEW > Page
:
Give it thedetails
name and clickCreate Page
:
- Let’s create the
details
page UI. SelectHeader
and typeDetails
forText
property. Also, by checking the “Back” button – it will navigate the user on the previously visited page:
- Drag and drop two
Label
components on the page:
- The page UI is ready. Let’s add a mapping that will output
item
local storage variable data to the two added labels. Expand theEVENTS
tab and add the following event:details > Page Show > Mapping
. Create the following mapping:
- Click the
JS
icon to the right of the mapping arrow led from thequantity
parameter. Add the following JavaScript code:
1return 'Quantity: ' + value; - Click
Save
. TheJS
button becomes blue – this means there is a custom JavaScript code that will be executed during mapping:
ClickSave and return
. - This leaves two things left: handle an item click and to navigate the details page. Go to the
startScreen
page and select theList
item. Create the following event:mobilelistitem_3 > Click > Run JavaScript
. Add the following JavaScript code:
123var clickedItemIndex = $(this).closest("li").index(); //Determine clicked list item indexvar currentItemArray = Apperyio.storage.items_array.get()[clickedItemIndex]; //Get the array item by determined indexApperyio.storage.item.set(currentItemArray); //Set the "item" variable with value of that array item
1Apperyio.storage.item.set(Apperyio.storage.items_array.get()[$(this).closest("li").index()]);Save
. - Add another event for the
List
item:mobilelistitem_3 > Click > Navigate to page > details
.
ClickSave
. - Here is how all the events of the
startScreen
page should look:
- Here you go. Test the app and try to click the
List
item. You’ll see thedetails
page with the item name and its quantity.
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:
- 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 findAPI Key
andAPI Secret
underKeys and Access Tokens
tab. - Go to the database you’ve created before (
WarehouseDB
). Switch toSocial connections
tab, and clickAdd an app
. Type the app name you want, paste theConsumer Key
forClient Id
andConsumer Secret
forSecret Id
. ClickSave app
. - Go to
Collections
tab, clickSecurity and permissions
and check theSecure 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. - Go back to the app and add new page named
loginPage
by goingCREATE NEW > Page
. - Go to
Project > App settings
and selectloginPage
forStart page
. - Go back to
loginPage
and change theText
property ofHeader
toSign in
. - Also, place a
Button
to the page, change itsText
property toSign in with Twitter
and itsName
tosign_in_tw
. - Add the following JavaScript on
Click
event to thesign_in_tw
button:
123456Apperyio.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 variableApperyio.navigateTo("startScreen"); //And navigate to different page}, function(error) {alert("error_" + JSON.stringify(error));});Twitter Consumer Key
, Appery.ioApp id
(it’s in the URL, betweenproject/
and/app
) and your Appery.io database id (id of theWarehouseDB
).If you’re using libraries version below 3.0, the
URL
will look as following:1https://appery.io/app/view/{ENTER HERE YOUR APPERY.IO APP ID}/loginPage.html - 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, selectloginPage
asCOMPONENT
andLoad
asEVENT
. Add the following code:123456789101112131415161718192021Apperyio.User.setDefaultDB('5492b499e4b0262b47c39fdc');//If not on the deviceif (!(document.URL.indexOf('http://') === -1 && document.URL.indexOf('https://') === -1)) {checkStatus();}function checkStatus() {if (Apperyio.User.getStatus() === "authorized") { //Check if authentication is already finishedApperyio.storage.token.set(Apperyio.User.getToken()); //If so, store the retreived token to storage variableApperyio.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 againcheckStatus();});}}} - Both code snippets store the token to the storage variable, so it should be created. Go to
Project > Model and Storage > Storage
and addtoken
variable. - You’re almost done. The last step – is to add the token to request. Go to the
startScreen
page and open theDATA
tab. ClickMapping
forBefore send
of therestservice1
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.