ShowTable of Contents
A representation of a Domino database that is stored on a Domino server. The Domino database needs to be reachable via HTTP or HTTPS.
The NotesDatabase is the root for other Notes objects like NotesView or NotesDocument.
If you work with NotesDocument objects (see below), changes or new documents are normally stored in a local queue of the NotesDatabase object to allow batch uploading and offline operation. You can flush the queue and upload all changes to the corresponding Domino database on the Domino server with the NotesDatabase.uploadChanges() method.
If NotesDatabase.upladOnNetworkChange is true (default), then all queued changes are uploaded automatically when the network status on the device changes from offline to online.
Creation
var db = new NotesDatabase(url, name);
With:
url: the HTTP or HTTPS url to the Domino database. Example: http://office4/web/youatnotes/wiki-xpages.nsf
name: a internal name, used for the local database. Example: "xpageswiki".
Notes:
You can also create a new NotesDatabase object with
var db = new NotesDatabase(name);
without giving an url if you plan to use the object only for working with local data. If you created the object without an url, you cannot use methods that read or write Data to the Domino server.
Properties
NotesDatabase.useDominoCommands
Set to true if your Domino Database does not contain the YouAtNotes Domiino To Go XPages and you want the framework to use the standard Domino URL commands like "?ReadViewEntires".
Using standard Domino commands is slower than using the YouAtNotes Domino To Go XPages and the following restrictions apply:
- views can be read to a maximum of 9999 entries
- multiple values in a column not support yet (only the first value will be used)
- items in documents must be of type string
- you can only set items that exists on the form of the Domino document when creating new documents or changing existing documents
Standard is false.
NotesDatabase.uploadOnNetworkChange
Set false to prevent automatic uploading of changes (new documents, changes to documents) when the network status changes from offline to online.
Standard is true.
Methods
NotesDatabase.createDocument()
Creates and returns a new NotesDocument. The UNID of new documents always starts with a hashtag '#', and NotesDocument.isNew() return true for new documents.
NotesDatabase.downloadDocumentsByUNID(unid, callback, skipitems, silent, failmessage)
Tries to download a document with the given UNID from Domino into the local cache.
If the document already exists in the local cache it will be overwritten.
With:
unid: the UNID of the document to download.
callback(success, e): (optional) a callback function with:
- success: true if the download was completed without errors.
- e: the error event where there was an error.
skipitems: (optional) an array of Domino document item names you want to exclude from the download.
silent: (optional) set to true for silent operation, that means no alert when there was an error (standard is false).
failmessage: (optional) a custom message if there was an error. Use %s as placeholder for the actual error message.
Notes:
You can check the data produced by the ynmobile_readdoc XPage by manually opening it in a browser with URL Parameters "unid" and "sk".
Example: http://testserver/dominotogo/contacts.nsf/ynmobile_readdoc.xsp?Open&unid=<some unid>&sk=form,type,zip
NotesDatabase.downloadDocumentsBySelection(select, callback, skipitems, silent, failmessage)
The same as above, but with the name of a view or a Domino formula to select which documents should be downloaded.
Notes:
You can check the data produced by the ynmobile_readdoc XPage by manually opening it in a browser with URL Parameters "select" and "sk".
Example: http://testserver/dominotogo/contacts.nsf/ynmobile_readdoc.xsp?Open&select=People&sk=form,type,zip
Example:
var db = new NotesDatabase("http://testserver/dominotogo/contacts.nsf", "contacts");
db.downloadDocumentsBySelection("People", function(success, e) {
if (success) YN.log("download successful."); else YN.log("download failed: "+e);
});
or
var db = new NotesDatabase("http://testserver/dominotogo/contacts.nsf", "contacts");
db.downloadDocumentsBySelection('SELECT form = "Person"', function(success, e) {
if (success) YN.log("download successful."); else YN.log("download failed: "+e);
});
NotesDatabase.getDocumentByUNID(unid)
Returns a specific NotesDocument (if it's present in the local cache). If the document does not exist in the local cache, null is returned.
With:
unid: the UNID of the document you want to get.
NotesDatabase.deleteDocumentsByUNID(unid)
Removes one or more documents from the local cache.
With:
unid: one UNID or an array of UNIDs of documents you want to delete.
Notes:
The deletion only occurs in the local cache, documents are not deleted on the Domino server.
NotesDatabase.getView(viewname)
Returns a NotesView.
With:
viewname: the name of the view you want to get.
NotesDatabase.uploadChanges(callback)
Tries to upload all queued changes (field changes, new documents) back to Domino. Returns immediately if there is no network available.
With:
callback(success, error or returnmsg): a callback function that is executed after the upload finished or if there was some error.
- success: true if the upload finished successfully.
- error: the error object in case of a httpClient error, or the string "no network" when there is no network available.
- returnmsg: the upload might finished successfully, but there might be a problem on the Domino side. If so, the returnmsg contains a message about the problem.
Returns:
true: if the upload request has been sent successfully (which does not need to mean that the upload itself was successfully fiinished, use the callback function to check that).
false: if there was no network.
Notes:
Uploading file attachments require NotesDatabase.useDominoCommands=false (XPages mode).
if you are working with NotesDatabase.useDominoCommands=true, you can use a second callback function:
NotesDatabase.uploadChanges(callback, callbackPerRequest);
The first callback function is called when all changes for all documents have been uploaded (since these changes may cover multiple Domino documents).
The seconds callback function is called each time after all changes for one document have been uploaded.
It accepts the following parameters:
callbackPerRequest(responseText, unid, url)
- responseText: the response received from Domino for the HTTP POST request
- unid: the UNID of the document the POST request has been made for
- url: the URL used for the request
You can use responseText to check if the response from Domino indicates that the document has been processed successfully.
If so, you need to return true to remove the uploaded document from the local update queue of the App. Otherwise, return false to let the App try to upload the data again at the next call of uploadChanges().
IMPORTANT!
If you have a callbackPerRequest callback function defined, BE SURE TO RETURN TRUE if the responseText indicates that the upload has been processed successfully by Domino. Otherwise, the data will remain in the local queue of the App and will be uploaded again and the next call of uploadChanges().
Note that this is only neccessary when you set NotesDatabase.useDominoCommands option to true.
Examples
var db = new NotesDatabase('http://testserver/dominotogo/contacts.nsf', 'contacts');
var doc = NotesDatabase.createDocument();
var doc2 = NotesDatabase.getDocumentByUNID(unid); // get UNID for example from a view entry's column "id"
doc.replaceItemValue("lastname", "sisko");
doc.save();
doc2.replaceItemValue("lastname", doc2.getItemValueString("lastname")+"TEST");
doc2.save();
db.uploadChanges(function(success, e){
if (success) YN.log("upload successful"); else YN.log("upload failed: "+e);
})
|