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

Attachments

Introduction

This tutorial shows some of possible ways to use the Model and Storage features within the example MusicShop app. This app allows the user to browse for instruments, choose a certain instrument, add it to the cart and then check out all the items in the cart. After checkout, all of local storage variables are simply cleared.

Creating from the backup

You can create this app by following our step-by-step tutorial below or by using the backup.

To create an app from a backup:

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

There is no need to follow the tutorial below if you decided to create this app from the backup.

The backup of this project contains two list services – a common REST Service that pulls data from the database and a Generic Service that simulates a common REST Service but returns all data locally. By default, the Generic one is used so the app will work without the database. If you decide to create this app via the backup, and you want to use a database, go to this section.

Before you begin

Tutorial level: advanced.

Creating a new app

Create a new app in the builder. From the Apps page, enter an app name and click Create. You’ll see a start page.

Creating the Models and Storage variables

This app uses Appery.io Models to create incoming data structures and Storage to create local storage variables based on these models. The main idea of the Models and Storage is to create an app structure before the actual development. So, first the data structure should be defined by creating the Models.

There are 4 Models in this app:

  • instrument – Model that describes the instrument entity with all its properties.
  • musical_instruments – Model that is an array of the instrument Models.
  • cart_item – Model that describes the instrument added to the cart.
  • cart – Model that is an array of the cart_item Models.

To create these models, go to Project > Model and Storage.

Create the following models:ms_models

Switch to the Storage tab to create local storage variables based on this model. There is also a total_price local storage variable, which is not a type of existing models, but a type of Number.

Create the following local storage variables:ms_variables

Creating the UI

Once the data structure is defined, all other app views can be created because it’s clearer now what data will app will operate.

Here’s a view of all the UI:ms_ui_view

 Catalog page

The initial page of the MusicShop app is the Catalog page. The list of musical instruments will be displayed on this page. The UI of this page will look like the following:
ms_catalog_page_ui

Complete the following steps to build it:

1. Rename the startScreen page to Catalog. Pages are listed under the Pages folder:
ms_catalog_page

2. Select Header and change its Text property to Catalog:
ms_catalog_header

3. Place a Button component to the right of Header title. Change its Text property to Cart, choose the shop icon and change its Position to right. Also select G for Swatch, type cart_button for Name and uncheck the Visible property:
ms_catalog_cart_button

Initially, Appery.io apps come with only one predefined flat-ui theme. Other default themes are available via plug-ins.

To learn how to import them, go here.

4. Drag a Search component to the Header under the Catalog label. Clear its Text property, and type Type for search for the Placeholder. Set its Name as search_bar and 0 10 8 10 values for Margin:
ms_catalog_search_bar

5. Add a List component to the page. Set its Items property to 1 and click Apply:
ms_catalog_list

6. Make sure that mobilelist_x (not the mobilelistitem_x) is selected (you can use breadcrumbs to check it). Uncheck Round corners, select C for Swatch and type instrument_list for Name:
ms_catalog_list_properties

7. Select mobilelistitem_x (use breadcrumbs). Choose thumbnail for Image Type. Also set Name property to instrument_item:
ms_catalog_list_item

8. Drag and drop the Label component over the List item. Set the Label‘s Text property to Instrument name, and Name to instrument_name. Also, type 4 for left Margin, select bold and uncheck italic for Font:
ms_catalog_list_item_instrument_name

9. Drag and drop the Label component over the List item. Set the Label‘s Text property to In stock, and Name to in_stock. Also, enter 4 for left Margin, and uncheck italic for Font:
ms_catalog_list_item_in_stock

10. Drag and drop a Label component over the List item. Set Label‘s Text property to $999, and Name to price. Also, enter 4 for left Margin, type #448600 for Font Color, check bold and uncheck italic for Font:
ms_catalog_list_item_price

11. The last component for this page is an About us button. Place the Button inside the Footer. Change its Text to About us, click No icon to the right of Icon and select i icon. Also, change its Name to about_us_button:
ms_catalog_about_us

Almost the exactly same List structure will be used again on the InstrumentDetails and Cart pages. With the help of Custom Components, this List can be saved and used multiple times on any page:

1. Select instrument_list and click Save as custom component on the top of the PROPERTIES panel:
ms_list_save_as_custom_component

2. Enter the name MusicShopList and click Save:
ms_list_custom_component

 InstrumentDetails page

The InstrumentDetails page will display the details of the chosen instrument. Click CREATE NEW > Page, enter the name: InstrumentDetails and click Create Page.

The UI of the InstrumentDetails page will look like the following:
ms_instrument_details_page

Follow the steps to build the InstrumentDetails page UI:

1. Select Header and change its Text property to Details. Check the Back Button and type Catalog for Back Button Text. Also, type go_to_catalog_button for its Name:
ms_details_header

2. Scroll down the components PALETTE and drag the MusicShopList component to the page:
ms_palette

3. There’s a single thing you need to do with the MusicShopList: remove the icons. Click Break apart custom component in the top of the PROPERTIES panel:
ms_details_break_apart

4. Select instrument_list_x, click the arrow icon to the right of the Buttons Icon and click No icon:
ms_details_list_without_icons

5. Drop the Label component under the List. Change its Text property to Description, its Name – to description and uncheck italic right to the Font:
ms_details_description

6. Next, place the Button component. Change its Text to Add to cart, check Mini Version and Inline. Select the shop icon, change Position to right, and select D for Swatch. Also change its Name to add_to_cart_button and set all zeros for Margin:
ms_details_add_to_cart

Cart page

The Cart page will display all the items that were added to the cart. Click CREATE NEW > Page, enter name Cart and click Create Page. The UI of the Cart page will look like the following:
ms_cart_ui_view

Follow the steps to build the Cart page UI:

  • Select the Header and change its Text property to Cart.
  • Place the Button component to the left of the Header title. Change its Text property to Catalog and choose left arrow. Also, type go_to_catalog_button for Name.
  • Place the MusicShopList component on the page.
  • Click Break apart custom component in the top of the PROPERTIES panel.
  • Select instrument_list_x, click the arrow icon to the right of the Buttons Icon and click No icon.
  • Select in_stock_x, change its Text to x 2, its Name to quantity, type #969696 for Font Color and select bold:
  • ms_cart_list
  • Drop the Label component under the List. Change its Text property to $999, its Name to total_price and uncheck italic and check bold to the right of the Font:
    ms_cart_total_price
  • Next, place the Button component. Change its Text to Checkout, check Mini Version and Inline. Select the tick icon, change Position to right, select F for Swatch. Also, change its Name to checkout_button and set all zeros for Margin:
    ms_cart_checkout_button

About us page

The About us page will display information about this app. Click CREATE NEW > Page, enter the name: AboutUs and click Create Page. The UI of the AboutUs page will look like the following:
ms_about_us_ui_view

Follow the steps to build the About Us page UI:

  • Select the Header and change its Text property to About us. Check the Back Button and type Catalog for Back Button Text. Also, type go_to_catalog_button for Name.
  • Drop the Label component under the List. Change its Text property to the text you want and uncheck italic to the right of the Font.

BuyConfirmation dialog

The BuyConfirmation dialog will appear once after clicking Checkout on the Cart page. Click CREATE NEW > Dialog, enter the name: BuyConfirmation and click Create  Dialog.

The UI of the BuyConfirmation dialog will look like the following:
ms_dialog_ui_view

Follow these steps to build the BuyConfirmation page UI:

1. Select Header and change its Text property to Buy?.

2. Drop the Label component on the page. Change its Text property to Are you sure you want to continue checkout?, uncheck italic to the right of the Font, and choose middle Align:
ms_dialog_label

3. Drop the Label component on the page. Change its Text property to $999, its Name to total_price, type #448600 for Font Color, uncheck italic and check bold to the right of the Font. Also select middle Align:
ms_dialog_label_2

4. Next, place the Button component. Change its Text to No and check Inline. Select the cancel icon, change Position to right, change Name to no_button and set 4 15 4 35 values for the Margin:
ms_dialog_no_butto

5. Place the Button component under the no_button. Change its Text to Yes, and check Inline. Select the tick icon, change Position to right, change Name to yes_button and set 4 15 4 15 values for the Margin:
ms_dialog_yes_button

Creating a database

All the information about the musical instruments will be stored in the database and then retrieved via the REST Service. If you decided to create this app from the backup, you can see that there is a Generic Service used by default and all data is stored locally without the use of a database.

Follow the steps to create the database and use remote data:

1. Click Database in the top right corner of the screen.

2. Click Create new database, Type MusicShop and click Create.

3. Download this zip archive and unzip it. There is an exported instruments collection as a .json file and folder with images inside it.

4. Click Import a collection. Type instruments. Click Choose file and select the previously unzipped instruments.json file.

Click Import. You should get the following collection:ms_imported_collection

5. As you can see, there are no files inside the photo column. Click on the first cell of the photo column, and Media Manager will appear. Click Upload file, then click it a second time and navigate inside the images folder of the unzipped instruments folder and choose violin.png.

Once the image is uploaded, select it and click Select:
ms_select_violin

6. The link on the image will be inserted into the cell of the photo column:
ms_inserted_violin_image

7. Upload the rest of the images the same way for the associated collection rows:
ms_inserted_images

If you created the app from the backup, continue from this section.

Importing the REST Service

A REST Service is needed to retrieve data from the database that was created above. The REST Service also can be automatically generated based on the existing databases and collection.

Here is how it can be done:

1. Switch to the Appery.io Visual builder. Click CREATE NEW > Database Services. Select MusicShop from the drop-down list. Expand the instruments collection and check the List service:
ms_import_rest

2. Imported List and Settings services will be listed under the Services folder:
ms_services_folder

3. A where parameter should be added to the Query String of the List service. It will be used again for search. Go to MusicShop_instruments_list_service and switch to the Query String tab of the Request view.

Type where in and click Add:
ms_list_where

4. Go to MusicShop_settings and add the photo_url parameter with https://api.appery.io/rest/1/db/files/ value:ms_settings_photo_url

Invoking the service

One of the main benefits of using the Model and Storage features is that the List service can be invoked once upon app start and retrieved data can be used further across the whole app.

Lets invoke the List service:

1. Go to the Catalog page and switch to DATA tab.

2. Select Service to the right of Add datasource and choose MusicShop_instruments_list_service. Click Add.

3. Rename the created datasource to get_instruments:
ms_added_datasource

4. Switch to the DESIGN tab and open the EVENTS tab.

5. Select Catalog as COMPONENT, Page show as EVENT and Invoke service as ACTION. Choose get_instruments for Datasource and click Save:ms_invoked_service

Adding Events and Mapping

Once the data structure of the app is ready and the service invokes, it’s time to add events and mapping. Lets walk through the all pages one-by-one and add them.

Catalog page Events and Mapping

Go to the Catalog page, expand the EVENTS tab and add the following events:

1. Catalog > Load > Run JavaScript.

Add the following JavaScript code:

2. Catalog > Page show > Run JavaScript.

Add the following JavaScript code:

3. about_us_button > Click > Navigate to page > AboutUs.

4. cart_button > Click > Navigate to page > Cart.

5. instrument_item > Click > Run JavaScript.

Add the following JavaScript code:

6. instrument_item > Click > Navigate to page > InstrumentDetails.

7. search_bar > Value change > Invoke service > get_instruments.

Here is how all the events for the Catalog page look like:ms_catalog_events

Now, let’s add mapping:

1. Switch to the DATA tab and click Mapping to the right of Before send for the get_instruments datasource.

Create the following mapping:ms_catalog_where_mapping

2. Click JS to the left of the where parameter and add the following JavaScript code:

3. Click Save and return to close the newly-created mapping.

4. Click Mapping for the Success event and create the following mapping:ms_catalog_success_mapping

5. Click JS to the left of the photo parameter and add the following JavaScript code:

6. Click Save and return.

7. Click on the down arrow icon to the right of the Success event of the get_instruments datasource.

Select Mapping:
ms_catalog_add_mapping

8.Create the following mapping:ms_catalog_ui_mapping

9. Add the following JavaScript code for in_stock > Text by clicking JS:

10. Add the following JavaScript code for price > Text by clicking JS:

You can test the app now by clicking TEST. You should see the list of musical instruments:
ms_first_test

InstrumentDetails page Events and Mapping

Go to the InstrumentDetails page, and add the following events:

1. InstrumentDetails > Load > Run JavaScript.

Add the following JavaScript code:

2. InstrumentDetails > Load > Mapping.

Create the following mapping:
Mapping

3. Add the following JavaScript code for in_stock > Text by clicking JS:

4. Add the following JavaScript code for price > Text by clicking JS:

5. add_to_cart_button > Click > Mapping.

Create the following mapping:ms_details_add_to_cart_mapping

6. add_to_cart_button > Click > Run JavaScript.

Add the following JavaScript code:

7. add_to_cart_button > Navigate to page > Cart.

All events on the InstrumentDetails page look like the following:ms_details_all_events

Cart page Events and Mapping

Go to the Cart page, and add the following events:

1. Cart > Load > Run JavaScript.

Add the following JavaScript code:

2. Cart > Load > Mapping.

Create the following mapping:ms_cart_mapping

3. Add the following JavaScript code for quantity > Text by clicking JS:

4. Add the following JavaScript code for price > Text by clicking JS:

5. Cart > Load > Mapping.

Create the following mapping:ms_cart_mapping_2

6. Add the following JavaScript code for total_price > Text by clicking JS:

  1. checkout_button > Click > Open dialog > BuyConfirmation.
  2. go_to_catalog_button > Click > Navigate to page > Catalog.

All the events on the Cart page look like the following:ms_cart_all_events

BuyConfirmation dialog Events and Mapping

Go to the BuyConfirmation dialog, and add the following events:

1. BuyConfirmation > Load > Mapping.

Create the following mapping:ms_buy_confirmation_mappingf

2. Add the following JavaScript code for total_price > Text by clicking JS:

3. no_button > Click > Close dialog > BuyConfirmation.

4. yes_button > Click > Run JavaScript. Add the following JavaScript code:

5. yes_button > Click > Navigate to page > Catalog.

All the events on the BuyConfirmation dialog look like the following:ms_buy_confirmation_all_events

 Configuring the app

If you created this app from the backup, and you want to get data from the database, follow the steps below.

The following steps assume that you already completed this section.

1. Go to the Catalog page and expand the EVENTS tab. Select Catalog for COMPONENT. Change the invoking datasource from get_instruments_generic to get_instruments:ms_catalog_change_data_soource

2. Select search_bar for COMPONENT and change the invoking datasource to get_instruments.

3. Click on the Database in the top right corner of the screen. Open the MusicShop database that was created earlier in this section. Click GET and copy the X-Appery-Database-Id:
ms_catalog_database_id

4. Switch to the Appery.io Visual Builder and go to MusicShop_settings. Paste the copied value to the database_id parameter:ms_settings

Testing the app

Click TEST to launch the app in the browser:ms_test