ShowTable of Contents
Represents the local cached version of a Domino document.
Creation
A new, empty document is created with NotesDatabase.createDocument() with code simiilar to this:
var db = new NotesDatabase(...);
var doc = db.createDocument();
A new document is empty and does not contain any data.
You can use the replaceItemValue() method to set data to items (fields). Use NotesDocument.save() to store the data in the queue of the curresponding NotesDatabase.
Use NotesDatabase.uploadChanges() to push the data to Domino.
You can get an existing document by it's UNID with:
var db = new NotesDatabase(...);
var doc = db.getDocumentByUNID(<unid>);
Properties
items
Returns an object list of items with the item names as keys. You can iterate over all items with code like this:
for (e in doc.items) {
YN.log("item name="+e+" value="+doc.items[e]);
}
Methods
getAttachment()
(work in progress)
Since:
Version 1.2
Notes:
Requires the Domino To Go XPages in the NSF.
getUniversalID()
Returns:
The universalID of this document (a 32 digit hex string which is a unique identifier for the document).
getParentDatabase()
Returns:
The NotesDatabase object the document belongs to.
isDeleted()
Returns:
true if the document has been removed with the .remove() method.
Since:
Version 1.2
isNew()
isNewNote()
Returns true if the document is new, that means it has been created in the mobile App using NotesDatabase.createDocument().
NotesDocument.isNewNote() is only an alias for NotesDocument.isNew() to make the API more friendly to Domino developers.
isValid()
Returns true if the document has a valid UNID and has not been deleted. There might be situations were Domino delivers documents without a UNID, and in that case this method would return false.
getItemValueString(itemname)
Reads the value of an item stored in the document.
With:
itemname: the name of the item for which you want to read the value.
Returns:
The value of the given item.
remove()
Removes the document from the local cache (not from the Domino NSF database).
If there were any attachments downloaded for this document, they will be deleted from the local file system of the mobile device, too.
Since:
Version 1.2
removePermanently()
Removes the document form the local cache (including attachments) and from the Domino NSF database.
This method creates a notification for Domino to delete the document from the NSF database. This notification will be uploaded to Domino in the next NotesDatabase.uploadChanges() call, then the document will be removed from the NSF database if the user has approprate rights. If user does not have appropriate rights, then the document will not be deleted. There is no notification back to the mobile device if that happens.
Since:
Version 1.2
Notes:
Requires the Domino To Go XPages in the NSF.
replaceItemValue(itemname, value, itemtype)
Sets the value for an item. If the item does not exist, it's created automatically.
With:
itemname: the name of the item you want to set.
value: the value you want to set as a string or array of strings. Use the optional 'itemtype' parameter for defining the type the value should become in the target Domino document.
itemtype: (optional, not supported in useDominoCommands mode) a string indicating the type for this item in the target document in the Domino database:
- "string" (default)
- "number"
- "datetime"
- "reader"
- "author"
save(uploadImmediately, saveAsUNID)
Saves the changes to the document in the local update queue. Use NotesDatabase.uploadChanges() to push the changes back to Domino.
With:
uploadImmediately: (optional) set to true if you want to try to upload the changes immediately to Domino (instead of calling NotesDatabase.uploadChanges() at another time).
saveAsUNID: (optional) set to a UNID to save the changes to a specific Notes document. Useful if you don't have a Notes document downloaded, but you want to upload changes to a document. If so, you can get a new document with NotesDatabase.createDocument(), set values with NotesDocument.replaceItemValues() and save these values to a specific document with NotesDocument.save(true or false, unid).
Notes:
You can use NotesDocument.save(true) to try to upload changes to Domino immediately. This works even when the device is offline, in that case the changes are stored in the local queue. The queue will be uploaded automatically to Domino if the device goes online again when the uploadOnNetworkChange property of the corresponding NotesDatabase object is true (standard).
setAttachment(localfile, itemname)
Attaches a file to the cached version of the document and uploads the file to the NotesDocument in Domino at the next synchronization.
With:
localfile: the local path and filename (pointing to the Apps' applicationDataDirectory) of the file.
itemname: the item name for the NotesDocument in which the file should be stored on the Domino side.
Notes:
Upload size limits apply as follows:
- if the device has LAN / Wifi: 20MB
- otherwise: 10MB
These limits are stored in NotesDatabase.UPLOAD_MAX_SIZE_MOBILE and NotesDatabase.UPLOAD_MAX_SIZE_LAN. You can change the limits if needed for a NotesDatabase object.
The timeout of the HTTP upload process is determined automatically depending on the file size and if the device has LAN/Wifi or mobile network. A log message tells you about the timeout value used for each file upload.
On the Domino side, the files are stored in a MIME item. For that reason, the Notes item defined by "itemname" must not exist or if it already exists, it must be a MIME item. It the Notes item has another type, the file will not be stored. If that happens, a log message on the Domino console will tell you about it.
You can use NotesDocument.setAttachment() multiple times to attach multiple files to the same document. Files are uploaded one after the other. If the upload process fails, files that has not been uploaded yet will be uploaded at the next synchronization.
If a file with the same filename already exists in the NotesDocument on the Domino side, it will be removed and overwritte by the new file.
Since:
Version 1.2.
Examples
// create a new document and store it to the local update queue
var db = new NotesDatabase("contacts");
var doc = db.createDocument();
doc.replaceItemValue("firstname", "Benjamin");
doc.replaceItemValue("lastname", "Sisko");
doc.save();
Hooks for custom SSJS Code
There are some hooks in the ynmobile_custom SSJS library where you can place your own code to modify documents or data.
custom_write(doc)
This function is called from ynmobile_write after the XPages received data from the mobile device and processed the data to a NotesDocument, but before the document is saved.
You can modify the document here, and you don't need to save it since it's being saved automatically if this function returns true.
custom_readdoc_beforeExport(doc)
This function is called from the ynmobile_readdoc XPage before a document is being converted to DXL and writte to the mobile device.
You can modify the document to your needs, for example changing item values.
If this function returns null, the document will be skipped.
custom_readview(data)
This function is called from the ynmobile_readview XPage before a view entry is written to the mobile device.
It received an array of column values for a view entry. You can modify the array as needed, but you should leave the number of elements in the array intact.
Futhermore, the array must contain only string values.
If this function returns null, the view entry will be skipped.
|