diff options
Diffstat (limited to 'examples/enginio/quick/users/doc/src/users.qdoc')
| -rw-r--r-- | examples/enginio/quick/users/doc/src/users.qdoc | 54 |
1 files changed, 34 insertions, 20 deletions
diff --git a/examples/enginio/quick/users/doc/src/users.qdoc b/examples/enginio/quick/users/doc/src/users.qdoc index 1420e60..f319c0d 100644 --- a/examples/enginio/quick/users/doc/src/users.qdoc +++ b/examples/enginio/quick/users/doc/src/users.qdoc @@ -28,14 +28,14 @@ /*! \title Enginio QML Examples - Users \example users - \brief The Users example introduces user registration, authentication and browsing. + \brief The Users example introduces user registration, authentication, and browsing. \ingroup enginio-qml-examples \inmodule enginio-qml \section1 Introduction This example will demonstrate how to register and authenticate a user, and what kind of information - is attached to an authenticated session. This is a simple example and data access rights + is attached to an authenticated session. This is a simple example, and data access rights management is not covered here. For such information, please refer to the Social Todo example. \image users-example.png @@ -44,71 +44,85 @@ structures, which are the same for every backend. The example is an application that shows users registered in the backend, allows registration of - new users and shows how to login in separate tabs. + new users, and shows how to login in separate tabs. Each backend contains the "users" object type, which defines a structure that stores all basic data about an application's users. The collection of "users" is not - really different from any other collection, therefore we do not need any special + really different from any other collection. Therefore, we do not need any special methods to manipulate it. Typical data associated with a user is: \list - \li username - required name used for logging in. - \li email - unique email address of a user. - \li firstName, lastName - user's credentials (optional). - \li password - write-only property, this value is used during authentication. + \li \c username - required name used for logging in. + \li \c email - unique email address of a user. + \li \c firstName, lastName - user's credentials (optional). + \li \c password - write-only property, this value is used during authentication. \endlist - The "users" object can be extended by custom properties, too. + The \c users object can be extended by custom properties too. \note \e username and \e password are always required and cannot be empty. - \section1 General example structure - This example uses QtEnginio library together with QtQuickControls, therefore both have + \section1 General Example Structure + + This example uses QtEnginio library together with Qt Quick Controls, therefore both have to be imported. + \snippet users/Browse.qml imports + We will also use a common \l {Enginio::EnginioClient}{EnginioClient} connection as shown here: + \snippet users/users.qml client - The example is organized into separate tabs by using \l TabView. Each tab shows different + The example is organized into separate tabs by using \l TabView. Each tab shows a different functionality. - \section1 Browsing users' data + \section1 Browsing User Data + The most convenient method to browse users is to use \l{Enginio::EnginioModel}{EnginioModel}. The model can automatically download all data that we need. It is sufficient to set three properties: \l{Enginio::EnginioModel::client}{client}, \l{Enginio::EnginioModel::query}{query} and \l{Enginio::EnginioModel::operation}{operation} as shown below: + \snippet users/Browse.qml browse The model is used directly by TableView, in which we define data that will be shown. + \snippet users/Browse.qml columns - \section1 User authentication - Authentication is quite easy. The only thing that needs to be done is to assign an identity, for example + \section1 User Authentication + + Authentication is quite easy. The only thing that needs to be done is to assign an identity, for example, \l{EnginioOAuth2Authentication}{EnginioOAuth2Authentication} object to \l{EnginioClient::identity}{EnginioClient::identity}. After a while, \l{EnginioClient::authenticationState}{EnginioClient::authenticationState} will change and \l{EnginioClient::sessionAuthenticated}{sessionAuthenticated} or \l{EnginioClient::sessionAuthenticationError}{sessionAuthenticationError} will be emitted. The first thing we need to do is to create an identity object: \l{EnginioOAuth2Authentication}{EnginioOAuth2Authentication} + \snippet users/Login.qml identity Then, depending on the state of the application, we assign the object to our enginioClient instance. There are four possible states, defined by \l{Enginio::AuthenticationState}. After assigning the Identity object, - the state changes from the initial "NotAuthenticated" to "Authenticating". + the state changes from the initial \c NotAuthenticated to \c Authenticating. + \snippet users/Login.qml assignIdentity - Once the authentication query finishes, the state changes to "Authenticated" or - "AuthenticationFailure" depending on the authentication result. Null + Once the authentication query has finished, the state changes to \c Authenticated or + \c AuthenticationFailure depending on the authentication result. Null assignment to the \l{EnginioClient::identity}{identity} causes the session to terminate immediately: + \snippet users/Login.qml assignNull For educational purposes, in the example we also show a log window with data attached to a session that is changing state. + \snippet users/Login.qml connections - \section1 Registering a new user - Registration of a new user is as simple as adding a new object to the "users" collection. It can be achieved + \section1 Registering a New User + + Registration of a new user is as simple as adding a new object to the \c users collection. It can be achieved by using the \l{EnginioClient::create}{create} function, as shown below: + \snippet users/Register.qml create We could also use the \l{Enginio::EnginioModel::append}{EnginioModel::append} method in the browsing example |