ShowTable of Contents
Introduction
In this simple 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 an XPages Mobile web experience. This tutorial builds a mobile app 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
There are a number of prerequisites the XPages developer will need to have before they take part in this tutorial...
- Domino 8.5.3 or the new IBM XWork server. The new XPages Mobile controls will not work on 852, they need the existing 853 runtime to function.
- The new 8.5.3 XPages Extension Library from OpenNTF or better. This tutorial focus is on the new XPages Mobile controls that come as part of the new 8.5.3 version of the XPages Extension Library. This library must be installed on the server and in Domino Designer as well.
- And some time to relax ;-)
Download the IBM XPages Extension Library 853 from OpenNTF
The 8.5.3 XPages Extension Library can be downloaded from OpenNTF
here
or take any new 8.5.3 Extension Library after October 14th 2011. From the downloaded zip file, locate another zip file called '
updateSite-designer.zip'. This is the usual Extension Library updateSite with extra Designer plugins for UI on a number of the new controls like Application Layout and the Data View.
Installing and deploying the XPages Extension Library
For Domino 8.5.3 and the IBM XWork Server the preferred way to install and deploy the Extension Library is to use the UpdateSite database, which is created from the new 'Eclipse Update Site (8.5.3)' template (updatesite.ntf). This streamline way to install and deploy the library is described here -
XPages Extension Library Deployment'.
For Domino Designer, it is advised that the developer installs the same updateSite for the Extension Library that is deployed to the server via the above method. Do this by...
- Selecting from Designer, File - Application - Install.
- Then from the Install\Updates dialog, select to 'Search for new features to install'.
- And then on the following dialog select the button to add a remote location - add the URL to the above update site nsf as shown in Figure 1.1
Once this is done, proceed to install the same extension library to Domino Designer that the server uses.
The Mobile Apps Palette in Designer
Once the new 8.5.3 XPages Extension Library has been installed on Designer the XPages developer is presented with a number of additional controls to the palette. One of these is the
Mobile Apps palette as shown in Figure 1.2.
Figure 1.2
This is the collections of controls 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 Mobile Page control that is to be displayed when the XPage is load.
Mobile 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 singlePageApp 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 Mobile Page to be loaded when the whole xpage is loaded.
Page Heading (xe:djxmHeading)
Another essential control for your XPages Mobile application is the Heading control. It's used as the header for the Mobile 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 Mobile Page.
The Heading control can also act as a container for other controls like buttons and the mobile applications Tab Bar.
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 Mobile Pages that contain documents.
Static Line Item (xe:djxmLineItem)
The Static Line Item control is a dojo control mainly used to link to other mobile pages.
Mobile Switch (xe:djxmSwitch)
The Mobile 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.
Tab Bar (xe:tabBar)
The Tab Bar on it's own displays like a banner across the Mobile page, and is mainly 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 places inside the Heading.
Tab Bar Button (xe:tabBarButton)
The Tab Bar Button is very much the same as the conventional XPages button (xp:button) butwith different styling for XPages Mobile applications.
Tutorial Overview
The objective of this tutorial is to introduce the new 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 Mobile Page controls as illustrated in Figure 1.3. Only one
Mobile Page can display at a time on the single page application control and
moveTo action are used to transition between these pages.
Four Mobile Page controls (ex:appPage) 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.
Using the Source Pane for this tutorial
All steps to build this simple application will be shown through the Source Pane in Designer. This means that each stage will be shown the in the XPages markup where the various attributes can be configured and in the All Properties pane. The main reason for this is that not all of the new controls have Designer UI, so it may take some getting used to - though benefits will be evident in the end as we will become more familiar with these new XPages controls.
It's also worth noting that the controls from the palette can be dropped directly on to the Source pane as well as the Design pane. This will generate the correctly tags in the right place, and from here it is advisable to configure the control via the
All Properties panel as shown in Figure 1.4.
Figure 1.4
The Application and Enabling it for the Extension Library
For this tutorial, take any existing Discussion template based application from Domino 8.5x and launch it in Designer. Go to the Application Properties and check the box for
com.ibm.xsp.extlib.library in the XPages Libraries section on the Advanced tab as in Figure 1.5. This enables the application to use the XPages Extension Library (ExtLib) which contains the new mobile controls.
Figure 1.5
This step isn't really necessary because when a user drags and drops a ExtLib control from the Palette to the Design pane in Designer they are prompted to enable this option. This step is done here to highlight how one can enable an application to use the ExtLib.
It's also worth noting that with the new 8.5.3 XPages Extension Library installation another library becomes available in this window called the
com.ibm.xsp.extlibx.library. This is an experimental extension library of XPages artifacts which have yet to be earmarked for IBM productization as with com.ibm.xsp.extlib.library. So for this tutorial, it is only necessary to select one library.
Set the Mobile Page Prefix in the XPages Application Properties for the XPages Mobile Theme
In Designer, go to the Package Explorer view. In the application you've chosen, locate the
xsp.properties file in the
Web Content\WEB-INF folder. Edit it and add the following line -
xsp.theme.mobile.pagePrefix=m_ as shown in Figure 1.6 - '
m_' being the prefix to your the XPage upon which mobile application is to be created. Any prefix can set, it doesn't have to be 'm_'. Though 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 1.6
Create a new Mobile Application and Home Page
We can begin now to create a mobile application in XPages, 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'.
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 Listing 2.1. This is the container needed for the Mobile application.
Listing 2.1
Add a Mobile Page and a Header to the Mobile Application
- Then into the mobile application, add a Mobile Page control (xe:appPage) from the Mobile App palette. This is a web page fragment for the mobile application and only one of these can be displayed at a time.
- Give this mobile page a name - pageName='homePage'.
- Then to the Mobile Page add a heading control (xe:djxmHeading) and give it a label – “Home”.
- On the mobile application control, the property ‘selectedPageId’ is now set to the mobile page name just added - 'homePage'. This will then be the default page to be loaded by the mobile application. This should generate the markup as shown below in Listing 2.2.
Listing 2.2
<?xml version="1.0" encoding="UTF-8"?>
<xp:view xmlns:xp="http://www.ibm.com/xsp/core"
xmlns:xe="http://www.ibm.com/xsp/coreex">
<xe:singlePageApp id="xpagesMobileApp"
selectedPageName="homePage">
<xe:appPage id="appPage1" pageName="homePage" >
<xe:djxmHeading id="homePageHeading" label="Home"></xe:djxmHeading>
</xe:appPage>
</xe:singlePageApp>
</xp:view>
And this enough to render a first look at the new XPages mobile application when launched in a web browser in a mobile device as in Figure 2.1.
Figure 2.1
Add a Static Line Item control (xe:djmxLineItem)
Before we add a Static Line Item control (xe:djmxLineItem) we must first add a Rounded List control (xe:djxmRoundRectList) which is to be the container control for the Static Line item control. Without the Rounded List control the Static Line item may not transition as expected between mobile pages as the underlining runtime gets upgraded.
To this Rounded List container control (xe:djxmRoundRectList) we now add a Static Line item control (xe:djxmLineItem). This control can perform a number of functions and we're going to use it hear to create a link to the next XPages mobile page that'll contain a view of all the documents in the Discussion application.
- We add the control into the home mobile page.
- And after the heading, and give it a label "All Documents" as shown in Listing 2.3.
Listing 2.3
...
<xe:appPage id="appPage1" pageName="homePage">
<xe:djxmHeading id="homePageHeading" label="Home"></xe:djxmHeading>
<xe:djxmRoundRectList id="djxmRoundRectList1">
<xe:djxmLineItem id="djxmLineItem1" label="All Documents">
</xe:djxmLineItem>
</xe:djxmRoundRectList>
</xe:appPage>
...
We can save our work at this point and preview the results as shown in Figure 2.2.
Figure 2.2
The moveTo Property
We are going to use this static line 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. This can be another XPages but in this exercise we are going to use this property to point to another mobile page in the same application, the '
viewPage' (which will be created in the step) as shown in Listing 2.4. We use a Hash (#) prefix here to enable the link to navigate to a location within the existing XPage.
Listing 2.4
...
<xe:appPage id="appPage1" pageName="homePage">
<xe:djxmHeading id="homePageHeading" label="Home"></xe:djxmHeading>
<xe:djxmRoundRectList id="djxmRoundRectList1">
<xe:djxmLineItem id="djxmLineItem1" moveTo="#viewPage"
label="All Documents">
</xe:djxmLineItem>
</xe:djxmRoundRectList>
</xe:appPage>
...
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 2.3.
Figure 2.3
The resetContent Property on the Mobile Page control
The property ‘
resetContent’ is set to
false on the home page as we do not wish to have the page recreated every time the page is displayed, as in Listing 2.5. We will use this property throughout this tutorial and in many cases it will be set to
true because we wish the application to make a round trip to the server to retrieve updated data.
Listing 2.5
<xe:appPage id="appPage1" pageName="homePage" resetContent="false">
<xe:djxmHeading id="homePageHeading" label="Home"></xe:djxmHeading>
<xe:djxmRoundRectList id="djxmRoundRectList1">
<xe:djxmLineItem id="djxmLineItem1" moveTo="#viewPage"
label="All Documents">
</xe:djxmLineItem>
</xe:djxmRoundRectList>
</xe:appPage>
The 'id' and 'pageName' properties
The
pageName property allows you to override the
Id of the Mobile Page
. This allows you to have more readable urls when navigating around your application. If you don't use this you will have to calculate the clientId of the component.
Setting the Default XPage when the XPage Application is launched on a Mobile device
Right now there is not a way to set the default XPage when the application is accessed by a mobile device. You can of course set the default XPage for the Notes client and web browser client and this is a feature under consideration for mobile devices in future core release but for now there is no set way to set the default XPage here.
There is however a workaround and it is to use 'context.getUserAgent().getUserAgent()', which detects what the web browser make is, from the Global Objects library in the core XPages runtime and page redirect as shown in Listing 2.6. This workaround has been incorporated into the latest version of the TeamRoom template in an empty XPage called 'main.xsp', and this XPage is set as the default XPage when accessed from web browsers (XPages mobile applications are run on web browsers inside mobile devices).
Listing 2.6
<xp:this.afterPageLoad>
<![CDATA[#{javascript:
var uAgent = context.getUserAgent().getUserAgent();
if ((uAgent.match("iPhone") !== null || param.platfrom=="iphone") || (uAgent.match("Android") !== null || param.platfrom=="android") || uAgent.match("iPad") !== null)
{
context.redirectToPage("/m_Application.xsp", true);
}
else
{
context.redirectToPage("/allDocuments.xsp", true);
}
}]]>
</xp:this.afterPageLoad>
The View Mobile Page
The next step is to create a new mobile page to display a view, the All Documents view from the existing Discussion application.
Add a new Mobile Page control
After the first Mobile Page, a second is added - ‘viewPage’. This should correspond to the moveTo value on the ‘All Documents’ Static Line Item control, so when this is selected the navigation will go to this new mobile page.
Add a Data View to display the Document titles
- Next, a Data View is dropped into the Mobile page.
- And as with any conventional configuration of a XPages view container, the data property is set here to pick up the view data source. In this case it will be the Notes view created for XPages, the All Documents view (xpAllDocuments).
- Then the summary column is then set to pickup the ‘Topic’ column from the view data source.
- We would also like to limit the number of rows the Data View displays, ten is the optimum number of the row count.
- 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 step). And like the moveTo property on the Static Line Item control, we use a hash prefix to the page name to instruct the navigation to go to a location within the current page - pagename="#documentPage".
- We also set the opentDocAsReadonly property, as in Listing 3.1, here too as we wish the first state of this document to be in read mode when opened as in Figure 4.1.
Set the navigation on the header
- The navigation between the two mobile pages needs to be set. In the case, this is done in the Heading (xe:djxmHeading). Here the property ‘moveTo’ is set to the previous mobile page, ‘homePage’. This is what the action of the Back button on the header will do.
- The label on the Back button is also set here too with the property ‘back’ being set to ‘Back’.
Now the two pages can navigate between each other. Selecting the All Documents line item to move to the Data View mobile page, and selecting Back navigates back to the home page. This is the standard way navigation is done on Mobile applications.
The 'preload' property
The preload property is used here to load this page when the mobile application is loaded on the mobile's web browser. This is done in the background and helps the application's performance for the user.
The Data View Page Markup and screenshot
Listing 3.1
<xe:appPage id="viewPage" pageName="viewPage" preload="true"
resetContent="true">
<xe:djxmHeading id="viewPageHeading" back="Back"
label="All Docs" moveTo="homePage">
</xe:djxmHeading>
<xe:dataView rows="10" id="dataView1" pageName="#documentPage"
openDocAsReadonly="true">
<xe:this.data>
<xp:dominoView var="view1" viewName="xpAllDocuments">
</xp:dominoView>
</xe:this.data>
<xe:this.summaryColumn>
<xe:viewSummaryColumn columnName="Topic"></xe:viewSummaryColumn>
</xe:this.summaryColumn>
</xe:dataView>
</xe:appPage>
Figure 3.1 demonstrates how the above markup in Listing 3.1 might appear in a mobile device.
Figure 3.1
Paging and Show More Rows on the Data View
Adding a full XPages pager control to the a XPages mobile app can use up a lot of screen space. This is something a developer may not want to do. Customising the pager maybe a better approach.
The Data View has a number of facets for paging; pagerBottomLeft, pagerBottom and pagerBottomRight. Regular XPages link controls can be dropped into this callback\editable area and they will be given a Mobile look and feel by the Mobile Theme. The regular XPages pager renders as links as well and so this is suitable paging on a Mobile app.
Listing 3.2 shows the markup of a customised pager in the pagerBottom facet.
Listing 3.2
<xe:dataView rows="7" id="dataView1" pageName="documentPage"
openDocAsReadonly="true">
<xp:this.facets>
<xp:pager partialRefresh="true" id="pager2" for="dataView1"
xp:key="pagerBottom">
<xp:pagerControl id="pagerControl1" type="Next"></xp:pagerControl>
<xp:pagerControl id="pagerControl2" type="Previous"></xp:pagerControl>
</xp:pager>
</xp:this.facets>
...
And Figure 3.2 show how this might appear at runtime on the device. Here the Next link displays as if a button and the Previous link displays disabled as the Data View is on the first page.
Figure 3.2
Figure 3.3 shows the screen when the Next link is selected and the Data View advances to the next page of that view. And here too the Previous link is now active.
Figure 3.3
Adding rows to the Data View instead, or maybe additional to the pager might be preferable to users and developers.
Listing 3.3 shows how this might look like in the markup for the Data View facet pagerBottom and using a new simple action on a link from the Extension Library called 'Add rows to a data iterator' as shown in Figure 3.4.
Figure 3.4
Listing 3.3
<xe:dataView rows="7" id="dataView1" pageName="documentPage"
openDocAsReadonly="true">
<xp:this.facets>
<xp:link escape="true" text="Show More" id="link1" xp:key="pagerBottom">
<xp:this.rendered><![CDATA[#{javascript:var dv = getComponent("dataView1");
if(dv.getRowCount() > 5)
return true;
else
return false;}]]></xp:this.rendered>
<xp:eventHandler event="onclick" submit="false">
<xp:this.script>
<xe:addRows for="dataView1" rowCount="5" state="true">
</xe:addRows>
</xp:this.script>
</xp:eventHandler>
</xp:link>
</xp:this.facets>
...
Also in Listing 3.3, the rendered property is set to only display the Show More link is the the Data View contains more this 5 rows. And in Figure 3.5 this link displays as there are 7 rows.
Figure 3.5
Read a Document
The next step is to open a document from the Data View in another Mobile page to read specific contents of that document like the Subject, Category and Body.
Add another Mobile Page to the Mobile application to display the document
- Like in the previous step, another Mobile page is added to the Mobile application.
- This is given an easy recognisable pageName, ‘documentPage’ for this exercise.
- This name is important as it is needed to configure the Data View pageName property, and this is prefixed there with a hash tag and so combined it would be pageName="#documentPage".
- A Heading control is then added to the Mobile page and this includes navigation back to the view mobile page.
Document data source and document binding
After this, mobile page is put together much like a developer would a conventional XPage.
- A Panel (xp:panel) is added.
- And to which a Domino document data source is set using the 'MainTopic' Form.
- Labels and input controls are then added to the Panel as in Listing 4.1, and bound to the document data sources for the Subject, Categories and Body fields from the Main Topic form on the Discussion application.
Handling Rich Text in Mobile Applications
In the markup below, Listing 4.1, we have not included a rich text control to handle the Notes or web rich text, and there is good reason for this. Conventional and XPages Rich Text content can be rendered inside an XPage mobile application but it is likely to become incomprehensive scaled down to a small screen. Plus, the current version of the XPages Rich Text control (ckEditor) doesn't support mobile devices (phones or tablets) though this is very likely to change in future upgrades (CKEditor Support for Mobile).
The developer needs to think creatively here for a solution. Generally the solution is to use a multiline editbox (xp:inputTextarea) but it means that the user won’t have features associated rich text. Anywhere the developer intending to use a text box of some kind in place of a rich text editor, be aware that the developer will need to set the escape property to false.
In the markup below, we have used a Computed Field (xp:text) with the property 'escape' set to false. The rich text should appear satisfactory in read mode but editing the body text isn't really an option at this stage. For this reason, a Multiline Editbox control will be used for the input of text on the Body field in the exercise to create a new document further along.
Add the Rounded Edges Control
The rounded rectangle list (xe:djxmRoundRectList) control is added next to the mobile page. This will be the container for the document data and provide the styling surrounding the document when it displays in the device.
Markup to Read a Document
Listing 4.1
<xe:appPage id="appPage3" pageName="documentPage"
resetContent="true" preload="true">
<xe:djxmHeading id="documentPageHeading" back="Back"
label="Document" moveTo="viewPage">
</xe:djxmHeading>
<xp:panel>
<xp:this.data>
<xp:dominoDocument var="document1" formName="MainTopic">
</xp:dominoDocument>
</xp:this.data>
<xe:djxmRoundRectList id="djxmRoundRectList2">
<xp:label value="Subject: " id="labelSubject1"></xp:label>
<xp:inputText id="inputTextSubject" value="#{document1.Subject}">
</xp:inputText>
<xp:br />
<xp:label value="Category: " id="labelCategory1"></xp:label>
<xp:inputText id="inputTextCategory1" value="#{document1.Categories}">
</xp:inputText>
<xp:br />
<xp:text escape="false" id="computedFieldBodyDisplay"
value="#{document1.Body}">
</xp:text>
</xe:djxmRoundRectList>
</xp:panel>
</xe:appPage>
Figure 4.1 demonstrates a document opened in read mode from the data view.
Figure 4.1
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 couple of other mobile XPages controls - a Tab Bar (xe:tabBar) container control and a Tab Bar Button (xe:tabBarButton). The Tab Bar renders very much like a Heading control and with the tab bar buttons can display them in a segmented style.
The Tab Bar and Tab Bar Button
These two controls can be contained within the Heading control and so appear at the top of the mobile page. In this exercise we are going to place them below the header.
Firstly the Tab Bar container control is added to the page and the property barType is set to segmentedControl. With this set the tab bar buttons will then render together in a segmented style.
Editing a Document
- Tab Bar Buttons (xe:tabBarButtons) are added to the Tab Bar.
- From here these button can be configured in the same way as other action buttons in XPages. The Edit button is a normal run-of-the-mill XPages action button and uses a Edit Mode simple action as in Figure 5.1.
- We also set the rendered property here to be visible if the document is in read mode only as in Listing 5.1.
Figure 5.1
Known Issue with adding Events to an Extension Library Control
When events are added to Extension Library control using the above method to change the document mode simple action it will generate incorrect namespace for the eventHandler and action as in Listing 5.1 where xe is written instead of xp.
Listing 5.1
<xe:tabBarButton id="tabBarButtonEdit" label="Edit"
rendered="#{javascript:!document1.isEditable()}">
<xe:eventHandler event="onClick" submit="true"
refreshMode="complete">
<xe:this.action>
<xp:changeDocumentMode mode="edit" var="document1">
</xp:changeDocumentMode>
</xe:this.action>
</xe:eventHandler>
</xe:tabBarButton>
This left as is generates an error in Designer and so stops the page from compiling. This is a known issue 'DEGN8LFE64' in the core product which will be addressed in next release of Domino Designer.
These namespaces need to be changed back to xp before continuing as shown in Listing 5.2.
Listing 5.2
<xe:tabBarButton id="tabBarButtonEdit" label="Edit"
rendered="#{javascript:!document1.isEditable()}">
<xp:eventHandler event="onClick" submit="true"
refreshMode="complete">
<xp:this.action>
<xp:changeDocumentMode mode="edit" var="document1">
</xp:changeDocumentMode>
</xp:this.action>
</xp:eventHandler>
</xe:tabBarButton>
Saving a document in a Mobile Page
The Save button contains a simple action specific to XPages Mobile applications. It’s called a moveTo simple action as in Figure 5.2 and in this exercise it is used to save the document and then navigate to ‘viewPage’ page. It also contains how the page will transition once the action is called. Here the page will transition in a slide pattern and the direction will be right-to-left.
This Tab Bar Button has it's rendered property computed as well, set to be visible when the document is in Edit mode as shown in Listing 5.3.
Figure 5.2
Tab Bar and Tab Bar Button Markup
This example also includes a Cancel button though not entirely necessary as there is a back button on the header of the mobile page. Here we've included it as a further example in Listing 5.3.
Listing 5.3
<xe:tabBar id="documentTabBar" barType="segmentedControl">
<xe:tabBarButton id="tabBarButtonCancel" label="Cancel">
<xp:eventHandler event="onclick" submit="true"
refreshMode="complete" immediate="true" save="false">
<xp:this.action>
<xe:moveTo targetPage="viewPage" transitionType="slide"
direction="Right to Left"></xe:moveTo>
</xp:this.action>
</xp:eventHandler>
</xe:tabBarButton>
<xe:tabBarButton id="tabBarButtonEdit" label="Edit"
rendered="#{javascript:!document1.isEditable()}">
<xp:eventHandler event="onclick" submit="true"
refreshMode="complete">
<xp:this.action>
<xp:changeDocumentMode mode="edit" var="document1">
</xp:changeDocumentMode>
</xp:this.action>
</xp:eventHandler>
</xe:tabBarButton>
<xe:tabBarButton id="tabBarButtonSave" label="Save"
rendered="#{javascript:document1.isEditable()}">
<xp:eventHandler event="onclick" submit="true"
refreshMode="complete">
<xp:this.action>
<xe:moveTo forceFullRefresh="true" saveDocument="true"
targetPage="viewPage" transitionType="slide" direction="Left to Right">
</xe:moveTo>
</xp:this.action>
</xp:eventHandler>
</xe:tabBarButton>
</xe:tabBar>
Screenshot of the document in read mode with the Tab Bar and buttons
Figure 5.3 shows the document opened in read mode with the Tab Bar now visible at the top.
Figure 5.3
Screenshot of the document in Edit mode with the Tab Bar and buttons
Selecting the Edit button changes the mode to editable as shown in Figure 5.4.
In this example we have set the Subject and Category fields to be editable where we can now make changes. Selecting the Save button now submits these changes to the document. The Cancel button can also be used there to disregard those changes.
Figure 5.4
Using the actionFacet on the Header for Events
On mobile applications, it's usual that some action events to be activated from header on the right hand side; creating and saving documents. The actionFacet is available here to facilitate this in XPages mobile apps. And the developer may find that this is the preferable way to include actions on a mobile page and not have an area of the mobile screen being used up by a Tab Bar.
XPages buttons (xp:button) can be dropped into this area and it will inherit the styling from the Mobile Theme from the 853 Extension Library as shown in Figure 5.5 and without any extra styling needed.
Figure 5.5
Listing 5.4 show the markup used for the button shown in Figure 5.5. It also shows that the rendering of the Edit button is dependant on the mode of the document data source. And likewise when the document is in edit mode and Save button will display in place of the Edit button in the actionFacet. These buttons are contained within a panel which is set to be a facet of the Heading and the pane is identified with this heading facet by using the callback key to this particular facet xp:key="actionFacet".
Notice too in Listing 5.4 that the Panel that contains the document data source also now contains the Heading control as it now needs to see the data source.
Listing 5.4
<xp:panel>
<xe:djxmHeading id="documentPageHeading" back="Back"
label="Document" moveTo="viewPage">
<xp:this.facets>
<xp:panel xp:key="actionFacet">
<xp:button value="Edit" id="button1"
rendered="#{javascript:!document1.isEditable()}">
<xp:eventHandler event="onclick" submit="true" refreshMode="complete">
<xp:this.action>
<xp:changeDocumentMode mode="edit"
var="document1">
</xp:changeDocumentMode>
</xp:this.action></xp:eventHandler></xp:button>
<xp:button value="Save" id="button2"
rendered="#{javascript:document1.isEditable()}">
<xp:eventHandler event="onclick" submit="true"
refreshMode="complete">
<xp:this.action>
<xe:moveTo direction="Right to Left"
forceFullRefresh="true" saveDocument="true"
targetPage="viewPage" transitionType="slide">
</xe:moveTo>
</xp:this.action>
</xp:eventHandler>
</xp:button>
</xp:panel>
</xp:this.facets>
</xe:djxmHeading>
<xp:this.data>
<xp:dominoDocument var="document1" formName="MainTopic">
</xp:dominoDocument>
</xp:this.data>
...
Create a new document.
The final mobile page in this tutorial is for composing new documents in a mobile device.
- This mobile page is just like the documentPage but called 'newDocumentPage'.
- It contains a Heading, which will also contain navigation and page title.
- Again as this is a document a Rounded Rectangle container to provide the look-and-feel for documents in a mobile device.
- Also in this container is another conventional XPages Panel which in turn will contain the document data source along with inputs for the various fields bound to a document data source.
- This page also contains another Tab Bar with a single Tab Bar Button. This button uses a moveTo Simple Action to save the document and transition back to the 'viewPage' as shown in Listing 6.1
New Document Page Markup
Listing 6.1
<xe:appPage id="appPage4" pageName="newDocumentPage"
preload="true" resetContent="true">
<xe:djxmHeading id="newDocumentPageHeading" label="New Document"
back="Cancel" moveTo="viewPage">
</xe:djxmHeading>
<xp:panel>
<xp:this.data>
<xp:dominoDocument var="document1" formName="MainTopic"
computeWithForm="onsave">
</xp:dominoDocument>
</xp:this.data>
<xe:tabBar id="newDocumentTabBar" barType="segmentedControl">
<xe:tabBarButton id="tabBarButtonSubmit" label="Submit">
<xp:eventHandler event="onclick" submit="true"
refreshMode="complete">
<xp:this.action>
<xe:moveTo forceFullRefresh="true" saveDocument="true"
targetPage="viewPage" transitionType="slide" direction="Left to Right">
</xe:moveTo>
</xp:this.action>
</xp:eventHandler>
</xe:tabBarButton>
</xe:tabBar>
<xe:djxmRoundRectList id="djxmRoundRectList1">
<xp:label value="Subject: " id="labelSubject2"></xp:label>
<xp:inputText id="inputTextSubject2" value="#{document1.Subject}">
</xp:inputText>
<xp:br />
<xp:label value="Category: " id="labelCategory2"></xp:label>
<xp:inputText id="inputTextCategory2" value="#{document1.NewCats}">
</xp:inputText>
<xp:br />
<xp:inputTextarea id="inputTextareaBody" value="#{document1.Body}"
cols="40" rows="10">
</xp:inputTextarea>
</xe:djxmRoundRectList>
</xp:panel>
</xe:appPage>
New Document Button
So now that the new document page has been created, we need a way to initiate this page. We do this with a compose new document button on the 'viewPage'.
- To create something new on a mobile application it is usual to use a button a plus '+' symbol as its label, and for XPages mobile applications it's no different. A conventional XPage button (xp:button) is added to the Heading control's actionFacet of the 'viewPage' with it's value set to a plus '+' symbol.
- For it's action we can use a client side onclick event to link to a different location on the XPage namely the 'newDocumentPage' - location.href="#newDocumentPage". Or like what is shown in Listing 6.2 a moveTo simple action is used targeting the same 'newDocumentPage'.
Additional styling is needed here to the 'plus' button and this is to set the Font Size of the of the plus sign so that it displays like a typical mobile '+' button.
Listing 6.2
<xp:this.facets>
<xp:button value="+" id="actionFacetButton1" xp:key="actionFacet"
style="font-size:24pt">
<xp:eventHandler event="onclick" submit="true"
refreshMode="complete">
<xp:this.action>
<xe:moveTo targetPage="newDocumentPage"
transitionType="slide" direction="Left to Right"
forceFullRefresh="true">
</xe:moveTo>
</xp:this.action>
</xp:eventHandler>
</xp:button>
</xp:this.facets>
...
Screenshot of the Plus button
Figure 6.1 shows the plus button in the heading of the viewPage mobile page.
Figure 6.1
Composing a new document in action
Selecting the plus button navigates the user to the newDocumentPage as shown in Figure 6.2.
Figure 6.2
Here the fields can be filled in, and selecting Submit tab bar button saves the document which also transitions the user back to the 'viewPage' as shown in Figure 6.3.
Figure 6.3
This new document can now be viewed and updated from the Data View in the document page as shown in Figure 6.4
Figure 6.4
Delete a Document
Deleting document on a XPages Mobile application can be handled in very much the same way as it is done in conventional XPages. 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 another Tab Bar Button to the Tab bar on the documentPage.
- With the Tab Bar button added,
- select the Events view tab 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 7.1.
Figure 7.1
- We then group this delete document simple action with another, Move To Mobile Page, simple action. Here we set the targetPage to the viewPage, and the transitionType and direction as shown in Figure 7.2.
Figure 7.2
This should give us the following markup in Listing 7.1.
Listing 7.1
<xe:tabBarButton id="tabBarButtonDelete"
rendered="#{javascript:!document1.isEditable()}" label="Delete">
<xp:eventHandler event="onclick" submit="true"
refreshMode="complete">
<xp:this.action>
<xp:actionGroup>
<xp:deleteDocument name="" var="document1"
message="This action will delete the current document.">
</xp:deleteDocument>
<xe:moveTo targetPage="viewPage" transitionType="slide"
direction="Right to Left"></xe:moveTo>
</xp:actionGroup>
</xp:this.action>
</xp:eventHandler>
</xe:tabBarButton>
And when we run this on the mobile device we will now see this delete button appearing on the Tab Bar as in Figure 7.3.
Figure 7.3
And when selected, we get the confirmation message to OK this action as shown in Figure 7.4
Figure 7.4
And this should then transition back to the viewPage as shown in Figure 7.5.
Figure 7.5
Conclusion
Thus ends this tutorial to build a simple mobile application inside an existing Domino\IBM XWork application using the new XPages Mobile controls. And this complete XPages markup has been attached to this document.
For more examples on how to use these control a good example is available on the XPages Extension Library Demo App. And real live working example are now available on the extended TeamRoom and Discussion Templates which are also available from the OpenNTF download.
A sample of the completed tutorial is available is attached to this document.
FAQ
How to use Mobile Switch control? Any examples?
The Mobile switch control is like an on\off switch and for an example try the following. This control has a number of events associated with it.
The 'OnTouch*' events for Start, Move and End are all particular to the mobile device and are activated by the finger; similar to the mouse events in web apps. And the onStateChange event fires when the state of switch is changed.
<?xml version="1.0" encoding="UTF-8"?>
<xp:view xmlns:xp="http://www.ibm.com/xsp/core" xmlns:xe="http://www.ibm.com/xsp/coreex">
<!--<xp:this.beforePageLoad><![CDATA[#{javascript:viewScope.put("vs01","on")}]]></xp:this.beforePageLoad>
--><xe:singlePageApp id="singlePageApp1"
selectedPageName="h01">
<xe:appPage id="appPage1" pageName="h01">
<xe:djxmHeading id="djxmHeading1" label="Mobile Switch Test">
</xe:djxmHeading>
OnTouchEnd test
<xe:djxmSwitch leftLabel="ON" rightLabel="OFF" id="djxmSwitch1">
<xp:eventHandler event="onTouchEnd" submit="true"
refreshMode="complete">
<xe:this.action><![CDATA[#{javascript:var v1 = viewScope.vs01;
if (v1!=="off"){viewScope.put("vs01","off")
}
else{viewScope.put("vs01","on")
}}]]></xe:this.action>
</xp:eventHandler>
</xe:djxmSwitch>
<xp:text escape="true" id="computedField1" value="#{viewScope.vs01}">
</xp:text>
<hr />
OnTouchStart test
<xe:djxmSwitch leftLabel="ON" rightLabel="OFF"
id="djxmSwitch2" value="#{javascript:viewScope.vs02}">
<xp:eventHandler event="onTouchStart" submit="true"
refreshMode="complete">
<xe:this.action><![CDATA[#{javascript:var v2 = viewScope.vs02;
if (v2!=="off"){viewScope.put("vs02","off")
}
else{viewScope.put("vs02","on")
}}]]></xe:this.action>
</xp:eventHandler>
</xe:djxmSwitch>
<xp:text escape="true" id="computedField2" value="#{viewScope.vs02}">
</xp:text>
<hr />
OnTouchMove test
<xe:djxmSwitch leftLabel="ON" rightLabel="OFF" id="djxmSwitch3">
<xp:eventHandler event="onTouchMove" submit="true"
refreshMode="complete">
<xe:this.action><![CDATA[#{javascript:var v3 = viewScope.vs03;
if (v3!=="off"){viewScope.put("vs03","off")
}
else{viewScope.put("vs03","on")
}}]]></xe:this.action>
</xp:eventHandler>
</xe:djxmSwitch>
<xp:text escape="true" id="computedField3" value="#{viewScope.vs03}">
</xp:text>
<hr />
OnStateChanged test
<xe:djxmSwitch leftLabel="ON" rightLabel="OFF"
id="djxmSwitch4" value="#{javascript:viewScope.vs04}">
<xp:eventHandler event="onStateChanged" submit="true"
refreshMode="complete">
<xe:this.action><![CDATA[#{javascript:var v4 = viewScope.vs04;
if (v4!=="off"){viewScope.put("vs04","off")
}
else{viewScope.put("vs04","on")
}}]]></xe:this.action>
</xp:eventHandler>
</xe:djxmSwitch>
<xp:text escape="true" id="computedField4" value="#{viewScope.vs04}">
</xp:text>
<hr />
</xe:appPage>
</xe:singlePageApp>
</xp:view>
Can any buttons other than the Back button in the Mobile Heading control
Yes. The Heading control is essentially a container for controls but it has a set height so there are limitations to what it can contain. It does have a callback\editable area called actionFacet where buttons can be added to and take on the styling from the Mobile theme.
The Tab Bar and Tab Bar buttons can also be added to the heading control.
Editing edit rich text is a problem in XPages, any solution
We're restricted here by CKEditor and for the version we use in 853 doesn't support mobile devices. This is a read problem for mobile especially iPad and other tablets upon which they can reasonably use the existing web application.
CKEditor have just released a version that does have better support so maybe we may have this in the next core release of Notes Domino.
Navigating to another XPage from a Mobile App Page using the moveTo action
The moveTo action is designed to be used within the same Single Page Application container control. If you need to navigate to another XPage it's recommended that the developer used conventional XPages techniques to do this like the Open Page simple action.
Is the View Panel supported in XPages Mobile Applications
All XPages controls will display in a XPages Mobile apps. However, not all of the controls will be covered by the XPages Mobile theme which provides the look and feel for the application on mobile devices.
How do you set the default (mobile) XPage when launched on a device
Right now in 853 the app developer can set the default XPages to launch when the application is opened in the Notes client or on the web browser client. There is nothing similar for Mobile devices be it smartphones or tablets.
The way to get around this is to have a default XPage for web browsers that would redirect to a particular XPage depending on the client the application is launched upon. This is how it is done in the TeamRoom XL and Discussion XL templates.
<?xml version="1.0" encoding="UTF-8"?>
<xp:view xmlns:xp="http://www.ibm.com/xsp/core" viewState="nostate"
rendered="false">
<xp:this.afterPageLoad>
<![CDATA[#{javascript:
var uAgent = context.getUserAgent().getUserAgent();
if((uAgent.match("iPhone") !== null || param.platform=="iphone") ||
(uAgent.match("Android") !== null || param.platform=="android") ||
uAgent.match("iPad") !== null){
context.redirectToPage("/mobile.xsp", true);
}else{
context.redirectToPage("/home.xsp", true);
}
}]]>
</xp:this.afterPageLoad>
</xp:view>
The Chrome browser sometimes displays the mobile app in a totally different way to that of the Android. Why aren't they the same?
This is probably because of caching on the browser.
The XPages runtime detects the User-Agent, like in the previous question, on the first request and will decide if it's a mobile browser. This is saved in the session so there isn't a need to check again (it would be a performance hit if this was to be repeated for every single request coming into the server). So to avoid issues like this the developer may want to set the User-Agent string, and this must set it before the browser hits the server, if not the browser will have to close and opened again.
A browser platform query string parameter is available for developers to force the browser to takes precedence over one another. Just add '?platform=iphone' or '?platform=android' to the URL and this will force the correct theme for XPages mobile pages that match against the xsp.theme.mobile.pagePrefix property.