Single Page Application Wizardwith infinite Scroll…

Patrick Kwinten

14[Type the company name]

ContentsIntroduction.................................................................................................................................................2

Youtube....................................................................................................................................................2

Version.........................................................................................................................................................2

Terminology.................................................................................................................................................2

Setup development environment................................................................................................................2

IBM Domino 9.0.1....................................................................................................................................2

Domino Designer 9.0.1.............................................................................................................................2

Extension Library 901v00_03.20140120-0650.........................................................................................3

Fake names..............................................................................................................................................3

Browser plugin for switching User Agent.................................................................................................3

Application configuration.............................................................................................................................3

Project scope................................................................................................................................................6

Mobilization Step by Step.............................................................................................................................7

Step: Create an XPage..............................................................................................................................7

Step: Drag in the Single Page Application control....................................................................................7

Step: Configure the Application Pages with the wizard............................................................................7

Create Application Navigator page.......................................................................................................8

Create General page.............................................................................................................................9

Create Document Collection pages......................................................................................................9

Create Document Viewer pages.........................................................................................................12

Configure the Application Pages.........................................................................................................14

Temporarily Result.............................................................................................................................27

Completion.............................................................................................................................................35

Summary....................................................................................................................................................35

Infinite Scroll..........................................................................................................................................36

Recommendations.................................................................................................................................36

Screenshots................................................................................................................................................37

IntroductionThis document describes the Single Page Application wizard that is part of the Extension Library release 901v00_03.20140120-0650, which was released 24 January 2014 on OpenNTF.

A new property, "infiniteScroll", has been added to the Data View control which will allow for touch scrolling of a document collection list in XPages mobile apps. It can be enabled on the Data View control itself, or through the application's xsp.properties if all the Data Views are contrained within mobile applications. 

Another new mobile feature to this release is the Single Page App Wizard. This is activated when the Single Page Application (xe:singlePageApp) control is added to a XPage. The developer has then the option to create the basic framework for a complete XPages mobile application, dramatically cutting down on the design time needed." 

YoutubeThe Single Page Application (SPA) and infiniteScroll property are also demonstrated in an instruction video on Youtube.

VersionDate Version Author Remark2014-02-13 0.1 Patrick Kwinten Initial draft

TerminologyTerm RemarkXPages Rapid web and mobile application development technology. It allows

data from IBM Notes and Relational Databases to be displayed to browser clients on all platforms.

Setup development environment

IBM Domino 9.0.1For simplicity we assume you run an IBM Domino 9.0.1 server. Here you can find instructions how to download it from IBM’s Passport Advantage site.

Domino Designer 9.0.1You can download (for free) Domino Designer 9.0.1 at IBM Software site.

Extension Library 901v00_03.20140120-0650You can download the library (of course) from OpenNTF.

Locationhttp://www.openntf.org/main.nsf/project.xsp?r=project/XPages%20Extension%20Library/releases/8DFE49ADFE1CD56686257C6A003F7618

Note: You need to install the library both on the Domino server as Domino Designer.

Fake namesIn this document we will demonstrate the SPA wizard by example. As example application we will use the infamous ‘Fake Names’ application. The Fake Names application is an address book like application.

You can download an instance of it on the following addresses:

Locationhttp://www.codestore.net/store.nsf/unid/BLOG-20070104http://xpagescheatsheet.com/cheatsheet.nsf/home.xsp

In this document we have downloaded the Fake Names application from Codestore which is considerable out of date.

The main reason for this is that the Fake Names application from Codestore has a categorized People by Organization view in it. Note that all default names are grouped under the ROCKALL organization. You need to alter some Person documents in order to have multiple categories in the People by Organization view.

Browser plugin for switching User AgentPerhaps you develop the application in a (local) virtual environment. This environment is probably not directly accessible by a mobile device.

In such case you will test the application in a web browser and mimic the user agent of a mobile device. Most browsers have developer tools to do this or ease switching user agents by a add-on.

Application configuration Open the Fake Names application in Domino Designer. Open the XSP Properties file:

Set the following properties:o Enable ‘Use mobile there for XPages with the prefix:’.

Keep the default m_ value.

o Select a mobile theme: Mobile default.

OneUI DX V1.3. Select this option.

The Mobile default theme looks like the UI of a standard native app for the mobile device. This depends per device (Android, iPhone).

User Agent set to iPone:

The OneUI IDX V1.3 theme is the UI that is reused across multiple IBM products (Connections, iNotes).

Project scopeIn this tutorial we are going to mobilize partly the Fake Names application. We choose to mobile:

Some views with Person info:o ‘People’.o ‘People By Organization’.

The ‘Group’ view. The Configuration view with ServerParameter info (‘Server\Configurations Parameters’). The Configuration view with Holiday info (‘Server\Holidays’).

That is about all the information (documents) that is available in the application.

For each view we will create a ‘mobile page’ with a list of documents, and for each document type (form) we will also create a mobile page.

The ‘mobile interface’ of the Fame Names application starts with a mobile page that contains links to the several ‘views’.

There will also be a mobile page with some information about the application.

Page RemarkStartpage (static) Mobile page setup as start page for the mobile

interface. The page contains a menu that directs to other mobile pages:

People People by Organization Groups Configuration – Parameters Configuration – Holidays

About (static) Page which some information about the application.People Displays a (flat) list of Person documentsPeople by Organization Displays a categorized list of Person documents by their

organization.Groups Displays a (flat) list of Group documents.Parameters Displays a (flat) list of ServerParameter documents.

Holidays Displays a (flat) list of Holiday documents.Person Displays information on a Person document.Group Displays information on a Group document.Parameter Displays information on a ServerParameter document.Holiday Displays information on a Holiday document.

Mobilization Step by StepIt is now time to start the development.

Step: Create an XPage Create an XPage and give it a name that starts with the chosen prefix (m_) e.g. m_index.xsp.

Step: Drag in the Single Page Application control Open the Mobile palette. Select the Single Page Application control and drag it on Design pane of

the XPage.

Step: Configure the Application Pages with the wizardWhen you drop the control on the Design pane a wizard pops up:

Keep the checkbox ‘Create a Custom Control for the content of each Application Page’ selected.

From here you will define the available mobile pages.

Create Application Navigator page Select ‘New’. Enter a name for the Application Page e.g. Main. Select as Type ‘Application Navigator’. Press ‘OK’.

Create General page Select ‘New’. Enter a name for the Application Page e.g. About. Select as Type ‘General. Press ‘OK’.

Create Document Collection pages

Create Document Collection page for People Select ‘New’. Enter a name for the Application Page e.g. People. Select as Type ‘Document Collection’. Select ‘OK’.

Create Document Collection page for People by Organization Again select ‘New’. Enter a name for the Application Page e.g. PeopleByOrganization.

o Notice that spaces are not allowed in the name. Select as Type ‘Document Collection’. Select ‘OK’.

Create Document Collection page for Groups Again select ‘New’. Enter a name for the Application Page e.g. Groups. Select as Type ‘Document Collection’. Select ‘OK’.

Create Document Collection page for Parameters Again select ‘New’. Enter a name for the Application Page e.g. Parameters. Select as Type ‘Document Collection’. Select ‘OK’.

Create Document Collection page for Holidays Again select ‘New’. Enter a name for the Application Page e.g. Holidays. Select as Type ‘Document Collection’. Select ‘OK’.

Create Document Viewer pages

Create Document Viewer page for Person (document) Select ‘New’. Enter a name for the Application Page e.g. Person. Select as Type ‘Document Viewer’. Select ‘OK’.

Create Document Viewer page for Group (document) Select ‘New’. Enter a name for the Application Page e.g. Group. Select as Type ‘Document Viewer’. Select ‘OK’.

Create Document Viewer page for Parameter (document) Select ‘New’. Enter a name for the Application Page e.g. Parameter. Select as Type ‘Document Viewer’. Select ‘OK’.

Create Document Viewer page for Holiday (document) Select ‘New’. Enter a name for the Application Page e.g. Holiday. Select as Type ‘Document Viewer’. Select ‘OK’.

Configure the Application Pages Select Next. This will open a new dialog.

Configure Application Page ‘Main’ Change the Label in the Page Heading section to ‘Address Book’. Enter ‘About’ in the Tool Bar Buttons field. Select ‘Next’.

The action above will lead the following result:

Configure the entries for the Application NavigatorThe following dialog will appear for an Application Navigator page:

Here you will set the items or entries that will appear in your ‘navigation menu’.

Select ‘New’. Enter a label for the entry e.g. People. Select as Target Page ‘People’. Select ‘OK’.

Repeat the steps above for People by Organziation, Groups, Paramaters and Holidays:

As a result your dialog should look as followed:

Select ‘Next’.

Configure Application Page ‘About’The dialog for Application Page ‘About’ contains already all the items that we want:

A label for the Page Heading. A Back Button that returns the user to the Main page.

Select ‘Next’.

Configure Application Page ‘People’The dialog for Application Page ‘People’ contains already all the items that we want:

A label for the Page Heading. A Back Button. Set the Target Page however to ‘Main’.

Also include a Tab Bar Button labeled ‘Add’. First you need to mark the checkbox ‘Add a Tab Bar’. Select ‘Next’.

Since this Application Page is set as a Document Collection type the following dialog appears:

Select for the View ‘_People – People’ as data source. Give the Data source a name e.g. viewPeople. Select ‘Next’.

The following dialog will appear:

Select the Summary column. Choose from the list ‘Name’. Set the Target Page to ‘Person’. Keep the Infinite scroll option on ‘Enabled’. Select ‘Next’.

Repeat this process for the other Document Collection Application Pages PeopleByOrganization, Groups, Parameters and Holidays. Play around a little with the options if you like.

Configure Application Page ‘Person’Next the dialog for the Person Application Page appears.

Set the Back Button, e.g. to the People Application Page. Add some common Tab Bar Buttons e.g. Close, Edit, Save, Cancel.

Select ‘Next’.

A second dialog for the Person Application Page appears.

Select the Person form as source. Enter a name for the Data source. Select a default action. Select a form validation event.

Select ‘Next’.

A third dialog for the Person Application Page appears. Here you must select the fields on the selected Person form you want to display.

Default all fields are presented. So you basically delete the fields you do not want to display. Below you find an example of selected fields.

Select ‘Next’.

Repeat the same process for the Group, Parameter and Holiday Application Pages.

Configure Initial PageA final dialog appears. It summarizes the total of Application Pages and asks what Application Page should be set as Initial Page (the page to be opened first when accessing the XPage).

Select Main as Initial Page. Select ‘Finish’.

Temporarily ResultAs a result the custom controls for the Application Pages are being created.

The XPage m_index.xsp contains all these automatically created custom controls:

Save the XPage. Preview the XPage.

Below is a screendump of the result so far:

You can navigate between the different Document Collection Pages back and forth. You can open the Document Viewer Pages.

However you cannot open the About Application Page yet. Also the Tab Bar Button ‘Add’ on the Document Collection Pages is not working. Likewise the Tab Bar Buttons Close, Edit, Save and Cancel on the Document Viewer Pages. These you have to set separately on the Custom Controls.

Apply Navigation to the About Application Page. Open the Custom Control ccMain. Allocate the About Button. Add an Server Action to it.

Select as category ‘Mobile’. Select as action ‘Move to Application Page’. Set as targetPage the Application Page ‘About’.

o The other properties are optional to specify explicitly. Select ‘OK’.

Save the Custom Control.

Update the Add buttonsOn each Document Collection Application Page we have included a Tab Bar Button to add new documents. The wizard did not place any action under these buttons so we need to set them separately.

Below is an example how to add the action for the Add Tab Bar Button on the People Application Page:

Select as Category ‘Mobile’. Select as Action ‘Mobe To Application Page’. Choose a direction. Set the forceFullRefresh property to ‘true’. Set the loaded property to ‘true’. Set the saveDocument property to ‘false’. Set the targetPage property to ‘Person’. Choose a transitionType.

Select ‘OK’.

Repeat the process above for the Add Tab Bar Buttons for the other Document Collection Application Pages “People by Organization”, “Groups”, “Parameters” and “Holidays”. Set the targetPage property to the corresponding Document Viewer Application Page.

Update the Close, Edit, Save & Cancel buttonsThe wizard did not place any action under these buttons so we need to set them separately. Below is an example how to add the action for the Close, Edit, Save and Cancel Tab Bar Button on the Person Application Page:

Close buttonThis button should only be displayed when the document is in read mode. It should “close” the Person document and return the user to the People’s view.

<xe:tabBarButton id="tabBarButton1" label="Close" rendered="#{javascript:!docPerson.isEditable()}"

<xp:eventHandler event="onClick" submit="true" refreshMode="complete">

<xe:this.action><xe:moveTo direction="Right to Left" forceFullRefresh="false"

saveDocument="false" targetPage="People"></xe:moveTo></xe:this.action>

</xp:eventHandler></xe:tabBarButton>

Edit buttonThis button should also only be displayed when the document is in read mode. It should change the document mode into edit mode.

<xe:tabBarButton id="tabBarButton2" label="Edit" rendered="#{javascript:!docPerson.isEditable()}">

<xp:eventHandler event="onClick" submit="true" refreshMode="complete"><xe:this.action>

<xp:changeDocumentMode mode="edit" var="docPerson"></xp:changeDocumentMode>

</xe:this.action></xp:eventHandler>

</xe:tabBarButton>

Save buttonThis button should also only be displayed when the document is in edit mode. It should save the Person document while “closing” it and move back to the People’s view. Note it should force a full refresh of the target page.

<xe:tabBarButton id="tabBarButton3" label="Save" rendered="#{javascript:docPerson.isEditable()}">

<xp:eventHandler event="onClick" submit="true" refreshMode="complete"><xe:this.action>

<xe:moveTo direction="Right to Left" forceFullRefresh="true" saveDocument="true" targetPage="People" transitionType="slide"> </xe:moveTo>

</xe:this.action></xp:eventHandler>

</xe:tabBarButton>

Cancel buttonThis button should only be displayed when the document is in edit mode. It should not save the Person document while “closing” it and move back to the People’s view.

<xe:tabBarButton id="tabBarButton4" label="Cancel" rendered="#{javascript:docPerson.isEditable()}">

<xp:eventHandler event="onClick" submit="true" refreshMode="complete"><xe:this.action>

<xe:moveTo targetPage="People" direction="Right to Left"forceFullRefresh="false" saveDocument="false"transitionType="slide">

</xe:moveTo></xe:this.action>

</xp:eventHandler></xe:tabBarButton>

When you save the changes and preview your work you will notice that an error message is displayed when opening a Person document. This is caused by the fact that the docPerson data source is connected to a panel and the tab bar buttons are placed outside that panel. In order to make the code work you should relocate the opening panel tags so they include the Tab Bar. It might be even recommended to include the Page Heading control within the data source panel so you e.g. can populate a custom header title.

Below is a snippet how your page could like from the start:

<?xml version="1.0" encoding="UTF-8"?><xp:view id="view1" xmlns:xe="http://www.ibm.com/xsp/coreex" xmlns:xp="http://www.ibm.com/xsp/core"><xp:panel> <xe:djxmHeading back="Back" id="djxmHeading1" label="Person" moveTo="People">….</xe:djxmHeading>….<xp:this.data> <xp:dominoDocument formName="Person" var="docPerson" loaded="true" /> </xp:this.data> </xp:panel></xp:view>

Repeat the process above for the Close, Edit, Save and Cancel Tab Bar Buttons for the other Document Viewer Application Pages “Group”, “Parameters” and “Holidays”. Set the targetPage property to the corresponding Document Collection Application Page.

CompletionYou have now mobilized the fake names application in XPages! Users can navigate through different sets of documents, open and read their information, create new documents or update them.

SummaryWith the Single Page Application control you can rapidly mobilize a Notes application. The wizard is intuitive although you need to understand some basics of mobile development.

Unfortunately the wizard is not complete and forces you to apply some coding.

Infinite ScrollThe infiniteScroll property for a Data View control is enabled by default in the Singe Page Application. This great new feature allows users to fetch new rows of data by scrolling down the list.

You would almost be stupid to disable this feature.

Recommendations Ability to apply basic CRUD Tab Bar Buttons to a Document Viewer Application Page. On a Document Viewer page is viewer page it would be easier to add fields instead of removing

most of all the fields that would otherwise be applied by default. In mobile apps the number of fields you want to display is probably less than in a Notes client application.

Ability to re-open the wizard after you have pressed ‘Finish’. It would be great to have message popups when a user performs an action that he/she is not

allowed to do. At the current stage there is default no mechanism for this. Examples: “You are not authorized to perform this action”, “You have insufficient access rights”.

Screenshots

Figure: Main Application Page.

Figure: People Document Collection Application Page.

Figure: Person Document Viewer Application Page.

Figure: Person Document Viewer Application Page in edit mode.