Subscribe via Feed

XPage Cheat Sheet #2 - DataSource and NotesXspDocument

Peter Presnell, Nov 6, 2009 6:32:18 AM

In my last blog I did an update on the XPage Lifecycle.  The next blog in this new series will cover some of the basics about DataSources and the new NotesXspDocument object/class.  This is targeted at those people like me making a transition from LotusScript to the new world of XPages and SSJS.

With Notes Classic the data model was quite simple.  Notes databases contained a collection of Notes Documents.  These were represented in LotusScript via the NotesDocument class.  The Form was the design element used to display and maintain these documents.  While it was possible to bring in data from other documents there was usually a very strong one to one relationship between the Form and a Document.  So strong that it was often impossible to separate the two.


With XPages we are now starting to see a stronger separation between the data layer and the presentation layer.  Data is now (typically) bound to an XPage using one or more DataSources.  The most common DataSources are the Notes Document and the Notes View.  In the future there are plans to support a much wider range of DataSources including XML, JSON (I assume), and Relational Databases.  (You can do this now using a few tricks).


When using Notes Classic to develop applications for the Notes client most of your code is executed on the client with LotusScript able to maintain a continuous exchange with the server.  With the Web model used by XPages it is either not possible or not practical for the Domino server to keep the NotesDocument objects open for the life of a transaction.  This has given rise to the creation of a new NotesXspDocument object which acts as a buffer between Web Page and the NotesDocument objects holding the data. The NotesDocument object only has a life as long as a single trip to the server.  The NotesXspDocument however stays with the XPage as it travels back and forward between the server and the client.

For each DataSource that is linked to a Notes Document on either an XPage or a Custom Control a global SSJS variable is assigned that matches the name assigned to the DataSource.  This variable is an SSJS object of this new type - NotesXspDocument.  The NotesXspDocument is still tied to a NotesDocument but there are some important differences. 

When creating a Notes Document Data Source you are usually asked to connect to an existing form in this (or another database).  As best as I can tell the form selected is significant for just two purposes:-

  1. It determines the list of fields that will be displayed in the data palette.  This can be useful, but if you know the names of the fields you are working with it is not needed;
  2. When a new document is saved the Form name assigned to the document will be that of the selected form (unless you manually assign a value to the field "Form").

Custom Controls & NotesXspDocuments

If your XPages are designed with CustomControls, care needs to be taken to avoid the possible scenario of a separate NotesXspDocument being created for the XPage and each Custom Control.  I have had all manner of troubles trying to share data between my XPage and Custom Controls until I started to understand what was going on.  e.g. A save action on my Xpage would create five new documents!  If your Custom Controls are designed to maintain data in the same Notes Document then it is usually a good idea to share the one NotesXspDocument between the XPage and these controls. 

  1. John Mackey has previously blogged about Passing the NotesXspDocument as a parameter to a Custom Control.
  2. Another technique (also covered by John) is to use the global variable currrentDocument.  This is a NotesXspDocument object that references the first Notes Document data source assigned to the parent XPage.  On the custom control use Advanced Data Binding and Expression Language to enter currentDocument.fieldname to bind the control to a specific field in the first Notes Document DataSource on the parent XPage.  This may not work if you have multiple DataSources bound to the XPage because it seems to always take the first one listed.  Note: The list of DataSources is maintained in alphabetical order so its not even the first DataSource you create that gets assigned!

Using the above it becomes possible to assign the same field to multiple edit controls either on different Custom Controls or even the same XPage/Custom Control.  If this happens the data entered in the last edit control is the one that is always returned to the NotesXspDocument.  After a refresh the other controls will loose their values and display the value entered in this last edit control.

NotesXspDocument & NotesDocument

It appears that during the initial PageLoad events the existing data is transferred from the NotesDocument to the NotesXspDocument.  Only those fields bound to the NotesXspDocument (on XPage or CC) are transferred.  This does include bound controls that are not rendered (visible).  This same data is then transferred back to the NotesDocument when method is invoked.  Alternatively you can manually manipulate the NotesDocument object using SSJS.

Note: If you were to perform a save on a newly created document using the NotesDocument via NotesXspDocument.getDocument().save() you will probably find a document saved with a single field (Form) and none of the data entered on the XPage.

Also note that if you pass the NoteID or UNID to a Custom Control you will bind to the same NotesDocument but most likely create a separate NotesXspDocument.

On-Line Demonstration

To illustrate some of the above I have created an on-line demo in the new XPages Kindergarten section of the .Domino Framework:

3 responses to XPage Cheat Sheet #2 - DataSource and NotesXspDocument

Dharmesh Bhakta, January 18, 2011 5:38 PM

Hi! Thanks for the post. Can you please provide me more details on this "In the future there are plans to support a much wider range of DataSources including XML, JSON (I assume), and Relational Databases. (You can do this now using a few tricks)." I would like to use the Notes View container control but would like to get the data from relational database instead of view datasource. Is it possible? Any information will be greatly appreciated. Thank you.

Matt White, November 6, 2009 8:45 PM

Another way of getting data from the XspDocument to the NotesDocument without a save, is to use document1.getDocument(true) which basically re-syncs the data between the two objects.

Gerald Mengisen, November 6, 2009 2:21 PM

Thanks so much for this series, it's easy to read and grasp!