- Enginio Manual
- Enginio QML Types and Examples
- Enginio QML Examples - Social Todos
- Enginio 1.2.1 Reference Documentation

# Enginio QML Examples - Social Todos

## Introduction

Social Todos is a simple todo list application with a social twist, demonstrating the user management and access control features of the Enginio service. The application allows the end user to register a new user account, log in, and create and delete task lists, manage tasks on those lists and share lists with selected other users.

The application data is modeled as todo items and todo lists.

- A todo item represents a single tasks which needs to be done. Todo item contais a textual description of the task and a boolean status flag telling whether the task is completed or not.
- A todo list represents a list of tasks. Todo list contains zero or more todo items and each todo item belongs to just one todo list. Todo lists are created by the application end users. By default only the user who created a list can access it and its todo items. However, the creator can share the list with other users.

The Social Todos example uses the following Enginio features:

User management with integrated Enginio accounts | Enables end users to register and login. end users are identified by username and password.
Object storage | Provides shared persistent storage for task lists and tasks.
Data validation | Enforces required data structure for task lists and tasks.
Access control mechanisms | Restricts access to application data so that it is available only to authenticated (logged-in) end users. End users can see and manipulate only those task lists and tasks which they are entitled to.

To get the Social Todos application working correctly you will need to:

1. Create a new application backend via Enginio Dashboard.
2. Configure the backend as instructed in the Configure Backend section.
3. And then run the application as explained in the Configure and Run QML Application section.
4. Finally you can check the QML application details in QML Application Walk-through.

## Configure Backend

This section presents steps for configuring a fresh Enginio Backend for the Social Todos example. A big part of the backend configuration is related to restricting who can create and access the application data.

Data creation controls

Todo list and todo item creation is allowed for registered application users only. The protection is based on having a single usergroup (group name 'allUsers') in the backend configuration. Todo list and todo item creation rights are granted to members of this group. Application users are added to this usergroup when they use the QML application.

For built-in users and usergroups the creation control is handled slightly differently. New users can be freely created and thus anyone can register to use the application. Usergroups creation is completely blocked, since the application uses just one fixed usergroup.

Data access controls

Data access (and manipulation) to todo lists and todo items is allowed only for logged-in users. By default only the user who creates the todo list can access the list and its todo items.

However, the creator can share the list with other users. List sharing happens by granting the right to access the list to selected other users.

Access permissions are explicitly managed only for todo lists. Todo items are configured to inherit permissions from the todo list which they belong to.

For user objects, the access is allowed only to logged-in users which are members of 'allUsers' usergroup.

For usergroups objects, the access is allowed so that everyone can see the single fixed 'allUsers' usergroup.

### 1. Create 'allUsers' Usergroup

Create a new usergroup `allUsers`. The usergroup will be used to restrict that only registered application end users can store new todo lists and items to the backend. The usergroup itself is secured with suitable data access permissions.

First create the usergroup:

- In the Dashboard: Select Usergroups, click Add, enter name `allUsers` for the usergroup, and select Save.

Then secure the usergroup by configuring suitable permission settings:

- In the Dashboard: Open allUsers usergroup for editing, apply the configurations below, and finally select Save in usergroup editor.

Setting area | Required configurations |
--- | --- | ---

Object permissions

Configure the following permissions:

- Grant `read` permission to `all`.
- Clear other permission grants.

Object permissions control who can perform operations to `allUsers` usergroup.

In this case read-only access is given to everybody, so the QML application can read the `allUsers` data even when the application doesn't have any logged in user.

Member management permissions

Configure the following permissions:

- Grant `create` permission to `all`.
- Clear other permission grants.

Member management permissions control who can add new members to the `allUsers` usergroup or remove existing ones.

Now everyone can add members, and consequently the QML application can add the end user to the `allUsers` usergroup. However, since other permissions are not granted, usergroup members can not be listed or removed.

### 2. Create 'todoLists' Object Type

Create a new object type `objects.todoLists`. The object type defines the data schema and other settings for todo list objects.

Create the object type:

- In Dashboard: Select Object Types, click Add, enter name `objects.todoLists` for the object type, and select Save.

Then configure the object type with needed details:

- In Dashboard: Open objects.todoLists object type for editing, apply the configurations below, and finally select Save in object type editor.

Setting area | Required configurations |
--- | --- | ---

Properties

Add following property:

- `name`, with data type string

Properties are key/value pairs containing actual object data.

The '`name`' property will hold the name of the todo list.

Permissions

Configure following permissions:

- Collection permissions
  - Grant read and create permission to `allUsers` usergroup.
  - Clear other permission grants.
- Object permissions template
  - Grant admin permission to creator subject.
  - Clear other permission grants.

Collection permissions control who is able to create new `objects.todoLists` objects or list existing ones. Now those rights are granted to `allUsers` usergroup members.

Object permissions template define how object level permissions will be initially set for created `objects.todoLists` objects. Now admin permission will be granted to the user who creates the `objects.todoLists` object.

Admin right allows the user to perform all 'normal' operations on the `objects.todoLists` object (i.e. read, update and delete the object). Admin right allows the user also to manage object's permissions (i.e. grant and withdraw rights for other users).

### 3. Create 'todos' Object Type

Create a new object type `objects.todos`. The object type defines data schema and other settings for todo item objects.

Create the object type:

- In Dashboard: Select Object Types, click Add, enter name `objects.todos` for the object type, and select Save.

Then configure the object type with needed details:

- In Dashboard: Open objects.todos object type for editing, apply the configurations below, and finally select Save in object type editor.

Setting area | Required configurations |
--- | --- | ---

Properties

Add following properties:

- `title`, with data type string
- `done`, with data type boolean
- `todoList`, with data type ref and target `objects.todoLists`

Properties are key/value pairs containing actual object data.

The '`title`' property will hold the textual content for the todo item.

The '`done`' property is boolean status whether the item is done or not.

The '`todoList`' is a reference to parent todo list, i.e. a link to todo list object to which this todo item belongs to.

Reference constraints

Configure following reference constraint action:

- For `todoList` reference, setup cascade delete action.

Reference constraints are mechanism to enforce "exists" relationships between objects. Action specifies what is done when a referenced object is deleted. Cascade delete selection means that the referencing `objects.todos` object is also deleted in this case.

Permissions

Configure following permissions:

- Collection permissions
  - Grant read and create permission to `allUsers` usergroup.
  - Clear other permission grants.
- Object permissions template
  - Clear all permissions grants.
- Object permissions inheritance
  - Enable object permissions inheritance for `todoList` reference.

Collection permissions control who is able to create new `objects.todos` objects or list existing ones. Now those rights are granted to `allUsers` usergroup members.

Object permissions template define how object level permissions will be initially set for created `objects.todos` objects. Now object permissions template is left empty, because dynamic permission inheritance is used.

Object permissions inheritance enables inheriting object level permissions dynamically from referenced objects. Now permissions inheritance is enabled for `todoList` reference. Thus `objects.todos` object inherits its permissions from referenced `objects.todoLists` object.

### 4. Configure 'users' Object Type

Configure built-in `users` object type with needed security permissions. The `users` object type defines data schema and other settings for user objects, modeling application end users.

- In Dashboard: select Object Types, open users object type for editing, apply the configurations below, and finally select Save in object type editor.

Setting area | Required configurations |
--- | --- | ---

Permissions

Configure permissions and dynamic rules:

- Collection permissions
  - Grant create permission to `all`.
  - Grant read permission to `allUsers` usergroup.
  - Clear other permission grants.
- Object permissions template
  - Grant read permission to `allUsers` usergroup.
  - Grant admin permission to creator subject.
  - Clear other permission grants.

Collection permissions control who is able to create new `users` objects or list existing ones. In this case create right is granted to all, so anyone can freely register to application as a new user. However, listing of existing users is granted only to members of `allUsers` usergroup.

Object permissions template define how object level permissions will be initially set for created `users` objects. Read-only right is given to `allUsers` usergroup members, so registered users are able to see each other details for sharing purposes.

Now admin permission will be granted to the user who creates the `users` object, i.e. to user itself. Admin right allows the user to perform all operations on the `users` object (i.e. read, update and delete the object and also to manage its access rights).

### 5. Configure 'usergroups' Object Type

Configure built-in `usergroups` object type with needed security permissions. The `usergroups` object type defines data schema and other settings for usergroups objects.

- In Dashboard: select Object Types, open usergroups object type for editing, apply the configurations below, and finally select Save in object type editor.

Setting area | Required configurations |
--- | --- | ---

Permissions

Configure permissions and dynamic rules:

- Collection permissions
  - Grant read permission to `all`.
  - Clear other permission grants.
- Object permissions template
  - No changes.

Collection permissions control which users are able to create new `usergroups` objects or list existing ones. In this case listing rights are granted for everyone (i.e. those are publicly readable). Thus the QML application can locate the `allUsers` usergoup in the application startup phase, even before the end user logs in to the system. However, since create right is not granted to anyone, new usergroups can not be created.

Object permissions template define how object level permissions will be set initially for the created `usergroups` objects. Since new usergoups will not be created dynamically, there is no need to modify the permission template. Note that changes made in the permissions template will effect existing `usergroups` objects and thus the `allUsers` group as well.

## Configure and Run QML Application

## QML Application Walk-through

Files:

- socialtodos/Header.qml
- socialtodos/List.qml
- socialtodos/Login.qml
- socialtodos/ShareDialog.qml
- socialtodos/TextField.qml
- socialtodos/TodoLists.qml
- socialtodos/TouchButton.qml
- socialtodos/socialtodos.qml
- socialtodos/socialtodos.pro
- socialtodos/socialtodos.qrc