1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
|
/*
* 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
*/
|
