Introduction

In this tutorial, the XPages developer will be shown how to build a simple XPage Mobile application in an existing Domino database. Using the familiar Discussion template based application, we take the user on their first steps to creating a XPages mobile web experience. A mobile application is built from scratch; display a list of views, display the contents of a view, open a document from that view and then perform all the typical actions like Create, Read, Update and Delete on a document.

Prerequisites

This tutorial has been updated to target the latest IBM Notes Domino 9.0 release. Sections of this tutorial will need the later release IBM Notes Domino 9.0.1, these will be called out for the user in the text.

The Mobile Apps Palette in Designer

When the developer launches Domino Designer from IBM Notes Domino 9.0 and opens a XPage, they are presented with a number of additional drawers on the right hand side in the Controls palette. One of these is the Mobile palette as shown in Figure 1.01.
Figure 1.01


Those who previously used the mobile controls from IBM Notes Domino 8.5.3 may notice a difference in the list presented. In Notes Domino 9.0, these controls have been renamed though the underlying tags remain the same as in Table 1.01.
Table 1.01

Control tag	Control Names in 9.0.x	Control Names in 8.5.3
xe:singlePageApp	Single Page Application	Single Page Application
xe:appPage	Application Page	Mobile Page
xe:djxmHeading	Page Heading	Page Heading
xe:djxmRoundRectList	Rounded List	Rounded List
xe:djxmLineItem	Rounded List Item	Static line Item
xe:toolbarButton	Tool Bar Button*
xe:tabBar	Tab Bar	Tab bar
xe:tabBarButton	Tab Bar Button	Tab Bar button
xe:djxmSwitch	Toggle Switch	Mobile Switch

This is the collections of controls which can be used for the developing XPage mobile applications.

Single Page Application (xe:singlePageApp)

This is the container control for the XPages mobile application, controlling it's layout and configuration. The property selectedPageName must be set here to a Application Page control that is to be displayed when the XPage is load.
More...

Application Page (xe:appPage)

This is the web page fragment used in a mobile application. Only one of these mobile pages is displayed at a time. It contains a number of notable properties which effect the behaviour of this control.
The pageName property is the mobile page name and is the property used for navigation between the mobile pages as well as being used by the Single Page Application control to decide what page to show initially. The resetContent property is used to indicate if the page contents should be recreated each time the page is displayed. Another property affecting performance is preload, which can be used to force the Application Page to be loaded when the whole XPage is loaded.
More...

Page Heading (xe:djxmHeading)

Another essential control for your XPages Mobile application is the Heading control. It's used as the header for the Application Page. It contains properties for the basic navigation - the back property being the label for the Back button and the moveTo property to contain the pageName of the destination of the Application Page.
The Heading control can also act as a container for other controls like buttons and the mobile applications Tab Bar.
More...

Rounded List (xe:djxmRoundRectList)

This control is noteworthy for it displays a rectangle with rounded corners, and we are using it here in this tutorial to provide the background and rounded corners for the Application Pages that contain documents.
More...

Rounded List Item (xe:djxmLineItem)

The Rounded List Item control is a dojo control mainly used to link to other mobile pages.
More...

Tool Bar Button (xe:toolBarButton)

Added in IBM Notes Domino 9.0, the Tool Bar Button is a button that can be placed in Page Heading control, ideally suited for when an action button is needed to say create a new document. The Page Heading isn't the only place for which this control can be placed. It can be used elsewhere in the Application Page and still have the same functionality, and look and feel.

Tab Bar (xe:tabBar)

The Tab Bar on it's own displays like a banner across the Application Page, and is used as a container control for the Tab Bar Button. When the barType property is set to segmentedControl, the tab bar buttons display together as one though separated into their individual buttons.
The Tab Bar can also be placed inside the Page Heading.
More...

Tab Bar Button (xe:tabBarButton)

The Tab Bar Button is very much the same as the conventional XPages button (xp:button) but with different styling for XPages Mobile applications.
More...

Toggle Switch (xe:djxmSwitch)

The Toggle Switch control is probably best described as an on\off switch, behaves like a checkbox, and not to be confused with a Switch facet control (xe:switchFacet) which allow the developer to dynamically change content that depends on a certain value.
More...

Other XPages Controls for Mobile

The above control are not the only XPages controls that can be used in building XPages mobile apps. As XPages mobile apps are essentially web application with a native look and feel, all XPages controls can be used but that does not make them usable. A number of XPages controls have been enhanced so that they become more usable inside a XPages Mobile Application. Controls like the Data View (xe:dataView), Form Table (xe:formTable), and the Outline (xe:outline) have all have renderers added to give them that mobile look and feel.

Tutorial Overview

The objective of this tutorial is to introduce the XPages Mobile controls, how to use them and build a simple application using them. In this simple application, we are going to demonstrate the usual CRUD operation - create, read, update and delete - of documents.
The application that is to be built is contained within one XPage using the Single Page Application control. This control will contain a number of Application Pages controls as illustrated in Figure 1.02. Only one Application Page is display at a time on the Single Page Application control and moveTo action are used to transition between these pages.
Three Application Page controls will be added to the Single Page Application control each will represent a different mobile page; a home page, a page to view of a collection of documents, these documents will be opened in another mobile page where these documents are to be read, updated and deleted, and finally another mobile is used to create new documents which once created will display on the view mobile page.
Figure 1.02

---

Application Setup

To set up a sample application for this tutorial, take any existing Discussion template based application from Domino 8.5.x and launch it in Designer (or take any Domino application and remember to swap out the Form and Notes View names as we go through this tutorial). This application would not have an existing XPages mobile application created within, and with this application we are going to do two things; set a variable in the application's properties to use the XPages mobile theme, and enable the application to use the XPages Extension Library.

Set the Mobile Page Prefix in the XPages Application Properties for the XPages Mobile Theme

With the application open in Domino Designer, launch the Xsp Properties from the Application Configuration section as shown Figure 2.01
Figure 2.01


This will launch the Xsp Properties for the application, and here on the first tab select the checkbox beside "Use mobile theme for XPages with the prefix" as shown in Figure 2.02. This will set xsp.theme.mobile.pagePrefix=m_ - 'm_' being the prefix added to the XPage upon which mobile application is to be created. Any prefix can set, it doesn't have to be 'm_'. The XPages developer needs to select a prefix carefully so that it doesn't conflict with the names of existing XPages existing in the application. This is needed for the XPage to use the Mobile theme for the mobile application else it will use the existing application's theme and will not appear as desired.
Figure 2.02

Enabling it for the XPages Extension Library

Next we will need to enable the application to use the XPages Extension Library. With the XPage Properties document open, progress to the Page Generation tab. And here check the box for com.ibm.xsp.extlib.library in the XPages Libraries section on the Advanced tab as in Figure 2.03. This enables the application to use the XPages Extension Library (ExtLib) which contains the mobile controls.
Figure 2.03


We now save these changes to the xsp.properties file. Verify that this is done, advance to the Source tab. There two variables "xsp.theme.mobile.pagePrefix=m_" and "xsp.library.depends=com.ibm.xsp.extlib.library" should now be added as shown in Figure 2.04.
Figure 2.04

---

Create a new Mobile Application and Home Page

We can now begin to create a mobile application, which is basically one XPage that contains a number of sections where in each is displayed dynamically. This is done so that there is a smooth transitions between pages and that the feature behaves in a manner that the user expects from a mobile application.

Create a new XPage for the Mobile Application

Next create a new XPage and name it to whatever as long as it is prefixed to what has been set in the xsp.properties file, for example 'm_application.xsp' as shown in Figure 3.01.
Figure 3.01

Add a Single Page Application (xe:singlePageApp) control to the XPage

To the XPage add from the Mobile palette in Designer a Single Page Application (xe:singlePageApp) control as in Figure 3.02. This is the container needed for the XPages mobile application.
Figure 3.02

Add an Application Page and a Header to the Single Page Application

Then into the Single Page Application, add an Application Page control (xe:appPage) as shown in Figure 3.03. This is a web page fragment for the application and only one of these can be displayed at a time.
Figure 3.03


To this application page add name to the property pageName='homePage' in the property panel as shown in Figure 3.04.
Figure 3.04


To the Application Page, add a Page Heading control (xe:djxmHeading) and to the label property of this control enter “Home” as shown in Figure 3.05
Figure 3.05


On the Single Page Application control, the property ‘selectedPageName’ is now set to the Application Page page name just added - 'homePage' as shown in Figure 3.06.
Figure 3.06


This will then be the default page to be loaded by the Single Page application when the XPage is launched in the browser of the mobile device. This should generate the markup as shown below in Listing 3.01.
Listing 3.01


We can now take a first look at your new XPages mobile application when launched in a mobile device's web browser as in Figure 3.07.
Figure 3.07


Note: the above screenshot is taken from the application running in a Chrome browser with the User Agent set to mimic that of an iPad -
Mozilla/5.0 (iPad; CPU OS 5_0 like Mac OS X) AppleWebKit/534.46 (KHTML, like Gecko) Version/5.1 Mobile/9A334 Safari/7534.48.3

Add an Outline for Navigation

Most mobile applications have on their default page an outline of options for users to select. For XPages mobile application we can use two methods to create this list of options. One is use an Outline (xe:outline) control, and another is use a Rounded List with Rounded List Item controls which we are going to use here.
Add a Rounded List control (xe:djxmRoundRectList) to the editable area of the Application Page as shown in Figure 3.08.
Figure 3.08


Depending on how accurate the drag and drop is the Rounded List may appear in the wrong location relative to the Heading as shown in Figure 3.08. This can be rectified selecting and dragging the Heading control back to the top as shown in Figure 3.09 and on Figure 3.10
Figure 3.09


Figure 3.10


Next, add a Rounded List Item control (xe:djmxLineItem) to the editable area on the Rounded List control that was added in the previous step. The Rounded List is to be the container control for the Rounded List Item control. Without the Rounded List control, the Rounded List Item may not transition as expected between mobile pages as the underlying runtime gets upgraded. This control can perform a number of functions and here we're going to use it to create a link to the next application that'll contain a view of all the documents in the Discussion application, so for this we now enter "All Documents" into label property for the Rounded List Item as shown in Figure 3.11.
Figure 3.11


The markup for these changes should generate what is shown in Listing 3.02 for the application page "homePage".
Listing 3.02


We can save our work at this point and preview the results in the web browser as shown in Figure 3.12.
Figure 3.12

The moveTo Property

We will now use this Rounded List Item control to link to another mobile page and for that we are going to fill out the 'moveTo' property with the name of the destination page. In this exercise we are going to use this property to point to another Application Page in the same Single Page Application.
Input 'viewPage' (an Application Page which will be created in the next section) as shown in Listing 3.03.
Listing 3.03


By setting the 'moveTo' property, a chevron will now appear signifying that that this item will navigate the user to another mobile page as in Figure 3.13.
Figure 3.13

---

An Application Page to Display Data from a Notes View

The next step is to create a new Application Page to display data from the All Documents Notes View in the existing Discussion application.

Add a Second Application Page control

Add a second Application Page to the Design pane and place it after the first Application Page in the Single Page App. Go to the All Properties panel of the control and for the property "pageName" input ‘viewPage’ as shown in Figure 4.01. This should correspond to the moveTo value on the ‘All Documents’ Rounded List Item control, so when this is selected the navigation will go to this new Application Page.
Figure 4.01


Next, add a Page Heading control to the Application Page and for the Label enter "All Docs" as shown in Figure 4.02.
Figure 4.02

Add a Data View to Display the Data from the Notes View

The Data View control is one of the other control outside of the Mobile palette which can used in XPages mobile applications and will render with the native look and feel which users expect. The configuration of the Data View for this purpose is easy in comparison to its use in regular XPages applications. For Mobile, the only attributes that will be used are the "summaryColumn" and the "categoryColumn". For the following exercise we will be using just the summaryColumn to display the values of the "Topic" column from the Notes View "All Documents". If the All Documents view was a categorized view, we would be using categoryColumn as well.

Add a Data View control from the Extension Library palette to the second Application Page after the Page Heading control. This will launch a dialog for the user to select a View data source, and from here, select the All Documents ($All) view as shown in Figure 4.03.
Figure 4.03


Selecting OK here to add the Data View to the Application Page as shown in Figure 4.04.
Figure 4.04


Next go to the All Properties panel of the Data View. In the format section, select the summaryColumn attribute and when you do so a button with the plus sign "+" that will appear. Press this Plus button once and a new complex property "xe:viewSummaryColumn" will then display in its place. To the columnName property input ‘Topic’. This is the corresponding column name from the Notes View data source as shown in Figure 4.05.
Figure 4.05


We would also like to limit the number of rows the Data View displays when viewed in a mobile device. Ten is an optimum number to choose though this may vary depending upon the device. So while we have the All Properties of the Data View open, set the row count to "10" as shown in Figure 4.06.
Figure 4.06


The pageName property is set here also. This is the destination page name for document links on the Data View. In this case we are going to set this to 'documentPage' (which is to be created in the next section). And like the moveTo property on the Rounded List Item control, we use the pageName property to instruct the navigation to go to a location within the current page - pagename="documentPage" as shown in Figure 4.07.
Figure 4.07


We also set the opentDocAsReadonly property to true here, as shown in Figure 4.08, as we wish the first state of this document to be in read mode when opened.
Figure 4.08

Set the Navigation on the Page Heading

The navigation between the two Application Pages needs to be set. In this case, it is done in the Page Heading (xe:djxmHeading) and here we set the ‘moveTo’ property to display the home Application Page "homePage". This will become the action of the Back button on the Page Heading. The label on the Back button is also set here too with the property ‘back’ being set to ‘Back’ as shown in Figure 4.09.
Figure 4.09

The "preload" Property

While on the viewPage we are going to use the preload property. This, when set to true as shown in Figure 4.10, is used to load the Application Page when the mobile application is loaded on the mobile devices web browser. This is done in the background and helps the application's performance for the user.
Figure 4.10


This completes the viewPage Application Page and Listing 4.01 shows the markup that should have been generated in this exercise.
Listing 4.01

Test the Navigation and Data View data display

Now the two Application Pages can navigate between each other. We can test this by selecting the All Documents item to move to the Application Page that contains the Data View, and selecting Back navigates back to the home page as shown in Figure 4.11. This is the standard way navigation is done on Mobile applications.
Figure 4.11

---

Read a Document

The next step is to open a document from the Data View in another Application Page to read the contents of that document selected.

Application Page to Display the Document

Like in the previous step, another Application Page is added to the Single Page Application. This is given the pageName "documentPage" which was the name used to configure the Data View pageName property in the previous exercise.

Document data source and document binding

After this, the Application Page is put together much like a developer would do for a conventional XPage.
Into the editable area on the Application Page we drag and drop a Panel(xp:panel). On this Panel we set the document data source using the 'MainTopic' Form as shown in Figure 5.01 - a form on a Discussion application.
Figure 5.01


Now that we have added a document data source we can add the other elements to enable the reading of documents.

We add a Page Heading control to the panel, and set some properties; label to "Document", back to "Back", and moveTo to "viewPage" as shown in Figure 5.02.
Figure 5.02


Next, we add a Form Table (xe:formTable) control after the Page Heading as shown in Figure 5.03. This is another control that is not available in the Mobile palette but in the Extension Library palette. We are using it here as it renders in native look and feel of the mobile device and suitable for displaying documents.
Figure 5.03


Then to the main editable area on the Form Table we now add three Form Layout Rows (xe:formRow) controls as shown in Figure 5.04.
Figure 5.04


To the top two rows we enter "Subject" and "Category" for the labels, and EditBoxes (xp:inputText) controls to the main editable areas of these rows. To the editable area of the third row we now add a Rich Text (xp:inputRichText) control. The Form Layout Rows should look like what is illustrated in Figure 5.05.
Figure 5.05


The next step is to bind these controls to the document data source, and this is done in the conventional XPages way as shown in Figure 5.06 for the Rich Text control.
Figure 5.06

Markup Generated to Read a Document

Listing 5.01 shows what this exercise should have generated for the "documentPage".
Listing 5.01


Figure 5.07 demonstrates how the application should now behave and a document being shown in Read mode in the "documentPage".
The same example should also demonstrate the behaviour of the document page when the Application Page's property "resetContent" is not set. You'll notice that the same document that was first opened always displays no matter which document was selected in the "viewPage".
Figure 5.07

Application Page property "resetContent" on Document Page

In the above example the same content appears in the "documentPage". The reason for this is that we are not telling the Application Page to go back to the server to retrieve the new data. Listing 5.02 shows how we can change this behaviour to reset the content by setting "resetContent" to true.
Listing 5.02


Test this change and verify that the document selected from viewPage now opens as expected in the documentPage.

Remove Label for the Document Body

In Figure 5.07, we see that the content of the body, the rich text, is set to one side in line with the Subject and Category field values and an area of white space exists in the row under the Category label. This is because of the label, though not set for the row, still holds a place for this label when rendered. We can make it so that the body uses up this space by setting the label position to "None" as in Figure 5.08.
Figure 5.08


This change should now allow the body of the document to use up the width of the row, which is vital for the small screen as shown in Figure 5.09.
Figure 5.09

---

Update a Document

Conventional XPages techniques can be used to update or edit the document, though in this exercise we are going take the opportunity to use a Tool Bar Button (xe:toolBarButton) from the Mobile palette. We are going to use two Tool Bar Buttons, each for a specific action. One to switch the document from read mode to edit mode, and another to save the changes and transition back to the viewPage, the Application Page that contains the Data View.

The Page Heading Action Facet

Each Page Heading control has a facet or editable area, and its intended use is for the typical actions that users expect to be available to them at the top right hand side of the screen. An action to create a new document is one of the most common use cases. Another is editing and saving of documents which this exercise is about. The Tab Bar (xe:tabBar) and Tab Bar Buttons (xe:tabBarButton) can also be used for this same use case and placed anywhere in the Application Page, though for this exercise we are going to use the Action Facet and the Tool Bar Button.

First step on this exercise is to add a Panel to the actionFacet as shown in Figure 6.01. This panel will be the container for the two Tool Bar Buttons.
Figure 6.01

Tool Bar Button for Edit Mode

To the panel which was added into the actionFacet, drag and drop from the Mobile palette a Tool Bar Button and add a label "Edit" as shown in Figure 6.02
Figure 6.02


We also want to programmatically determine when this button becomes visible. We only want it to display when the document is in Read mode. This is done as in any other XPage application by configuring the Visible option to not render when the document is editable as shown in Figure 6.03.
Figure 6.03


And to the onClick event for this button we add a server-side simple action to change the mode of the document to edit mode as in Figure 6.04.
Figure 6.04

Tool Bar Button to Save Changes

We now add another Tool Bar button to the panel in the action facet and set the label to "Save" as in Figure 6.05
Figure 6.05


And for this button we want to determine when this button should render, and for this exercise we only want this button to display when the document is in edit mode as in Figure 6.06. This button should then display when the Edit button is selected and so only one button will appear in the action facet at one time.
Figure 6.06


And finally to this Save button we are going to add a specific mobile simple action, Move To Application Page, to do two main things on the on click event as shown in Figure 6.07. To save the document, and then to move to the viewPage.
Figure 6.07

The Action Facet Markup and Test

Listing 6.01 shows the completed markup as a result of this exercise for the Tool Bar Buttons in the Action Facet.
Listing 5.3


We can now test the changes made to the action facet on the documentPage. The Edit button should now appear on the top right hand corner of the page as shown in Figure 6.08.
Figure 6.08


Selecting the Edit button should toggle the document from Read mode to Edit mode. And the Save button should then appear in place of the Edit button as in Figure 6.09.
Figure 6.09


Make a change to the document, like edit the Subject, and select Save. This should transition to the viewPage.

The resetContent Property on the View Page

You may have noticed if you had made a change to the Subject that those changes aren't reflected in the viewPage. This is because the updated Notes view data hasn't been retrieved from the server. So to see these changes, particularly when changes are made to the data that is also used by the Notes View data source, we set resetContent to true on the Application Page for the viewPage as in Figure 6.10.
Figure 6.10

---

Create a New Document

For composing new documents we are going to reuse the Document Page but transition to it from an action button on the viewPage.

New Button on the View Page Action Facet

To the viewPage Application Page drag and drop a Tool Bar Button to the action facet of the Page Heading control. To this Tool Bar Button add a label "New" as in Figure 7.01.
Figure 7.01


Then to this button we add the mobile simple action for the onClick event. Here, as shown in Figure 7.02, we set the transition direction to go from left to right, we want to force a full refresh of the xpage, set the target page as the documentPage, and the transition type as slide
Figure 7.02

Create a New Document Test

Figure 7.03 shows the New button in place on the Page Heading of the viewPage Application Page.
Figure 7.03


Selecting this button should transition to the documentPage where the input fields can be selected and data entered as in Figure 7.04.
Figure 7.04


Selecting Save on the documentPage should as before transition the user back to the viewPage where the new document should now be visible as in Figure 7.05.
Figure 7.05

---

Delete a Document

Deleting document on a XPages mobile application can be handled in very much the same way as it is done in a conventional XPages app. For example, on to a button, a delete document simple action is performed, or a selected document can be deleted from a view panel.
In this exercise, we are going to add a Tab Bar and to it a Tab Bar Button on the documentPage Application Page.

Add a Tab Bar and a Tab Bar Button

To the documentPage drag and drop a Tab Bar (xe:tabBar) to a space after the Form Table on the Panel as in Figure 8.01.
Figure 8.01


The Tab Bar is a container for the Tab Bar Button which we now add, and to this button we add a label "Delete" as in Figure 8.02.
Figure 8.02


Back on the Tab Bar, we set the property "barType" to "segmentedControl" as in Figure 8.03 to give the control a typical rendering for mobile devices; in that it will render as a banner across the page and the button displays as typical button requiring no extra styling.
Figure 8.03


We also want to control when this Delete button gets displayed. Typically this is not displayed when the document is a new document, so we add "!document1.isNewNote()" to the computed value of the visible option as in Figure 8.04
Figure 8.04

Configuring a Delete Document Action

To the Delete button we add a grouped simple action that will first of all delete the document if the user wishes to do so and before transitioning back to the viewPage.
Select the Events view tab for the Delete button and for the onClick event add a Delete Document Simple Action document data source of the documentPage 'document1', and a confirmation messages as in Figure 8.05
Figure 8.05


Then to this delete document simple action, another simple action "Move To Application Page" is added. Here we set the targetPage to the viewPage, the forseFullRefresh and the transitionType and direction as shown in Figure 8.06
Figure 8.06


Now that the two actions have been completed on the same event they should appear as a Action Group as in Figure 8.07.
Figure 8.07

Tab Bar markup for the Delete action and Test

Now that we've completed the configuration of the Tab Bar Button for the delete action we should have a markup generated for this as in Listing 8.01.
Listing 8.01


And when we run this on the mobile device we will now see this delete button appearing on the Tab Bar as in Figure 8.08.
Figure 8.08


And when selected, we get the confirmation message to OK this action as shown in Figure 8.09
Figure 8.09


And this should then transition, right to left, back to the viewPage where the deleted document should no longer exist as shown in Figure 8.10
Figure 8.10

---

Conclusion and Link to CRUD Markup

This completes the tutorial to build a basic application using the XPages Mobile controls. The complete markup to the above steps have been posted to http://openntf.org/XSnippets.nsf/snippet.xsp?id=xpages-mobile-control-tutorial-crud-xsnippet

What follows next some more exercises that will advance this tutorial and your understanding of building application with the XPages mobile controls.

---

Advanced Topics

We now pick a number of topics that will help you build a more complete understanding of XPages mobile applications.

Design Patterns for XPages Mobile Applications

> Placeholder <<<

Using CKEditor and Rich Text

> Placeholder <<<

File Upload and Download

> Placeholder <<<

Using the deviceBean Feature

> Placeholder <<<

Using the Transitions Events

> Placeholder <<<

Using the Orientation Change and Resize Events

> Placeholder <<<

Paging and Show More Rows on the Data View

> Placeholder <<<

Using the Switch Controls

> Placeholder <<<