path: root/doc/enginio_overview.qdoc

/****************************************************************************
**
** Copyright (C) 2013 Digia Plc and/or its subsidiary(-ies).
** Contact: http://www.qt-project.org/legal
**
** This file is part of the documentation of Enginio.
**
** $QT_BEGIN_LICENSE:FDL$
** Commercial License Usage
** Licensees holding valid commercial Qt licenses may use this file in
** accordance with the commercial license agreement provided with the
** Software or, alternatively, in accordance with the terms contained in
** a written agreement between you and Digia.  For licensing terms and
** conditions see http://qt.digia.com/licensing.  For further information
** use the contact form at http://qt.digia.com/contact-us.
**
** GNU Free Documentation License Usage
** Alternatively, this file may be used under the terms of the GNU Free
** Documentation License version 1.3 as published by the Free Software
** Foundation and appearing in the file included in the packaging of
** this file.  Please review the following information to ensure
** the GNU Free Documentation License version 1.3 requirements
** will be met: http://www.gnu.org/copyleft/fdl.html.
** $QT_END_LICENSE$
**
****************************************************************************/

/*!
\page enginio-index.html
\contentspage {enginio-index.html}{Contents}
\nextpage Enginio Installation Notes and Prerequisites

\title Enginio Manual

This manual shows how to use the Enginio library in a Qt application.
Both C++ and QML applications are covered. The manual is also used when
integrating Enginio into an existing Qt project.

Enginio is a \l {http://en.wikipedia.org/wiki/Backend_as_a_service}
{Backend-as-a-Service} solution for simplifying backend development
of connected and data-driven applications.

\section1 Getting Started

First read the installation notes and prerequisites, then follow one
of the short tutorials for using Enginio, either with QT Quick or with
C++.

\list
\li \l {Enginio Installation Notes and Prerequisites}
\li \l {Getting Started with Enginio using Qt Quick}
\li \l {Getting Started with Enginio using C++}
\endlist

\section1 Reference documentation and examples:
\list
\li \l {Enginio C++ Classes and Examples}
\li \l {Enginio QML Types and Examples}

Enginio documentation is also available at the
\l {https://developer.qtcloudservices.com} {Qt Cloud Services}
website \l{http://engin.io/documentation/} {here}.

\endlist

\section1 Enginio Overview

The Enginio APIs have a general pattern that is useful to understand.
This section gives a short overview of the API concepts used
throughout the library.

Enginio is a client-side library for communicating with the server
at \l {http://engin.io}. Multiple \e backends can exist in each
server account. When communicating with the server, the backend is
specified by a \b {backend id}. When multiple users load an Enginio
application, the all use the same \b {backend id}.

\section2 Objects

Enginio provides several types of objects. These include users, user
groups, files, custom objects, and more. All communications with the
backend use \l {http://json.org} {JSON}. When using the QML API, JSON
objects are simply written inline. When using the C++ API, the
\l QJsonObject and \l QJsonValue classes are used.

Each JSON object in Enginio has the reserved properties \c id,
\c objectType, \c createdAt, and \c updatedAt. For example,
a custom object with no user-defined properties will look like
this in JSON:

\code
{
    "id": "51cdbc08989e975ec300772a",
    "objectType": "objects.todos",
    "createdAt": "2013-06-28T16:38:32.369Z",
    "updatedAt": "2013-06-28T16:38:32.725Z"
}
\endcode

But custom object types are normally augmented with user-defined
properties that contain the application-specific data. A user-defined
property can also contain a JSON object. For a more detailed description of
Enginio objects, see the \l{http://engin.io/documentation/overview/objects}
{Enginio Object documentation}.

\section2 Operations

The basic operations on objects are shown in the table below.
For a complete list of operations see the
\l [CPP] {EnginioClient} {EnginioClient for C++} or the
\l [QML] {EnginioClient} {EnginioClient for QML}.

\table
\header
\li Operation
\li Description
\li C++
\li QML
\row
\li create
\li Insert a new object into the database
\li \l [CPP] {EnginioClient::create()}
\li \l [QML] {EnginioClient::create()}
\row
\li query
\li Query the database
\li \l [CPP] {EnginioClient::query()}
\li \l [QML] {EnginioClient::query()}
\row
\li update
\li Update an object in the database
\li \l [CPP] {EnginioClient::update()}
\li \l [QML] {EnginioClient::update()}
\row
\li remove
\li Remove an object from the database
\li \l [CPP] {EnginioClient::remove()}
\li \l [QML] {EnginioClient::remove()}
\endtable

\note User and access control list management are also performed using
these same functions.

\section2 File Management

For file management, these operations are slightly different in that
files are always attached to objects and can only be accessed through
their objects. The Qt library provides convenient functions to upload
and download files.

*/

/*!
\page enginio-getting-started.html
\nextpage Getting Started with Enginio using Qt Quick
\previouspage {enginio-index.html}{Enginio Manual}

\title Enginio Installation Notes and Prerequisites

\section1 Installation Notes

Enginio is packaged with Qt beginning with Qt 5.2. When starting the
Qt installation, ensure that the Enginio component in the \e {Qt Cloud
Services} category is selected.

Enginio requires OpenSSL to be installed, except for iOS, where the
native SSL framework is used instead.

\note For Qt 5.2.0, Enginio comes in the online installer only.

\section1 Prerequisites

A Qt Account is required to use the
\l{https://console.qtcloudservices.com} {Qt Cloud Services}.  A Qt
Account can be created at \l{Qt Account Sign-up}.

To run an Enginio Client application to use
\l{https://console.qtcloudservices.com} {Qt Cloud Services},
the \c{backend id} of an Engino Data Storage Instance is required.

Sign in to \l{https://console.qtcloudservices.com/login} {Qt Cloud
Services} using the Qt Account. Under \uicontrol {Enginio Data
Storage} (EDS), press the \uicontrol {Launch instance} button to create
a new cloud instance. Enter the name for the new instance and select
a data center. Then press \uicontrol {Create}.

A dialog of the new instance appears showing the \uicontrol {General}
tab. Here the instance \uicontrol {Name}, \uicontrol {ID}, and
\uicontrol {Address} are shown. Select the \uicontrol {Environment}
tab to show the \uicontrol {EDS_BACKEND_ID} and the
\uicontrol {EDS_INSTANCE ADDRESS}. These values can be cut and pasted
into the examples where required.

\note Some of the examples have built-in \uicontrol {EDS_BACKEND_ID}s.

Select the \uicontrol {Configure} tab and press the \uicontrol {Open}
button. This opens the dashboard for the new instance in a new browser
tab. The dashboard is used for instance management.

These instructions are also found in
\l{https://developer.qtcloudservices.com/qtc/getting-started}
{Getting Started With Qt Cloud Services}. Reading the documentation at
\l{https://developer.qtcloudservices.com/} {Qt Cloud Services Developers}
is also recommended.

*/

/*!
\page enginio-qml.html
\nextpage Getting Started with Enginio using C++
\previouspage Enginio Installation Notes and Prerequisites

\title Getting Started with Enginio using Qt Quick
\brief Introduction to using Enginio using Qt Quick

\section1 Setup a Qt Quick 2 application project

Create a new  \l [QtQuick] {Qt Quick} {Qt Quick 2} Application.

Qt Creator can be used to create a template.
\uicontrol {File ⇒ New File or Project ⇒ Applications ⇒ Qt Quick 2 Application}

\section1 Initialize Enginio Client

To use Enginio's QML API, the Enginio library must be imported.
\badcode
import Enginio 1.0
\endcode

Initialize the \l [QML] {EnginioClient} with the \b {backend id} value, which can be copied from the Dashboard.

Go to \uicontrol{Dashboard ⇒ The Backend home-view ⇒ See ’Keys box’ ⇒ Copy backend id value}.

\code
EnginioClient {
    id: enginio
    backendId: "YOUR_OWN_BACKEND_ID"
}
\endcode

\section1 Store the First Object

Now an \e object can be stored with Enginio. First, create an \e object in JSON format and fill it with data as needed.
Then call create on the client with the JSON object as a parameter.

\code
Component.onCompleted: {
    var city = {
        objectType: "objects.city",
        name: "Helsinki",
        population: 606000
    };
    enginio.create(city);
}
\endcode

\l{Checking stored objects in the Dashboard}{Check the Enginio dashboard} for the newly created object.
*/


/*!
\page enginio-cpp.html
\nextpage Checking stored objects in the Dashboard
\previouspage Getting Started with Enginio using Qt Quick

\title Getting Started with Enginio using C++
\brief Introduction to using Enginio using C++

\section1 Setup Qt Application Project

To link to Enginio in a qmake-based project, add the line shown below
to the \c .pro file.

\badcode
QT += enginio
\endcode

\section1 Initialize Enginio Client

To use the Enginio library, the required library headers must be included.
\code
 #include <Enginio/Enginio>
\endcode
Then an \l EnginioClient must be instantiated. The client requires
a \c{backend id}, which can be copied from the Dashboard. Go to the
\l{https://dashboard.engin.io/}{Enginio Dashboard} and select a backend.
Copy the \b {backend id} value.

\code
QByteArray backendId("YOUR_OWN_BACKEND_ID");
EnginioClient *client = new EnginioClient;
client->setBackendId(backendId);
\endcode
For testing purposes, it is easiest to hardcode the \b {backend id} directly into application code.
However, this might not be always the best choice, and sometimes it might be beneficial
to put the backend configuration in a separate configuration file.

\section1 Storing the First Object

Create an object in JSON format and fill in the data:
\code
    QJsonObject city;
    city.insert("objectType", QString("objects.city")); // an object type is required for all objects in Enginio
    city.insert("name", QString("Oslo")); // other properties can be chosen freely
    city.insert("population", 624000);
\endcode

Create the object in the Enginio database by calling \l {EnginioClient::create()}:
\code
    client->create(city);
    connect(client, SIGNAL(finished(EnginioReply*)), this, SLOT(uploadFinished(EnginioReply*)));
\endcode
Note that the \l {EnginioClient::create()} {create()} method performs the actual asynchronous network communication.
Wait for completion by connecting to the \l{EnginioClient::finished()}{finished} and \l{EnginioClient::error()}{error} signals.

\l{Checking stored objects in the Dashboard}{Check the Enginio dashboard} for the newly created object.
*/


/*!
\page enginio-dashboard.html
\title Checking Stored Objects in the Dashboard
\previouspage Getting Started with Enginio using C++

When objects have been stored in the database using either the C++ or
the QML code, go to the \l{https://dashboard.engin.io/}
{Enginio Dashboard} and check the status there.

\list
\li Select the Objects view from the top navigation bar.
\li Make sure that \gui objects.city is selected in the type drop-down.
\li The list should now show a row for the object which was just uploaded.
\endlist
\image object_browser_first_city_object.png

For more information on how to interact with Enginio, read the \l EnginioClient documentation.
To get convenient access to objects stored in Enginio, consider using \l EnginioModel.
*/

/*!
\page tutorials.html
\title Enginio Tutorials

\list
\li \l {Enginio Installation Notes and Prerequisites}
\li \l {Getting Started with Enginio using Qt Quick}
\li \l {Getting Started with Enginio using C++}
\endlist
*/