/*
 * Copyright (C) 2013 Canonical, Ltd.
 *
 * Authors:
 *  Kevin Wright <kevin.wright@canonical.com>
 *
 * This program is free software; you can redistribute it and/or modify
 * it under the terms of the GNU Lesser General Public License as published by
 * the Free Software Foundation; version 3.
 *
 * This program is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 * GNU Lesser General Public License for more details.
 *
 * You should have received a copy of the GNU Lesser General Public License
 * along with this program.  If not, see <http://www.gnu.org/licenses/>.
 */

/*!
\page concepts.html
\title Design Concepts

This concept guide will describe a wide variety of U1Db-Qt functionality and usage. It will cover:

\list 1
    \li Overview of U1Db Documents and Databases
    \li Creating Documents and Databases
    \li Database keys and Document contents
    \li Listing docId values in a Database
    \li Retrieving Documents
    \li Searching and retrieving Documents by docId
    \li Modifying Existing Documents
    \li Document Functions
    \li Index expressions
    \li Querying an index
    \li Index functions
    \li Blending the U1Db-Qt plugin with QML and Javascript
    \li U1Db-Qt with QML Elements and Components
    \li Using U1Db-Qt with elements and components that support models
    \li Using U1Db-Qt with elements and components that do not utilize models
    \li Using a Document without a Database
\endlist

\section1 Brief Description of U1DB

U1DB is a database API for synchronised databases of JSON documents. It’s simple to use in applications, and allows apps to store documents and synchronise them between machines and devices. U1DB is the database designed to work everywhere, backed by the platform’s native data storage capabilities. This means that you can use u1db on different platforms, from different languages, and backed on to different databases, and sync between all of them.

\section1 What is the difference between U1DB and U1Db-Qt

U1Db-Qt is the QML implementation of U1DB. It is a QML plugin written in C++ and allows for creating and manipulating U1DB databases via a more declarative approach within a QML application.

            A Database is very simple to create. It only needs an id and a path where the file will be created. A Database is a model, which can be used by elements, such as the ListView further in this example.

            \qml
            U1db.Database {
                id: aDatabase
                path: "aU1DbDSatabase2"
            }
            \endqml

            A Document can be declared at runtime. It requires at the very least a unique 'docId', but that alone won't do anything special. The snipet below snippet demonstrates the basic requirements.

            In addition to this, this example displays text from the database for a specific docId and id key in a text area called 'documentContent. To update the text area at startup with either the default value or a value from the database the onCompleted function is utilized, which is also demonstrated below.

            \qml
            U1db.Document {
                id: aDocument
                database: aDatabase
                docId: 'helloworld'
                create: true
                defaults: { "helloworld":"Hello World" }

                Component.onCompleted: {
                    documentContent.text = aDocument.contents.helloworld
                }

            }
            \endqml

         It should be possible to use a document without a database, as demonstrated in this snippet. Additionally this document will use the concept of sub-keys, as exemplified by the "bookmarks" id key + contents. This example will attempt to use the bookmark document to store docId values from the database, which will be displayed in a ListView on the second tab of the application. The user will be able to select a value from the ListView and the first tab will be modified accordingly.

       \qml
       U1db.Document {
            id: aBookmarkDocument
            docId: 'bookmarks'
            create: true
            defaults: { "bookmarks": [{}] }
       }
       \endqml

                 The listDocs method retrieves all the docId values from the current database. In this demonstration the values are put into an array, which is then checked to locate the docId for the current and previous documents within the database.

               \code
               var documentIds = documentObject.database.listDocs()

               for(var i = 0; i < documentIds.length; i++){

                   if(documentIds[i]===documentObject.docId && i > 0){
                       return documentIds[i-1]
                   }
                   else if(documentIds[i]===documentObject.docId && i==0){
                       return documentIds[documentIds.length-1]
                   }

               }
               \endcode

                These steps demonstrate the creation of a temporary document, based on a copy of the global document. This will then be used to determine if there is already a document in the database with the same docId as the address bar, and additionally with a key id with the same name.

                \code
                var tempFieldName = addressBarText;

                var tempDocument = aDocument
                tempDocument.docId = addressBarText;

                var tempContents = tempDocument.contents
                \endcode

                \b{Note: For simplicity sake this example sometimes uses the same value for both the docId and the key id, as seen here. Real life implimentations can and will differ, and this will be demonstrated elsewhere in the example code.}

                    Here the contents of the temporary document are modified, which then replaces the global document.

                    \code
                    documentContent.text = 'More Hello World...';

                    var tempContents = {}
                    tempContents[tempFieldName] = documentContent.text
                    tempDocument.contents = tempContents
                    aDocument = tempDocument
                    \endcode

                In this instance the current document's content is updated from the text view. The unique key and docId are not modified because the database already contains a record with those properties.

                \code
                var tempContents = {}
                tempFieldName = getCurrentDocumentKey(aDocument.contents)
                tempContents[tempFieldName] = documentContent.text
                aDocument.contents = tempContents
                \endcode

                    Here a rectangle is defined that represents the lower portion of our application. It will contain all the main parts of the application.

                    \qml
                    Rectangle {

                         width: units.gu(45)
                         height: units.gu(70)
                         anchors.bottom: parent.bottom

                         color: "#00FFFFFF"

                         // The remainder of the main part of the application goes here ...

                         }

                     \endqml

                            The following TextArea is for displaying contents for the current state of the global document, as defined by the key / name in the address bar.

                            \qml
                            TextArea{

                                id: documentContent

                                selectByMouse : false

                                x: units.gu(1)
                                y: units.gu(1)
                                width: units.gu(43)
                                height: units.gu(58)
                                color: "#000000"

                            }
                            \endqml

                                        There is an object within in the 'aDocument' model defined earlier called 'contents', which contains a key called 'hello', which represents a search string.  In this example the key will represent the name of a document in the database, which will be displayed in the address bar. Displaying the key is demonstrated here:

                                    \qml
                            TextArea{
                                    text: displayKey(aDocument.contents)

                                    function displayKey(documentObject){

                                        var keys = Object.keys(documentObject);

                                        return keys[0]

                                    }
                            }
                                    \endqml
 */

