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

What we are going to build?

In this tutorial we will show you how to build a cross-platform mobile app for a food truck that sells burgers. We will call our truck Burgerio. The app allows to place a burger order ahead of time, and when the truck arrives, you’ll simply pick up the order.

What you will learn

After completing this tutorial you will learn:

  • Building mobile app in Appery.io
  • Creating and using Orchestrate database
  • Connecting for Orchestrate database from Appery.io app using REST APIs
  • Publishing the app as HTML5, or PhoneGap

Before you begin

Before you begin, you need to have an Orchestrate account.

Tutorial level: intermediate.

Creating a new app

To begin, you are going to create a new app. Click the “Create new app” button, name the app: Burgerio, and click “Create.”

When the new app loads, you will see the Start page (this page has links to documentation, tutorials, events, etc).

Open the first page: Pages > startScreen.

Let’s pick a different theme for our app.

To change your theme and swatch settings, you need to import the available default themes via plug-ins first: CREATE NEW > From Plug-in (or click “Add more Themes” from App settings > General), which will open a window with the list of available themes for importing. Select the theme to import  (Jqm-classic) and click “Import selected plug-ins”.

Go to Project > App settings > General, for Theme, select jqm-classic.

Go back to the startScreen page, and you will see this:StartPage

Creating the UI

Building the Orders page

Let’s build the UI for the Orders page:

1. The first step is to rename the page. With the page name selected (use breadcrumbs to select startScreen), rename the page to Orders in PROPERTIES.

2. Select the Header and change its Text property in the PROPERTIES panel to Burgerio.

3. By using the drag and drop place the Button component on the page (drag it on the Header component right to the Burgerio title). Change its Text property to New order and its Name to navigate_to_add_order_button. Also choose the “plus” icon by clicking “Icon” in PROPERTIES panel:
NewOrderButton

This button will navigate the user to a page where a food order can be made.

4. Now place the List component on the page. This list will display all the orders. Change its Name to records_list. As the List items will be generated dynamically based on the retrieved data, you should leave only one item. Change the Items property to 1 and click “Apply”.

5. Counter property of the List item will be used to show how many burgers of each type were ordered. Select the List item (use breadcrumbs for simpler navigation) and check the “Counter Visible” property in the PROPERTIES panel. Also change its Name to records_item.

6.  Drag two Label components directly into the List item.

7. Select the first label and change its Text property to Burger and its Name to burger_label. Burger name will be displayed using this label.

8. The second label will be used to keep the ID of the current order (retrieved from Orchestrate backend, we will come back to this later). Select it and change its Name to order_number. Uncheck the “Visible” checkbox.

The final Orders page looks like this:OrdersScreen

Building the AddOrder page

The second page will allow you to place an order.

1. To create a new page select CREATE NEW > Page. Type AddOrder and click “Create Page.”

2. Select the Header and change its Text property in the PROPERTIES panel to Add Order. Check the “Back Button” checkbox.

3. Place a Select component into the AddOrder page. This component will be used to select the burger that you want to order. Change its Name property to hamburger_select. In the PROPERTIES panel, click “Change” to the right of the Options label. Configure the Select component Options as following:
Options

To add new values, enter new label/value pairs and click the “Add” button.

4. Now let’s add a Slider component to a page and configure it. By using this component, the user will choose the amount of ordered burgers. Drag the Slider component to a page below the Select. Change its Value (default value) to 1, Min value to 1 and Max value to 10. Also, change its Name property to qty_slider.

5. Place a Button component that will save the order into the Orchestrate backend. Add a Button component to the page and change its Text property to Place order. Also, change its Name to place_order_button, and check the “Inline” option.

The final AddOrder page looks like this:AddOrderScreen

You are almost done with the UI. The last page (dialog) you need to create is when deleting an order.

Building the DeleteConfirmation dialog

  1. Click CREATE NEW > Dialog. Type DeleteConfirmation and click “Create Dialog.” The dialog is similar to the classic page, but it can be opened as a dialog (like a popup).
  2. Select the Header and change its Text property in the PROPERTIES panel to Delete?
  3. Next, add the Label component and change its Text property to Are you sure you want to remove this order?
  4. Add the Grid component. The Grid will serve as convenient container to place other components. Change its Rows count to 1 in the PROPERTIES panel.
  5. Place the Label component in the first Grid column. Change its Text property to Burger name and its Name to burger_name.
  6. Place a Button below the Label and change its Text property to Yes. Also change its Name property to yes_button.
  7. Place the Label component in the second Grid column. Change its Text property to Burgers quantity and its Name to burgers_qty.
  8. And place the last Button below the burgers_qty label and change its Text property to No. Also change its Name property to no_button.

The final DeleteConfirmation dialog looks like this:
DeleteConfirmation

Creating a database

Now that we are done with the app UI, you are going to create the app backend in Orchestrate.

  1. Sign in with your Orchestrate credentials at http://orchestrate.io/. Click “CREATE YOUR FIRST APPLICATION” to create a new application. Name the application and then click the green icon to create it.
  2. Once the application is created, you will see the dashboard and your API key. Let’s create a new collection by clicking “+NEW COLLECTION.” Name the collection: Orders, and click the green icon to create it.

Copy the API key.

This is how the Orchestrate dashboard with the database you just created should look:OrchestrateDashboard

Everything created in Orchestrate is instantly exposed via REST APIs. Connecting to any RESTful API in an Appery.io app is super easy – and that’s exactly what we are going to do next.

Defining and binding REST API services

When you have more than one API service, it’s a good idea to keep the API key (and other common properties) in a single place and then simply reference it from the services.

To ensure that the data remains intact without modification during transport we will use a Base64 encoding scheme to get a protected key to be used for setting the app’s services:

1. Copy your Orchestrate API key  and insert it into the form, then click “>ENCODE<“:
Base64Encode

2. Copy the encoded key and switch to the Appery.io app builder and select CREATE NEW > Service. Choose Settings (REST settings) and click “Create Service”.

3. Add two parameters and their values:

  • orders_collectionOrders.
  • api_key – paste the encoded API key:

Settings

Adding the PlaceOrder service

Now let’s add a PlaceOrder service that will send the order to Orchestrate.

1. Select CREATE NEW > Service > REST. Type PlaceOrder and click “Create Service.” Configure the REST service as following:

  • Type the following string for the URL field:
    As you can see, the URL contains values in braces – those values will be taken from the specified Settings file.
  • Choose PUT as Method.
  • Select Settings (that was created in the previous step) for Settings.
  • Click “New channel” to create a new Appery.io Proxy channel, select OrchestrateProxy and click “Create.” This Proxy channel will be used with all further REST Services.

Here is how PlaceOrder REST Service Settings should look:
PlaceOrderSettings

3. Open the Request tab and, under Body tab, add two parameters – key and json.

4. Two more parameters – burgerName and burgersQty should be added as string objects for json:PlaceOrderSettingsRequest

5. Then switch to Headers, add a new parameter (Authorization), and define its value as follows:PlaceOrderSettingsRequestHeaders

6. Open the Test tab. Specify a key value as number sequence. For example – 3681236897512. And values for json as:

7. Click “Test”. Congratulations, you just ordered 2 hamburgers!Test

8. You can ensure that the order was placed by checking the collection on the Orchestrate side. Go to Orchestrate.io, select the app and then the Orders collection. The Key/Value tab will open. You shouldn’t type anything here, just click the red square button with small white arrow to make a GET request:OrchestrateGetResult

As you can see, 2 hamburgers are there.

Next you are going to add the service to the page:

1. Open the AddOrder page and switch to DATA view. Choose Service as datasource, select PlaceOrder and click “Add.” Rename the service instance to place_order:

2. Click “Mapping” for Before Send event to bind the service to the page. Mapping (binding) allows you to take values from the page and use them as values for service input parameters, and take data from the service and map it to the page for display.

3. Before Send mapping for PlaceOrder service requires a unique value for the key. Click the “JS” button for the key parameter. Instead of mapping a value from the page (usually entered by the user), we are going to generate the unique value in JavaScript. Orchestrate stores values under a unique key. This key can be used further to retrieve or delete data stored under this key. We will show you how to use a simple UUID generator to automatically generate a key.

Add the following JavaScript and click “Save and return”:

Any time the PlaceOrder service triggers, this code will be executed and will generate a unique key.

4. As the actual data needs to be in JSON format, the actual order payload also needs to be created in JavaScript. Click “JS” for the JSON parameter. Add the following JavaScript code and click “Save and return”:

This code will take values from UI components and wrap it in JSON format.

Switch to DESIGN view, select the place_order_button and expand the EVENTS tab. Add the following event and save:

place_order_button > Click > Invoke service > place_order.

Adding the GetAllOrders service

Let’s create a service that will retrieve all the orders.

1. Go to the Orders page and select CREATE NEW > Service > REST. Type GetAllOrders and click “Create Service.” Configure the REST service as following:

  • Type the following string as URL:
  • Select the Settings and Proxy:

GetAllOrdersSettings

2. Go to the Request tab and define Authorization parameter:
GetAllRequestHeaders

3. Open the Test tab and click “Test.” You should see one order that you created. Click “Import as Response.” This automatically creates the service response structure based on the test data.

4. Open the Orders page and switch to DATA view. Add the GetAllOrders service instance. Name it get_records.

5. There is nothing to map for the input. So, click “Mappingfor Success event, create the following mapping and save:Mapping

Note: Read more about Appery.io mapping here.

Switch to DESIGN view, then open the EVENTS tab and add the following event that will trigger the get_records service when page loads:

Orders > Page show > Invoke service > get_records.

Now you can test the app. Click “TEST” button in top right of the screen and you’ll see your orders when the page loads:
2Hamburgers

Go back to the Orders page and select “New order”. Expand the EVENTS tab and add the following event:

navigate_to_add_order_button > Click > Navigate to page > AddOrder. Click “Save”:navigate_to_add_order_button

Try to add some orders by navigating to the AddOrder page.

Setting an event to open the delete dialog

Do you remember that we created a DeleteConfirmation dialog? The user should have the ability to cancel an order, so let’s work on that.

First, you have to create a new storage variable. Select Project > Model and Storage>Storage, then enter selected_order as a new storage variable:NewStorageVariable

In the Orders page, select the records_item and add the following events:

  • records_item > Click > Set storage variable > selected_order. Check “Bind to component” select the Target component – order_number and Property name  – Text. Click “Save”.
  • records_item > Click > Open dialog > DeleteConfirmation. Click “Save”.

This will open up the delete confirmation dialog.

Adding the GetOrder service

Go to to the DeleteConfirmation dialog and follow the steps to add a GetOrder service. It needs to retrieve information about the selected order (on which the user clicks):

1. Select CREATE NEW > Service > REST. Type GetOrder and click “Create Service.” Configure the REST service as following:

  • Type the following string as URL:
  • Select the Settings and Proxy:

GetAllOrderSettings

2. Open the Request tab and add the key parameter:GetOrderKeyString

3. To authorize security, define the Authorization parameter under the Headers tab:GetOrderHeaders

4. Open the Response tab and add the JSON parameter with two nested parameters – burgerName and burgersQty:GetOrderResponseBody

5. Add the service instance to the page under the DATA tab, and name it get_order.

6. Click “Mapping” for Before Send event, create the following mapping for the get_order service and save:GetOrderServiceBSMapping

7. Switch to Success event and create following mapping and save:GetOrderServiceSuccessMapping

Now we need an event that will invoke GetOrder service on page Load event. Switch to DESIGN view and open EVENTS tab. Add the following event:
DeleteConfirmation > Load > Invoke service > get_order. Click “Save”.

Adding the DeleteOrder service

1. Select CREATE NEW > Service > REST. Type DeleteOrder and click “Create Service.” Configure the REST service as following:

  • Type the following string as URL:
  • Select DELETE for Method.
  • Select the Settings and Proxy:

DeleteOrderSettings

2. Open the Request tab and add the key parameter:DeleteOrderKeyString

3. Switch to the Headers tab and define the Authorization parameter: GetOrderHeaders

4. Open the deleteConfirmation dialog and switch to DATA view.

5. Add the service instance to the page and name it delete_order.

6. Click “Mapping” for Before Send event, create the following mapping for the delete_order service and save:DeleteOrderServiceBSMapping

Now we just need to add events to invoke the services. Switch to DESIGN view and select the yes_button. Add the following events:

  • yes_button > Click > Invoke service > delete_order.
  • yes_button > Click > Close dialog > DeleteConfirmation:

Select the no_button.  Add the following events:

  • no_button > Click > Set storage variable. Choose selected_order as Variable name and leave the Value field empty.
  • no_button > Click > Close dialog > DeleteConfirmation:

Testing the app

Click “TEST” to launch the app in the browser.

The app should look like:
Final

Android

Android testing options:

  1. Use the Appery.io Mobile Tester app. It’s an app that allows you to launch any app created in Appery.io as a hybrid app.
  2. Build the Android binary and install it your device. When the build is completed, you’ll see a QR code. Scanning the QR code will download the app to your phone. You can also email the app to your device.

iOS

iOS options:

  1. Use the Appery.io Mobile Tester app. It’s an app that allows you to launch any app created in Appery.io as a hybrid app.
  2. Build the app and install it on your device.