. 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
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
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 of the 'viewPage' with it's value set to a plus '+' symbol.
- For it's action we use a client side onclick event to link to a different location on the XPage namely the 'newDocumentPage' - location.href="#newDocumentPage".
Plus Button Styling
The next step for the plus button is to change it's styling. If we were to use the default styling, the button would be difficult for the user to use as well as being positioned and styled incorrectly for the use case.
The styling of this button will differ between mobile devices. The styling below in Listing 6.2 is typically for iOS (iPhone and iPad).
Listing 6.2
<xp:button value="+" id="button2"
style="float:right;
position:static;
margin-top:6px;
margin-right:5px;
height: 30px;
width: 30px;
padding: 2px 0px 0px 0px;
border-style: inset;
border-color: #9CACC0;
font-family: Helvetica;
font-size:26px;
font-weight:bold;
color: white;
line-height: 5px;
cursor: pointer;
-webkit-border-radius: 5px;
-moz-border-radius: 5px;
background-color: #5877A2;
background: -webkit-gradient(linear, left top, left bottom, from(#8EA4C1), to(#4A6C9B), color-stop(0.5, #5877A2), color-stop(0.5, #476999));
-webkit-tap-highlight-color: transparent;">
<xp:this.onclick>
<![CDATA[location.href="#newDocumentPage";]]>
</xp:this.onclick>
</xp:button>
For Andriod it's slightly different, mainly around the colour of the text, background and shading as shown in Listing 6.3.
Listing 6.3
float:right;
position:static;
margin-top:0px;
margin-right:5px;
height: 25px;
width: 25px;
padding: 2px 0px 0px 0px;
border-style: inset;
border-color: #3F3E3E;
font-family: Helvetica;
font-size:26px;
font-weight:bold;
color: white;
line-height: 5px;
cursor: pointer;
-webkit-border-radius: 5px;
-moz-border-radius: 5px;
background-color: #ADADAD;
background: -webkit-gradient(linear, left top, left bottom, from(#E5E5E5), to(#7F7F7F), color-stop(0.5, #ADADAD), color-stop(0.5, #909090));
-webkit-tap-highlight-color: transparent;
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.
(See attached file: XPages Mobile Controls Tutorial Complete Sample.txt)