Introduction
In this tutorial, you’ll learn how to build an AngularJS 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 covered in this tutorial built with Ionic/AngularJS, but you can make it using the Bootstrap as well. All the steps will be the same, except of slight difference in UI components look.
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 to see how it’s built. But if this is the first Appery.io app that you’re building, it’s strongly recommended that you create it step-by-step.
To create an app from the backup:
- Click Create new app.
- Click From backup and select the project backup
.zip
file. - Click Create.
You still have to create the database manually as described in this section below. If you’ve already created the database, find the X-Appery-Database-Id
:
And paste it to MerchandiseDB_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 and select Ionic AngularJS App
. Name it MerchandiseApp
and click Create.
Building the app pages
In this part of the tutorial you are going to design the app pages and the model for pages.
Designing the page
The app UI is designed in the Design tab. This tab will open by default when you open a page.
- Every new app comes with two default pages:
index
andScreen1
. OpenPages > index
:
- Click the app
Header
, and then change itsText
property toIn stock
inPROPERTIES
. Select theColor
property (here,balanced
is used). Clear theFooter
Text
property. You may also define theFooter
Color
property to make the app look consistent:
- Now, switch to
Screen1
and, using the cog sign that appears when selecting the page on the list, rename it toList
. - Using breadcrumbs or
OUTLINE
, selectContent
and set its propertyScroll
=True
. - From the
PALETTE
, drag and drop aList
component. When theList
is inserted into the page, it has three staticList items
. Remove two of them. - Select the remaining
List item
and set its propertyType
=Linked
and define itsng-repeat
value as the following:
1item in listPlease read more about
ng-repeat
here. - Set
Heading > Text
to the following value:
1{{item.name}} - Clear the
Text
property value.
Here is how your List
page should look like:
Since you always start with a mobile web app (HTML5), you can instantly test your app in the browser. Simply click TEST to launch the app in a new window/tab (make sure pop-ups are enabled for the domain “appery.io”).
Creating the page model
The Scope tab holds the model (objects) used by the page.
First, you need to create a model:
- Go to
Project > Model
and create the following model: - Now, go to the
List
page and switch to theSCOPE
tab. - Enter a new variable name:
list
and click Add. Set itsType
toList
:
Creating a database
Now, you’ll create a new database and a new collection, and populate the collection with sample data.
- From the app builder, click
Database
to open theDatabase
page (it opens in a new tab):
- Once the
Database
tab is open, click Create new database. - For the database name, enter:
MerchandiseDB
and click Create.
When the database is created, you’ll see the page with three predefined collections:
- 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
A collection is like a table in a relational database.
- Create a new (custom) collection to save data. Click Create new collection. For the name, enter:
InStock
and click Add. 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:name
(Type
=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, simply click +Row and add any data you want.
An example of the collection with eight objects (rows):
Instead of creating collections manually, you can download the sample MerchandiseDB and unzip it. Just click Import a collection, type its name, and click Choose file to select the previously unzipped file.
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
- In the app builder, select
CREATE NEW > Database Services
. - Select
MerchandiseDB
from the list. Expand theInStock
collection to see all the available methods. - Since we only want to display data, check the
List
service:
- Click Import selected services.
UnderServices
, you’ll see two services generated. One is theSettings
service that holds the API key for the database, and the other is the REST service that receives data from the database:
- Open the
MerchandiseDB_InStock_list_service
. You’ll see that it has everything you need: theURL
and therequest
andresponse
parameters: - 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:
123456789101112131415[{"_id":"54bff7fe975a511d0f066e09","name":"Hoody","_createdAt":"2015-07-29 09:57:40.630","_updatedAt":"2015-07-29 09:57:40.630"},//...{"_id":"54d25b6e975aaa96de09f5f0","name":"Blouse","_createdAt":"2015-07-29 09:57:40.634","_updatedAt":"2015-07-29 09:57:40.634"}]
Invoking Services
Now, when you have created the database and imported the database services, you can proceed with invoking the database services:
- Go to the
List
page, open theSCOPE
view, and click Edit for theinit()
function. - Click Invoke service.
- Click
Backspace
, thenCTRL + Space
and selectMerchandiseDB_InStock_list_service
(you can also enter it manually): - Click
Mapping
belowfunction(success) {}
and create the following mapping: - Click Save & Replace.
- The
init()
function should look like:
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).
The page contains a list of items:
Running the app on a device
You can also launch the app on your 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 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.
- Drag and drop a
Button
component inside aFooter Button
on theindex
page. - Change its text to
Device Info
:
- Select the
Button
and provide the following forng-click
:
1showInfo() - Switch to
SCOPE
and add a new function –showInfo()
. - Define the following code for the function:
1234567891011121314151617if (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!');}
As you can see from the code, you must first install the app as binary to see the device details. See here (Android) or here (iOS) how you can do it.
Publishing for Android
To publish the app for Android, click Export:
Click .apk under the Binary app
column to start building for Android. Note, 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. 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 it when registering the app on the Apple website). For example –io.appery.app.MerchandiseApp
: - Scroll down the page and under the
Distribution certificate
section, select the earlier-uploaded.p12
certificate from drop-down menu. - Click Change in the
Provisioning profile
section and upload the.mobileprovision
file:
Click SAVE. - To publish the app for iOS, click Export:
- Click
.ipa
under theBinary app
column to start building for iOS. Note, that building the X 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 cannot test it in the 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 from 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.
Besides, to share your app with non-Appery.io users, you can go to the Apps
tab, select the project and scroll down to the Share via Appery.io Tester app
section, then turn the toggle
“on”.
Then, follow the instructions provided.
More information on sharing via Appery.io Tester apps is here.
Publishing as mobile web app
You can also publish your app as a mobile web app on an Appery.io
or some custom domain.
Inside the app builder, click CLOSE (upper-left corner) and then choose Back to app list and save to 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
It’s an often scenario when advanced info about certain item appears on a click. It’s called “Master-Detail pattern”. You can extend your MerchandiseApp
with such functionality by following simple steps:
- First, you need to add extra info about the items in the database. Go to
MerchandiseDB
, openInStock
collection and click +Col. Typeprice
for aname
a selectNumber
asType.
- Click Create column.
- Now, provide values for each item as following:
- As the collection structure has been changed, REST Service response should be changed too. Switch back to the Appery.io Builder and open the
MerchandiseDB_InStock_list_service
(underServices
folder). Click Test on theTest
tab:
1234567891011121314151617[{"_id":"54bff7fe975a511d0f066e09","name":"Hoody","_createdAt":"2015-07-29 09:57:40.630","_updatedAt":"2015-07-29 13:15:37.258","price":7.0},//...{"_id":"54d25b6e975aaa96de09f5f0","name":"Blouse","_createdAt":"2015-07-29 09:57:40.634","_updatedAt":"2015-07-29 13:14:55.306","price":7.7}] - As you can see, now the response contains new fields and values. Click Import as Response and the response structure of this REST Service will be automatically changed basing on the returned data. You can make sure about it by switching to the
Response
tab. - Now, go to the
List
page, open theDESIGN
tab, select theList item
component, and add a new attribute:ng-click
with the next value:
1showPrice(item.price) - Then, go to the page
SCOPE
and add a new function:showPrice()
withArguments
=price
, then insert the following code for the function:
12$scope.price.current = price;Apperyio.navigateTo("Price"); - Perform:
CREATE NEW > Page
, enterPrice
for thename
and click Create page. - In
DESIGN
view, drag and drop aButton
to the page withText
=Back
, select theion-chevron-left
forIcon
(Position
=left
), and pass the followingng-click
=goBack();
. - In
SCOPE
view, add a new scope function:go Back()
with the following code:
1Apperyio.navigateTo('List'); - Drag and drop the
List
component to the page, delete two of the threeList items
. - Now, select the remaining
List item
and set itsText
property to:
1{{price.current|currency}} - Now, add the page to routing:
Project > Routing
, select thePrice
page, enterPrice
for theroute name
, and click Add: - Lastly, edit the
init()
function of theindex
page by adding the following code into the code editor:
123$scope.price = {current: 0};
Here is the resulting view of the Price
page:
You can now go testing your app.
Alternatively, you can use the
backButton
directive to store navigation history. Click here to learn about thebackButton
directive.
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 an apps with Appery.io.
There are many more helpful Appery.io tutorials here, and all the docs you might need here.
Let support know if you have any issues via the forum or email.