U1db.concepts

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

  1. Overview of U1Db Documents and Databases
  2. Creating Documents and Databases
  3. Database keys and Document contents
  4. Listing docId values in a Database
  5. Retrieving Documents
  6. Searching and retrieving Documents by docId
  7. Modifying Existing Documents
  8. Document Functions
  9. Index expressions
  10. Querying an index
  11. Index functions
  12. Blending the U1Db-Qt plugin with QML and Javascript
  13. U1Db-Qt with QML Elements and Components
  14. Using U1Db-Qt with elements and components that support models
  15. Using U1Db-Qt with elements and components that do not utilize models
  16. Using a Document without a Database

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.

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.

U1db.Database {
id: aDatabase
path: "aU1DbDSatabase2"
}

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.

U1db.Document {
id: aDocument
database: aDatabase
docId: 'helloworld'
create: true
defaults: { "helloworld":"Hello World" }
Component.onCompleted: {
documentContent.text = aDocument.contents.helloworld
}
}

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.

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

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.

        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]
}
}

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.

         var tempFieldName = addressBarText;
var tempDocument = aDocument
tempDocument.docId = addressBarText;
var tempContents = tempDocument.contents

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.

             documentContent.text = 'More Hello World...';
var tempContents = {}
tempContents[tempFieldName] = documentContent.text
tempDocument.contents = tempContents
aDocument = tempDocument

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.

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

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

             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 ...
}

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.

                     TextArea{
id: documentContent
selectByMouse : false
x: units.gu(1)
y: units.gu(1)
width: units.gu(43)
height: units.gu(58)
color: "#000000"
}

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:

                     TextArea{
text: displayKey(aDocument.contents)
function displayKey(documentObject){
var keys = Object.keys(documentObject);
return keys[0]
}
}