Data binding in XPages

Data Binding is the process by which a control on an XPage is configured so it can write/read data to/from a Notes database. After reading this article the reader will have a clear understanding on how to do simple data binding for XPage enabled applications.

Background
Before the introduction of XPages Domino Designer users did not need to worry about 'data binding' as the process of saving and retrieving data to/from a particular location within the database was taken care of automatically by Notes and Domino. Basically in a Notes form once the application designer creates a field within a form, Notes takes care of saving/retrieving the information entered into that field by the end user. With the introduction of XPages Domino Designer now gives the application designer a way of separating the data and presentation layers of their applications. However with this flexibility also comes a degree of complexity in that the application designer now has to consider where the data that the user enters is going to be stored, and how it will be retrieved.
Fortunately Domino Designer makes the process of data binding in XPages as simple as possible, without the application designer losing the power to make very complex data bindings in a relatively short time using the click and pick UI in the XPages' controls' properties panels.

Binding XPage controls to existing Notes Form fields
In this article I will outline several different data binding techniques that should give the Domino Designer user a good feel for what changes are required to an XPage to save/retrieve existing Notes data. As a prerequisite to this article, and in order to follow the step by step instructions the user should first create a new Notes application using the blank template (to see the XPages running in a local application in a browser you will need modify the application's ACL to provide Anonymous with Author access and also provide Anonymous with the ability to create documents ).
For the purposes of this article I will start by showing how to save to an existing Notes form. In this example we basically have a simple sample contact form that allows the end user to input contact information about individuals into their Notes application. The form when opened in Domino Designer looks something like the following:


As you can see this is a really basic form. In this case we would like to create an XPage through which the end user can enter data which will be saved to the fields outlined above (firstName, lastName, street, city, state, etc...). To do this we first create an XPage, in my example I named it xpContact. (To create an XPage (similar to how you would create a form), double click on the XPage design element in the navigator and choose to create a new XPage from the design list editor which appears in the middle of the Domino Designer window)

Once the XPage is created the first task that must be completed is to set up a "link" between the XPage and the contact form. To do this we must add a Data Source to the XPage. Adding a data source to an XPage is a trivial task. With focus on the body of the XPage (as opposed to focus being on a specific control) the user simply has to activate the Data tab in the properties view at the bottom of the Domino Designer client:


Once the Data tab has been activated next the user clicks on the Add drop down button which presents a choice of available data sources. Currently only Domino View and Domino Document are available. For the purpose of this example you should choose to add a Domino Document data source.

Once that is chosen the properties panel will update automatically and will display default information about the newly added data source. Basically the Data Source is a mechanism for an XPage to be able to open and read/write data that would normally be entered/read via a Notes form/view. In the case of a Domino Document the preexisting design element is a Notes form. In order for the Data Source to be of any use the user must select which application and which form the data which they are trying to retrieve/save must reside, both of these attributes can be computed at run-time, but for the sake of keeping this example simple we will enter the information statically.
Setting the application and form name is trivial. By default the Data Source will look up preexisting design elements in the current application (the application where the XPage resides). The user can then select the appropriate form name from the drop down list of forms available at the data source panel. In the case of this example we want to save data that would have otherwise been saved using the contact form in Notes. In this case the designer selects the contact form from the list of forms available.

Once contact is selected it implies that going forward on this particular XPage the document1 data source is in fact basically referring to data from the contact form in Notes. document1's reference to the contact form can at any point be changed by the designer to reference some other form.
Once the data source is set up at the page level it is now time to create the form to look like an input form, basically with a table with labels and input fields where the end user can enter data. To quickly do this, from the Controls Palette drag and drop a table control from the palette and drop it on the XPage. Choose to create a table with 2 columns and 7 rows. Drag and drop a label control (from the Controls Palette) in each of the left hand rows. Drag and drop an Edit Box control from the Controls palette into the top right hand cell of the table, at which point your XPage should look like the following:

With an edit box control selected on the XPage go to the properties view and select the Data tab. Once the data tab is selected you will notice that document1 is automatically selected as the data source for the edit box control. This is just a design time selection, it is done automatically as document1 is the first data source on the list, the designer of the application can choose to overwrite this selection if he/she so wishes.
With document1 selected in the Data source field the designer next clicks on the Bind to drop down. This drop down will show a list of all the fields that are available for data binding in the contact form. As outlined above, document1 is the data source, and it is pointing to the contact form, thus all of the contact form's fields show up in the Bind to drop down.

Clicking on the firstName field in the Bind to drop down selects firstName and sets it as the field in the contact form to which this XPages edit box is now bound. Any information entered by the end user into this field will be saved to a new document into the firstName field. Earlier in the article when we set up the document1 data source by default the Default action attribute was set to Create document, meaning each time the data source is invoked via a document submit it will create a new document in the Notes application. Basically what we have done here is a fundamental step towards understanding how data binding works in XPages. Each control on an XPage corresponds to an XML tag. In this case the edit box is an inputText tag, setting values on the properties panels corresponds to setting attributes on the XML tag. In the case of the Data tab of any XPage control you are mainly dealing with setting the value attribute on the corresponding XML tag. Here is how the XML tag for the above XPages control would look after the data binding operation was performed:

As you can see the value attribute has been configured just as we specified in the properties panel. You will also notice that the value attribute also has some extra characters inserted automatically also. The #{...} notation is an integral part of the data binding. Basically there are three types of data binding available in XPages, the most basic type is static data binding where by the value is set to some static value which does not change. The other types of data binding are Compute Dynamically and Compute on page load. There is an important difference between these two data bindings. Compute on page load uses the ${....} notation and implies that the expression between the curly braces only gets computed as the XPage is loading, meaning the expression is only evaluated once. Compute Dynamically uses the #{...} notation and implies that the expression between the curly braces is computed each time the property is queried. Compute Dynamically is the most common data binding for properties that need to be computed. It is a very powerful method of data binding as it allows the designer to dynamically set and get properties at any point in the page's life-cycle.

Continuing in the same fashion as above we can recreate the Notes form in XPages, binding the individual XPage edit box controls to the various fields in the Notes contacts form.

The final step to complete this form is to drag and drop a button control from the palette onto the XPage. Once the button is added you must change the type of the button to be a submit button.

You now have a working XPage that will save data entered in the XPage into your Notes application. XPages also have built in converters and validators that allow the designer to add data conversion and data validation routines into his/her XPage logic without having to write and code. Validators and converters will be dealt with in separate Wiki articles.

Displaying Existing Data in an XPage
In classic Notes development designers use instances of the View design element to show documents which are filtered according to certain criteria which are defined in the View design element's definition.
Similarly in XPage development the user can use an XPage View control to display a list of documents in an orderly fashion. Analogous to how we have a Domino Document data source in XPages we also have a Domino View data source. And in an identical fashion to how the Domino Document data source has to define which Notes form design element it is corresponding to, similarly the Notes View data source also has to define which Notes View design element it is going to use as a definition for the selection criteria of the XPages Domino View data source.

For the purposes of this article I created a new View design element called alldocuments. This view has 6 columns; Last name, First name, Country, State, City, and Street. These columns correspond to the fields in the contacts form created in the first section of this article.


I also created a new XPage called xpAllDocuments. As the title suggests this page will contain an XPages view control that will show all of the documents in the current application.
Once the XPage is created simply drag and drop a View control from the Controls Palette and drop it on the XPage.

During the process of dropping the control on the XPage a dialog box will pop up which will allow you to configure the contents of the XPages view control.

It is easiest to configure the contents of the XPages view control from this dialog. First you should choose which Notes view design element you wish to use in order to filter the documents that will appear in this XPages view control. I choose alldocuments which is the Notes view design element I created earlier. Once the user chooses a view to use the remainder of the dialog gets populated automatically with a list of columns that are available in that view. Leaving all of the columns selected and pressing OK results in an XPage view control being generated on the XPage with the appropriate number of columns and also with the columns and XPages View control being correctly bound to the appropriate Notes view design element and columns.

You will also notice that an XPages Pager control is also generated automatically and inserted at the top right hand corner of the view control. This pager allows the view to control the number of documents visible at any one time. The default number of documents visible is 20. It can be modified by clicking on the pager control and modifying the attributes via the attributes panels.

If you go to source mode you will notice that the XPages Domino View data source is embedded within the XPages view control.

Each of the XPage view control's columns are individually bound to columns with corresponding names in the corresponding Notes view.

Saving the XPage and running the application on a Domino Server will allow you to see XPages 'in action'. You now have an application that is capable of storing and retrieving documents via a web browser. In order to run this application type http://my_server_ip/my_app_name.nsf/xpContact.xsp into your browser's address bar.

Summary
From reading this article you can see that data binding in XPages is very straight forward and intuitive. As virtually every attribute on an XPage is computable this makes data binding on XPages extremely powerful. In future articles I will dive into advanced data binding using JavaScript and advanced Expression Language.

Resources
For more information also see:
Adding a computed column to a view


Code
xpContact.xsp


xpAllDocuments.xsp