Lotus what? Nah mate, the world has moved on.

Monday, 6 January 2014

IBM Notes and Domino Application Development : XPage Tutorials : XPages Mobile Controls Tutorial

Powerful but so complex. The future of this product is clear as mud.

IBM Notes and Domino Application Development : XPage Tutorials : XPages Mobile Controls Tutorial:

'via Blog this'


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

label="All Documents">


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

label="All Documents"


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
label="All Docs"





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



label="Subject: ">

label="Category: ">


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" totrue.
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




direction="Right to Left"

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

message="This action will delete the current document."

direction="Right to Left"

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


Post a Comment

Thank you for taking the time to comment. Your opinion is important and of value and we appreciate the positive feedback! If you are "Negative Nancy" then please do us, and humanity, a favor, and piss off.

Total Pageviews

Google+ Followers


Blog Archive

Popular Posts

Recent Comments

Rays Twitter feed


Web sites come and go and information is lost and therefore some pages are archived. @rayd123 . Powered by Blogger.