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

What are we going to build?

In this tutorial, you’ll learn how to build a merchandise mobile app where a user can sign in or register, and keep a list of his/her merchandise items. This app uses the Appery.io databases, Users collections, and shows you how to create a sign in/registration feature.

Before you begin

Tutorial level: advanced.

This tutorial assumes you know how to build mobile pages, add and map services, and write JavaScript.

Creating a new app

Create a new app in the Builder; from the Apps page, click “Create new app,” enter an app name and click “Create”. After the app builder opens, go to Pages > startScreen.

We’re going to create two pages and a database for the app.

Creating a sign-in page

The sign-in page allows users to sign in to their account, and view the merchandise there. The sign-in page also allows new users to register.

Build the following UI:
UI

  • The page is renamed to Signin.
  • Inputs use placeholders to show the input label.
  • Buttons are set to Inline.
  • Existing user/New user sections are created by placing the List component, setting it to one item, and changing the item type to Divider, by checking the “Divider” box.
  • In PROPERTIES, change the Name property for Existing user Username to signin_username and for New user Username to register_username.
  • Similarly, change the Name property for Existing user Password to signin_password and for New user Password to register_password.
  • Both header and footer are hidden in this page.

Creating a merchandise page

The Merchandise page looks like:
merchandisePage

Creating an app database

To start creating the app database, click on the “Database” button in the builder (upper right corner) or simply go to https://appery.io/database.

1. Create a new database; name it MerchandiseDB.

2. Once the database is loaded, create a new collection (custom) called Merchandise.

3. Add one new column to the Merchandise collection called item (type should be string).

It should look like:
MerchandiseDB

4. Then, open the Security and permissions tab, check the “Secure collection” box and save.

5. After that, open the Change default ACL tab. A new window opens where you have to choose @Creator as a Username, click “Add user” and “Save and Close” buttons.

After choosing the Username value, appery user should click the “Add user” button prior to clicking “save”, otherwise default ACL won’t be changed.

6. The Users collection is built into every database, and has two required default columns: username and password (you can create custom columns as well):UsersCollection

7. Click “+Row,” and add the first user to the collection by setting the user’s username and password. For example:Jane

Creating REST API services

Inside the app builder, go to CREATE NEW > Database Services. Select the MerchandiseDB database, and then check the following services:
ImportDBServices

Once the services are imported, you can view them under the Services file:
ImportedServices

Then open the MerchandiseDB_Merchandise_create_service and delete an acl request parameter. As s result, the Body tab should look like this:DeleteACL

Add/map/invoke services: sign-in

Mapping login service

We are going to start with MerchandiseDB_login_service. When this service is invoked, the user signs into the app. A user is considered signed into the app when there is an active session token (returned by the service).

First, add the service to the page from DATA view:
login_serviceAdd

Rename the service instance to login.

Click “Mapping,” and define the following mapping action for Before send event:
BSEventMapping

Before you can invoke the service you’ve created, you’ll need to create a storage variable:

1. Project > Model and Storagand open the Storage tab.

2. Add a storage variable userSessionToken. Save.

Now you can create the following Success event mapping:
SuccessLoginMapping

userSessionId holds the current active session ID. This value is stored in the browser’s local storage.

There are two more things we need to do: handle a login failure, and if the login is successful, we need to navigate to the Merchandise page.

To handle a login failure, you’ll add a simple alert that will display an error message on the service’s Error callback:AlertIncorrectUsername

If the login is successful, you’ll navigate to the Merchandise page:MerchandiseSuccessfulLogin

From the DESIGN view, invoke the service upon “Sign In” button click.

Since we’ve created a sample user (Jane), we can now test the app. Launch the app in the browser and enter the credentials for the user you’ve created. If the login is successful, you’ll be redirected to the Merchandise page. If the login is unsuccessful, you should see an alert message.

Mapping signup service

We need to add and map the MerchandiseDB_signup_service.

First, add the service instance to the page and rename it to signup:AddSignUpService

Click “Mapping,” and define the following mapping action for Before send event:BSSignUpMapping

Create the following Success event mapping:
SuccesLogupMapping

In terms of the login service, you’ll need to handle invalid logins as well as successful ones.

If registration fails, the service returns an error message specifying why registration failed: for instance, a “user already exists” error message. To display the message returned by the service, go to the DATA tab, and add the following JavaScript on the service’s Error callback:

ErrorSignUp

If registration is successful, you’ll navigate to the Merchandise page:RegistrationSuccessful

From the DESIGN view, invoke the service on the “Register” button click.

Add/map/invoke services: Mdse.

Add three services to the Merchandise page:

  • MerchandiseDB_Merchandise_create_service – to add a new merchandise item for the signed-in user.
  • MerchandiseDB_Merchandise_list_service – to list all merchandise for the signed-in user.
  • MerchandiseDB_logout_service – to log out.

The following image shows all three service instances added to the page and renamed:3ServicesCreatedRenamed

Mapping item_add service

The first service you’ll create will add a new merchandise item to the collection.

After adding the service, create the following mapping action for Before send event:
BSCreateMapping

From the DESIGN view, invoke the service upon the “Add Item” button click.

To refresh items list once the new item was added you should add the following event on the  Merchandise screen > DATA tab:item_addSuccess

Mapping item_list service

When you list the merchandise, you’ll need to make sure you only show items for the current user. After adding the service to the page, create the following mapping action for Before send event:BSItem_list

Passing the current session ID ensures that only the objects owned by this user are returned by the service.

Create the following Success event mapping:
SuccessItem_list

You need to set the service to invoke on page show: Go back to DESIGN, open the EVENTS tab, then select Merchandise >Page Show > Invoke Service > item_list. Save.

Mapping user_logout service

The logout service invalidates the session ID, and requires the user to sign in again. After adding the service to the page, create the following mapping action for Before send event:
BSLogoutMapping

The service doesn’t return any data.

Invoke the service upon the “Logout” button click, and navigate to the Signin page on the service’s Success callback.

Testing the app

An optional step; you can configure the app so that all pages are rendered into one file. This increases app performance after the initial app load. Go to Project > App settings > General and check the “Render all pages in one HTML file” box:
RenderAllPages

Example: Signing in with the user, Jane, we created earlier, and adding a few merchandise items:
AddItemScreen

Example: Registering a new user, Steve:
RegisterNewUser

After signing up, Steve doesn’t have any items:
NewUserScreen

Adding merchandise items to Steve:
AddingNewItem

Error example: Trying to sign in with an incorrect password:
SignInFailure

Error example: Trying to register a new user with existing user name:
NewUserFailure

Users collection APIs

Learn more about Users collection APIs or try other tutorials via the links.