Introduction

The Ionic tutorial provides step by step instructions that will walk you through the process of developing an application with offline capabilities. You will also learn how simple it is to use the Appery.io App Client to add powerful caching functionality to your apps.

🚧
Important Note!
Note that the option of creating new apps with the Ionic framework was removed but we still support the projects that were created with it earlier.

The tutorial is divided into two parts: basic (part 1) and advanced (part 2). You should complete the basic tutorial first and then move to the advanced tutorial. The advanced tutorial starts where the basic tutorial ended.

Target Audience

This tutorial is for advanced developers who have prior experience building apps with Appery.io.

Tutorial Format

The tutorial is organized in the following way:

Each chapter (section) describes one particular feature. At the end of each section, you will find a link to the archive with the backup of the project, so you can start using the guide at any point without having to complete the previous steps of the tutorial.
The only prerequisite is to import the backup from the previous section.
At the end of each section, you will find more resources that will provide additional details about Appery.io features and the Client SDK.
Each Appery.io Client SDK method mentioned in the guide will be linked to the corresponding section of the SDK reference.

App You are Building

This tutorial will walk you through the process of creating a Notebook mobile app. The key features of the app:

Authentication.
Ability to work without internet connection with synchronization.
Conflicts resolving in case of failed synchronization.

Step 1: Creating Database

The first step is to create the database where the notes will be stored.

Create a new Appery.io database with Name : ApperyNoteDB.
Create a collection with Name: Notes.
Add a column with Name: content and type : String.
Add a column with Name: deleted and type : Boolean.
Fill the first row with a content equal to note1.

Download and Resources

You can download database backup file from this step to import it to your app.
Appery.io Database documentation.

Step 2: Creating Database Connection

To create a database connection in API Express which will refer to Appery.io database:

Go to API Express > Create new DB connection.
Create a database connection with:

Name : ApperyNoteDBConnection
Connection type : Appery.io database
Database name : ApperyNoteDB

You don’t need to enter a username or password.
Make sure that the connection is successful, click Test.

Download and Resources

Step 3: Creating API Express Project

To create an API Express project and services for Notes collections:

Create an API Express project with the name ApperyNoteProject:

Create a Service group (click new service). Name it notes.
Select Generate REST API.
Select the ApperyNoteDBConnection Database connection.
Select the Notes table.
Check Data Synchronization checkbox
Check Deleted for deleted field
Click Generate service.

You can click the Test link to open the test page and invoke services from the just created Service group.

Download and Resources

Download API Express project backup file from this step.

Step 4: Creating Ionic App

To create a new Ionic app:

Navigate to Apps (App Builder), click Create new app.
Create a new application:

Name it ApperyNote.
Specify the Ionic Type.

Download and Resources

Download Ionic app backup file in this step.

Step 5: Generating Services to Connect to the Database

Once you have an app created, the next step is to generate services for the database to fetch and save data. To generate services that perform basic operations in the app:

Click CREATE NEW and select API Express Generator.
Select Appery.io as the host.
Next, select the ApperyNoteProject project.
Generate generic services for notes service (press generate) and name them NoteService.
Press the Refresh button to refresh the App Builder.

Download and Resources

Download Ionic app backup file from this step.

Step 6: Creating the Notes Page

To create a page which shows notes from collection Notes:

Rename Screen1 to Notes.
Open Routing.
Rename the route name Screen1 to Notes.
On the Notes page, click SCOPE and add a new function loadData:

Apperyio.get("NoteService_find")({}).then( 
    function(success) {
        $scope.notes = success;
        $scope.$apply();
    },
    function(error) {
        console.log(error);
    },
    function(notify) {
        console.log(notify);
    });

Open the init function (click edit) and modify it to:

$scope.loadData();

In DESIGN view, add a List component to the Notes page.

Remove two last items from the List.
Add the ng-repeat directive for the ListItem and define it as note in notes.
Set the Item text to:

{{note.content}}.

Press refresh (CTRL + F5) button several times with open network tab of browser. To notice how many times application loads the same data.
Modify init function.

Apperyio.get("Notes_fetch")({}).then( 
    function(success) {
        $scope.loadData();
    },
    function(error) {
        console.log(error);
    },
    function(notify) {
    });

Update loadData function

Apperyio.get("Notes_find")({"cached": true}).then( 
    function(success) {
        $scope.notes = success;
        $scope.$apply();
    },
    function(error) {
        console.log(error);
    },
    function(notify) {
    });

Press the refresh button several times. To notice that response of fetch operation is empty.
Add in database new record with content: .note2 .
Pay attention that the response of fetch operation contains only one record with content: note2. Application load only changed data

📘
Tip
To test your app add another note to the Notes collect and click TEST in App Builder.

Result in This Step

Your app now displays records from the database.

Download and Resources

Download Ionic app backup file from this step.

Step 7: Creating the Note Page

The Notes pages display all the notes from the database. The new Note page you will create in this step will allow you to add a new note and save it into the database.

To create the page:

Add a Button to the top of the Notes page. The button will forward the user to the Note page (this page will be created in step 3).

Set the Text property to Add.
Set thenavigate-to property to Note .

Now, create a new page and name it Note. The page will display note information.
Add a Button to the page. This Back button will return a user to the Notes page without saving a note.

Text : Back.
Add back-button property.

Add another Button . This Save Button will return a user to the Notes page with saving a note.

Set the Text to Save and ng-click to save()

Add an Input with ng-model set to content.
Add isNew function

return Apperyio.get("$routeParams")._id == ":_id";

Add getNoteId function

return Apperyio.get("$routeParams")._id;

Modify init function.

if (!$scope.isNew()) {
        Apperyio.get("Notes_get")({"_id": $scope.getNoteId(), "cached": true}).then(
        function(success){ 
            $scope.content = success.content;
            $scope.$apply();
        },
        function(error){
            console.log(error);
        },
        function(notify){ 
        });
}

Add a scope function, name it save.

var operation;
var requestObject = {"content": $scope.content};

if ($scope.isNew()) {
    operation = Apperyio.get("Notes_create"); 
} else {
    operation = Apperyio.get("Notes_update");
    requestObject._id = $scope.getNoteId();
}

operation(requestObject).then( 
        function(success) {
            Apperyio.navigateTo("Notes");
            $scope.$apply();
        },
        function(error) {
            console.log(error);
        },
        function(notify) {
  
        });

Result in This Step

The app now displays and adds records.

Download and Resources

Download Ionic app backup file from this step.

Step 8: Editing a Note

Now you can extend the app to allow editing existing notes.

On the Notes page, select the List Item in List.
Add ng-click directive and define it as edit(note._id).
Add a scope function, name it edit and pass _id for its Arguments. Then, insert this code:

Apperyio.navigateTo("Note", {"_id": _id});

Open Routing and update the path of the Note route to /Note.html/:_id.
Select the List Item of the List component.
Press the + button.
Select Button.
Remove the text from the button.
Specify Icon of the button as ion-trash-b.
Specify ng-click: remove(note._id, $event).
Add a new scope function remove with arguments : ._id, $event.

Apperyio.get("Notes_delete")({
    "_id": _id
}).then(
    function(success) {
        $scope.loadData();
    },
    function(error) {
        console.log(error);
    },
    function(notify) {
    });
$event.stopPropagation();

Download and Resources

Download Ionic app backup file from this step.

Step 9: Adding Security

To secure the Notes collection and API Express project ApperyNoteProject and to add Login page to the NoteApp:

Open Appery.io Databases ApperyNoteDB.
Open Collection Notes.
Open Security and permissions.
Enable Secure collection and save.
Open Users collection.
Add two users:

Username user1 password pass1.
Username user2 password pass2.

Open Change default ACL of Notes collection.
Specify default value @Creator.
In the top navigation bar click Resources.
Open Security sub-tab.
Add a new security provider:

Name it ApperyNoteSecurity.
Provider type Appery.io Database Security.
Appery.io database ApperyNoteDB.
Test and save it.

Open API Express and then ApperyNoteProject.
Open the Settings tab.
Enable the Secure REST API option.
Specify security provider as ApperyNoteSecurity.
Open Apps and select the ApperyNote app.
Add a new page, call it Login.
Add an Input component:

Placeholder : Username.
ng-model : username .

Add another Input component:

Set Placeholder : Password.
Define ng-model as password.
Select Type : password.

Add a button:

Text : Login.
ng-click : login().

Add a scope function login:

Apperyio.get("AppClientLogin")({
    username: $scope.username,
    password: $scope.password
}).then(
    function(success) {
        Apperyio.navigateTo("Notes");
        $scope.$apply();
    },
    function(error) {
        Apperyio.get("$ionicPopup").alert({
            title: 'Authentication error',
            template: "Username or password is incorrect"
        });
    },
    function(notify) {
        console.log(notify);
    });

Open Routing.
Select Login as default Route.

Download and Resources

Download Ionic app backup file from this step.

Step 9.1: Adding Signup page

Add a new page, call it Signup.
On Login page add Loren ipsum component.

Text Signup.
Container a.
navigate-to Signup.

On Signup page add an Input component:

Placeholder : Username.
ng-model : username .

Add another Input component:

Set Placeholder : Password.
Define ng-model as password.
Select Type : password.

Add a button:

Text : Signup.
ng-click : signup().

Add a scope function signup:

Apperyio.get("AppClientSignUp")({ 
    username: $scope.username,
    password: $scope.password
}).then(
    function(success) {
        Apperyio.navigateTo("Login");
        $scope.$apply();
    },
    function(error) {
        Apperyio.get("$ionicPopup").alert({
            title: 'Signup error',
            template: "Username or password is incorrect"
        });
    },
    function(notify) {
        console.log(notify);
    });

Add Loren ipsum component.

Text Login.
Container a.
navigate-to Login.

Result in This Step

The app has two pages Login and Signup and user can create account from application. Pay attention that after signup it is required to perform Login.

Download and Resources

Download Ionic app backup file from this step.