But when I first discussed the approach with David Leedy many weeks ago, his requirement was somewhat different. The users of his mobile application would always be connected; they would not be roaming; so connectivity was not an issue and avoiding server-side interaction was not a concern. I am sure his situation is not unique, so I have followed his advice and am going to cover a server-side approach.

The first thing worth noting is on the “user” mobile page itself. I’m going to jump to this because it will impact the changes for the rest of the XPage. Whereas for the client-side approach the default setting of resetContent=”false” was used, for the server-side approach the mobile page will take the setting resetContent=”true”. As a result, I also need to change the dominoDocument datasource settings. Because resetContent is true, I need to ensure the mobile page knows which document I’m dealing with when I switch to the value picker and come back. So the action property is “editDocument” instead of “newDocument” and the documentId is set to “#{viewScope.documentId}”.

As a result, there need to be two changes to the New User button and the links in the view of existing users. The first is that I’m not using the queryString and don’t have to forceFullRefresh. So the “Move To App Page” simple action just switches to the “user” mobile page. The second change is I need to set viewScope.documentId – to null on the New User button (code shown below) and to the current entry’s ID in the view.

On the Submit button on the user page, I then need to clear viewScope.documentId.

For the Select State button, previously I used Client-Side JavaScript to switch to the stateSelector mobile page. I’m assuming good connectivity, so I use a Server-Side event – again the “Move To App Page” simple action.

The final change is on the link for each state. Again, I’m assuming good connectivity, so using the “Move To App Page” simple action to switch back to the user page. I’m also executing Server-Side JavaScript to run getComponent(“inputText3″).setValue(state.getColumnValue(“Key”)). So I’m setting the value directly in the component before switching back to the mobile page. Because it’s in the same XPage, I can do that.

So the differences are very minor, but all highlighting the different approach – the first avoids server-side events as much as possible, the second embraces them. I’ve attached the code below, and if you want to compare them, I would strongly recommend that after you add the XPage to the sample application, you go to the Project Explorer view and navigate to the two XPages. Select them both (holding down Ctrl), right-click and select Compare With – Each Other….

Mobile_ExistingUser_SSJS

If you would like to see the full video, follow the link above.

First of all, I’ve moved the New User button into the Page Heading control’s action facet. Again I use the Move to Application Page simple action, setting targetPage to “user” and setting forceFullRefresh to “true”. It’s important to do this. Otherwise, the user will be editing the previous contact instead of creating a new one. The code for this button will look very familiar:

Next I add a dataView control pointing to the AllContacts view. I’ve set to load 10 rows, but you’ll want to extend this to allow the user to add rows and save the state. If you’ve looked at the Discussion XL template, you’ll know exactly how to do that.

Instead of just adding a summaryColumn and setting the pageName property, I’ve added a panel to the detail facet. In that panel I’ve placed a Link control showing the contact’s name and email. I’ve added an onclick event to the Link setting forceFullRefresh to “true” and setting the targetPage to open the current document in edit mode, redirecting to the user page. If you’re relatively new to XPages, the Link text and targetPage may look strange, because I’m combining literal strings, Expression Language and Server-Side JavaScript. Read my blog post on combining languages from a couple of years ago for more. So the code for the dataView is this:

On the user page, resetContent is still set to “false”. The only difference here is a minor change on the State field. If the field is set with disabled as “true”, the value does not save into an existing field. If you wanted to prevent the user typing into the field, there are ways to do that, like adding code to the onfocus event of the field to move focus to the button.

The full new code is attached.

Mobile Page for Editing and Creating Contact

In this part I will demonstrate a predominantly client-side approach, picking options from a view. But the same technique could equally be used to select from a static list of options or options retrieved from a keyword document or Server-Side JavaScript / Java function. The database I’ll be using is the XPages Extension Library Demo database, creating a mobile interface to create a simple contact. The picker will select states.

The first step is to create an additional view in the database, because the AllStates view is not sorted. I’ve just created a copy of the view, switched the columns round, and sorted the Name column, as below:

So now onto the Mobile Page. The code for the XPage is attached at the bottom of this post. A dominoDocument datasource is bound to the XPage and uses the Contact form, with action=”newDocument”.

The Single Page Application mobile control is added – the container for the mobile pages, with the selectedPageName set to “welcome”. The first Mobile Page control is added with the pageName “welcome”. This has a Page Heading control and a Static Line Item which will move to the “user” page. This will be the page for creating a new user. What we have so far is below:

Another Single Page control is added. The key is ensuring resetContent is still set to “false” – we don’t want to reload the content every time we go to the page. Otherwise, we’ll lose all previously entered values. But this has other implications, as we will see later. Next a Single Page Heading and Form Table control are added. The details for most are not important. The focus at this point is on formRow4. The Edit Box with id inputText3 has disabled set to “true”, so the user cannot type into the field but a value can be written to it via Client-Side JavaScript and stored via the value binding to document1.State. This is standard functionality that might equally be seen in an XPage designed for desktop browsers.

Alongside the Edit Box, a Button is added. When designing for desktop browsers this would launch the Value Picker, but here it just runs Client-Side JavaScript to set location.href=”#stateSelector”. If you’ve used the Mobile Controls much (or the Dynamic Content controls – the concept is the same for both), you will have noticed that anchor tags (the #) are used to navigate between areas of the page. So setting location.href=”#stateSelector” is the same as setting moveTo on a Page Heading or Static Line Item control, and moves to the stateSelector Mobile Page. formRow4 looks like this:

For the moment, skip directly to the stateSelector Mobile Page, which is the interface to allow the user to select states. In normal XPages desktop browser interface, this is what would be the Value Picker. The Mobile Page contains a Page Heading, with the Back button given the label “Cancel” and moveTo value set to “user”. A Rounded List is then added, just to provide a nice mobile-styled container.

Typeahead filtering is provided via the search1 Edit Box. The value is bound to a viewScope variable called “search” and an onkeyup event applied to partially refresh the element “refreshPanel”. This typeahead filtering is only added because the user is selecting from a view with a large number of options. If the options are limited, this wouldn’t be required and should be avoided in order to further minimise calls to the server. This particular implementation adds no styling to the Edit Box. If you want to make it look nicer, look at the mobileSearch Custom Control in the Discussion XL template that comes with the Extension Library for 8.5.3.

Below the Edit Box the refreshPanel Panel control is added. A dominoView datasource is bound to this Panel, using the “Copy of AllStates” view. The keys property is set as “#{viewScope.search}”, to use what the user enters into the search1 Edit Box, and keysExactMatch is set to “false” so it only does a partial match. Again, if picking from a smaller list, this filtering will not be required. If picking from a Keyword document, ViewEntryCollection, Java bean or some other element, the filtering will need to be handled differently. That is generic XPages functionality and not mobile-specific, so out of the scope for this series.

The options for the user to select from are held in a Repeat Control bound to the dominoView datasource with the variable name “state”. In this example only 10 rows are shown, no pagers are provided, because the typeahead should be used to filter. Again, I’m not going to go into details on what to do if you need other functionality.

The contents of the Repeat Control are slightly unusual, so I will elaborate. What we want to do is capture the value of the row clicked, move pack to the user Mobile Page, and pass the value back to the inputText3 Edit Box that is bound to document1.State. If resetContent were set to “true” on that mobile page, we could pass the value into the query string and retrieve it. But if we were to set resetContent on the user Mobile Page to “true”, the page would get reloaded every time the user redirected to it, and so previously entered values would be lost. The initial thought may be to compute the resetContent property on the user page, for example, based also on a query string parameter. But like Server-Side JavaScript in a Client-Side JavaScript Script Block, the setting used when the page is shown is the result of the computation the previous time the page was rendered. So the query string parameter would not take effect when the user switches to the page, but instead, the next time the user switches to the page.

So we need to run code to switch the page and on the completion of that, set the field. We can do all that in Client-Side JavaScript. Within the Repeat Control there is a Div using the styleClass “mblListItem”. This simulates the Static Line Item control. Within the Div is a Label control whose value is “#{state.Name}” – the Name column from the view. The Label has an onclick eventHandler with submit=”false”. First, as with the Select State button, we set location.href=”#user” to move back to the user Mobile Page. Next we call dojo.byId(“#{id:inputText3}”.value=”#{javascript:state.getColumnValue(‘Key’)}”. This gets the inputText3 Edit Box via Client-Side JavaScript and write to it the value from the Key column for the relevant row. Note that using Expression Language (“#{state.Key}”) in the eventHandler will cause the Mobile Page to fail. Adding the eventHandler to the div does not work here.

Finally, back on the user Mobile Page there is the Save button. We need to save the document and return to the welcome Mobile Page, clearing the saved dominoDocument from memory. Fortunately there is a Server-Side JavaScript Simple Action to enable this: the Move To Application Page Simple Action. This has a number of parameters that can be set. Setting saveDocument to “true” easily allows us to save the main document datasource. Setting forceFullRefresh to “true” will allow us to do a full page refresh, clearing the saved dominoDocument from memory. The targetPage parameter is the page to move to and we set the transitionType to “slide”.

We now have a home page, an editable form, and a page where the user can select the state. All of this has a look and feel that’s consistent with mobile, maximises the screen real estate, and does as much as possible client side. The full code for the XPage is below.

In part three, I’ll show similar functionality using more server-side functionality. Although not my preferred option, there may be information useful for some developers.

Mobile New User CSJS XPage

Pickers and typeahead functionality work well in a browser environment, which is heavily reliant on server-side functionality. Partial refreshes abound in XPages and one of its major strengths as a RAD tool is the ease with which AJAX functionality can be made available. Even in an environment with high latency, browser connectivity is relatively reliable. The issue is: “how can the size of traffic between server and client be minimised?” There are a number of options for this, as I discussed in my recent session at BLUG which I will be expanding on at DanNotes – using loaded instead of rendered, using execMode=”partial” with an execId, using partial instead of full page refresh, combining controls.

However, when it comes to mobile development, in many cases the issue is different. On a mobile browser I regularly come across issues where connectivity drops and I have to resubmit a request. Anyone who attended Lotusphere this year or various LUGs will have on some occasion found that wifi dropped. This is one of the reasons for developing offline mobile applications, whether using HTML5, something like Appcelerator, or a tool like Teamstudio Unplugged. But if you’re building for a mobile browser, the issue becomes “how can the frequency of traffic between server and client be minimised?”

A brief perusal of the XPages Mobile Controls provides subtle evidence of this, particularly if one uses the Discussion XL template as an example. The mobile interface is a single XPage, encapsulated by a ‘dynamic content’ control that is the Single Page Application. Each ‘page’ is a Mobile Page and navigation is done by switching between those pages.My use of terminology is deliberate here, because the intention is where possible to switch between pages on the mobile client, not retrieve a page from the server.

The Mobile Page control has a property resetContent which, by default, is set to false. This means that if the user returns to a ‘page’ they have previously visited then, by default, the content is just redisplayed. There is no partial refresh to the server. It is a client-side event to effectively hide on area of the page and display another. There is another property preload which can be used to preload a Mobile Page so that a call to the server is not required. Adding content to a Mobile Page view is generally done with a client-side “Add rows to a data iterator” (xe:addRows) control which has a setting to save the state. This can be used to reduce the need to repeat the paging.

If you compare the mainTopic and the mobile_newTopic Custom Controls in the Discussion XL template, this desire to minimise calls to the server is evidenced still further. The browser version uses an inputText control with typeahead. The mobile version uses an inputText control without typeahead.

The whole approach of mobile browser development is to do as much as possible on the mobile client rather than run the gauntlet of connectivity to the server. This is also why defaults are to minimise the amount of content passed to the browser (so, for example, the tundra stylesheet is not passed to a mobile browser by default) and why defaults do not reload content from the server. This is also why one might choose mobile-specific design rather than using a cross-over pattern of development, using the same custom control for browser and web. More importantly, this is why mobile user interfaces may often provide a subset of browser functionality or different functionality.

And all this is without addressing the smaller screen real estate on a mobile phone (tablets have a bit more, but the XPages Mobile Controls do not yet cater specifically for tablets, so I’m excluding that from this article).

So, how do we provide typeahead or picker functionality on a mobile browser?

I’ll come onto one option in my next post.

But Safari has an option to change the user agent.

The first step is to enable the Develop menu. Go to Edit – Preferences. Then on the Advanced tab, check Show Develop menu in menu bar.

This will enable the Develop menu. From here you can go to the User Agent submenu and change the user agent to e.g. iPhone, iPad, or choose Other… to set up a custom user agent.

Now you can use the browser to see the iOS stylesheets and simulate functionalityfor a specific user agent.

First, a couple of points about the differing media. The electronic version is great for bookmarking and searching. Plus, because I always have my iPad with me, I always have PCG with me. But one of the nice additions on the paper version is quick reference material on the inside covers. This allows you to quickly find where to go to in the book based on certain needs.

As for the book itself, it’s aimed specifically at those already developing XPages applications. So it’s not going to tell you how to build an application – for that, read the Mastering XPages book. It’s going to tell you how to optimise your server, your application, and your Client-Side JavaScript. It’s also aimed at all XPages developers. I’m willing to bet there are only a handful of people in the world who already know everything that’s in the book. Anyone else will definitely learn something. And I learnt lots.

There is a host of information on the xsp.properties, which is where to go to optimise your server and application. One of the properties I learnt more about here was xsp.application.forcefullrefresh to fully refresh the application after each save in Designer. Just as one would expect, the book describes exactly what it does, to help inform on when to use it.

Another example of this in action is the Java getComponentFor and SSJS getComponent and how they work. I firmly believe that if you understand what’s happening, it’s easier to use it properly – that’s one of the guiding principles behind my second session at BLUG tomorrow. The explanation of getClientId, when it will not work and why also highlights this.

The book also goes in depth on Client-Side JavaScript. With mobile controls and developers going beyond the basics for other XPages development, this is particularly timely. There are also elements useful if you are converting an existing web application to use XPages, such as The benefits of attachQuerySubmitListener to utilise existing CSJS validation. One aspect I also look forward to investigating is overriding XSP.alert, perhaps to create a nicer alert than the Web 1.0 look and feel of basic browser alert boxes.

But the book also covers intermediate / advanced topics, such as using XPath for data binding, a great description of managed beans using the discussion database, clear instructions in Java debugging, and an excellent description of the JSF lifecycle and how to read stack traces.

All in all, it is a must-have resource, not only for XPages developers but also Domino Administrators who are administering servers with XPages applications on them. Thanks to Martin, Tony, Dan and Maire for their efforts.

Tim, David and I spoke to the authors a couple of weeks ago, so look out for that episode of The XCast soon.

I’ve now updated the whitepaper to bring it up to date with 8.5.3, just in time for the imminent release of Fix Pack 1 later this month. The whitepaper draws on years of experience with XPages and an insight into the Extension Library controls delivered in Upgrade Pack 1.

Maximising The Benefits of XPages in 8.5.3

Ready, Set, Go! How IBM Lotus Domino XPages Became Mobile

Eamon Muldoon and I will be presenting a session updated from Lotusphere covering all things mobile in the XPages Extension Library. There are some great controls available for providing users with a mobile browser experience that is automatically consistent with their device’s UX.

The Eureka Moment: The JSF Knowledge You Need to Understand XPages

There’s a really scary word in there – “JSF” – that may make you think this session isn’t for you. Many might think this is for expert developers. It’s not. If you’re a beginner or intermediate at XPages, there will be great content that will demystify some of the gotchas and help you code for optimisation and performance. As long as you have created an editable XPage and done a partial refresh, you’ll learn a great deal and not get lost. I originally intended to present this session with Tim Tripcony, unfortunately it wasn’t to be, but I’d like to give him my thanks for helping out with the session.

If you’re at BLUG by all means say hello.

• Tony McGuckin has posted an XSnippet for tracking the XPages and JSF lifecycle.
• Ulrich Krause has posted a topic on the XPages Forum about dataContext recalculating when outside of the refreshId area
• Andrew Pollack posted a question on Stack Overflow because he had suffered major frustration when trying to edit a row in a repeat control, because validation on a new document was triggering.

As part of my preparation for BLUG I investigated all the partial refresh options. One that I have never used but gave me a eureka moment, was Partial Execution Mode. It is the option that answered both questions, as I’ve been able to prove, thanks to both developers posting their code. (And, by the way, this is one of the wonderful benefits of XPages, that developers can post their code.)

 So What Happens During a Partial Refresh?

Well, I can’t cover everything here. That’s a big chunk of my session at BLUG. And I’ll work from Ulrich’s code. There’s a screenshot below, but if you follow the link to his post above, you can download it.

First of all, the whole XPage is posted back to the browser. This is the default action and will occur for most of you for most of your XPages, unless specifically coded differently. That’s outside the scope of this post and won’t affect the later processing.

Secondly, the server processing occurs. I’ll come back to that.

Finally, the area in the refreshId, highlighted in the screenshot, is passed back to the browser.

RefreshId: WHICH Refresh?

We’ve mentioned refreshId here. The key thing to remember here is that the refreshId defines the area that will be refreshed back to the browser. The refreshId has absolutely no effect on the server processing, and that is very important to remember. Regardless of what is put in refreshId, the whole XPage is recalculated by the server processing, during the relevant phases of the JSF lifecycle. This is evidenced when you use a phaseListener to show what is updated during each phase (see Tony’s XSnippet for how to do that).

The value property of the dataTable is calculated during the Apply Request Values phase as well as the Render Response phase (see below).

Add a Computed Field with a value calculated in SSJS and you will see it is calculated during the same two phases. Add a rendered property calculated using SSJS to the Computed Field and you will see that the rendered property is recalculated during the Apply Request Values, Process Validation, Update Model Values and Render Response phases.

And by default, every control in the whole XPage is recalculated. The fact that this hasn’t been so widely noticed is a credit to the performance of XPages.

ExecMode and ExecId To The Rescue

On every event there is a little checkbox which a lot of developers – myself included – have always left as one of those pieces of advanced XPages functionality to look into at one point in the future. I reached that point recently.

The setting is Set partial execution mode. In the source pane this converts to execMode=”partial” set on the eventHandler. This changes what is processed in the server side processing. Instead of processing the whole XPage, it processes a specific component.

By default the component processed is not the component set in the refreshId property, but the component surrounding the eventHandler. In this case, that is the button. Herein lies the danger, because in the vast majority of cases, that won’t be what you want to process. That is the importance of setting the execId property as well. Note that the execId property is not available via the Events panel. You need to select the eventHandler and find it in the All Properties panel (the same as the onStart, onError and onComplete events use to trigger Client-Side JavaScript during the partial refresh). Personally, I find it easier to just set them in the source pane.

The Results

Once execMode is set to partial and execId is set, the full JSF lifecycle only processes those components within the ID defined for execId. This will significantly cut down the number of calls to the server. The value property of Computed Field controls will not be calculated at all during the JSF lifecycle. Currently the rendered property of the Computed Field and the value property of the Data Table will still get calculated during the Render Response phase. The screenshot below shows the value property of the Data Table. But the properties are not recalculated during any other phase.

It also means that if, like Andrew Pollack, you have a repeat control where you want to toggle edit mode and validation for one row while not triggering validation for a second datasource on the XPage, setting execMode and execId will do that for you.

The Caveat

However, bear in mind the impact of execMode and execId. Because the component tree is only updated for the components within the execId, that means other values entered by the user do not get applied during the Apply Request Values phase. That means all values entered by the user outside of the execId area revert back to what they were the last time a refresh occurred.

The Conclusion

So it has real benefits for performance, for logical processing, but the impacts must be understood. Hopefully this article has given you enough information to understand the impacts and, if not, enough information to work them out for yourself. It’s a piece of functionality I will certainly be using more often in the future.

Not surprisingly, the operating system has a big impact on the speed of Lotus Notes opening, but also hanging of the Notes Client (and presumably Domino Designer client). The whitepaper is well worth reading, particularly for support teams. Good management of the PC can avoid some of frustrations of users that are wrongly laid at the feet of Lotus Notes.

Any developer providing an application on the Lotus Notes Client may also want to leave a copy strategically on the desks of their colleagues!

Not mentioned in the whitepaper, but covered in the new XPages Portable Command Guide book, are the notes.ini variable settings to optimise Lotus Notes Client memory usage – vmarg.Xmx and vmarg.Xms. When amended relative to the PC’s system memory, this too can improve Notes Client performance.

I and other IBM Champions have joined the debate. Too read both sides of the discussion and all the comments, head across to ZDNet.

Then you’ve got to remember what settings you changed and where to find them.

Except you don’t. Because Domino Designer is on Eclipse. Out of the box, Eclipse gives you the functionality to export your preferences, as Dan O’Connor mentioned in a comment on one of my previous blog posts. But like the Package Explorer in 8.5.2, it’s a bit hidden away.

The first step is to go to a non-Domino Designer perspective. I use the Java perspective. When you then open the File menu, you’ll see some additional options for Import… and Export…. Export is the one we want.

This brings up a dialog box. Under General, you want to select Preferences.

You can then select all or selected types of preferences, and choose a file location to export them to.

Then on your new install of Lotus Notes / Domino Designer you can again switch to the Java perspective or another standard Eclipse perspective and choose File – Import…. Point to the location and you can import your preferences.

Within a few minutes, all my preferences, all widgets in the relevant categories of my Widget Catalog, all Sametime communities and groups (once I had added a default community) were installed. Some settings for some widgets were downloaded, but not all. Nonetheless, it was a significant time-saver when setting up my new laptop.

It’s a shame the functionality is hidden and presumably not available for a Notes Client only install. It could save a lot of time and ensure your users love Lotus Notes.

• Sven Hasselbach’s initial post
• My explanation of what’s happening in the source code and Java
• Sven Hasselbach’s response
• A possible alternative from Mark Roden

Both make good points and I have to say I’m glad I don’t have to make a decision on what changes, if any, should be made to Domino Designer as a result! Whether it’s a bug or a feature, I don’t have an opinion either way to be totally honest. If it’s allowed in the future, I’ll use it. At the moment, it’s something I’m happy to be aware of and work around.

And on that topic – working around it – I had another thought late last night (technically this morning!). As ever, it came from thinking about the problem from a different direction. It comes from an element of XPages probably under-used but extremelt powerful – dataContexts.

If you don’t know about dataContexts, read the part of the Mastering XPages book on them. They’re basically global variables that can be scoped to an XPage, a Custom Control or a Panel. Just the same as dominoDocument or dominoView datasources. This makes them very powerful, especially for values you plan on using multiple times on the page. Instead of the value being computed multiple times, it’s computed once and referenced via EL.

The code is pretty similar (again, I’m using a screenshot for ease because it’s SO simple:

As with any other data elements, we have a var, which is how we reference it, and a value. Again, it’s computed on page load. But for computedField2 we can then use normal EL, so it’s #{username} and we don’t have to combine ${…} and #{…}.

The output now works.

Sven encountered the issue, as did I, in an Output Script control. Basically, if your Output Script code combine ${…} code and #{…} code, for example #{id:myField1}, the #{…} code is always evaluated at page load. This means, in the case of #{id:myField1} that it returns a blank ID. This isn’t limited to Output Script controls. It’s the same for any control, even a Computed Field.

One of the nice things about XPages, once you’ve mastered the basics, is the Custom language. This allows you to combine textual and computed elements in a single Value Binding, as I blogged about last July. But even in a Computed Field, you can’t combine ${…} and #{…}. Let’s put this in context.

Look at this code. It’s fairly basic. We’re outputting a username and control IDs.

But look at the output. For the first control, we get the ID. For the second, we get the username, but not the ID.

That’s because the ID for computedField1 has been generated at runtime, but the binding for computedField2 has been generated at page load. Basically, because we have something that needs generating at page load, everything needs running at page load.

This may seem strange. But if we understand what’s happening behind the scenes, it’s understandable. Any non-literal string is stored as a String and passed to a Java function. So whereas a developer might consider “${javascript:@UserName()}” as a distinct element, the XSP Command Manager just interprets the whole value property as something that needs passing to a Java method. Let’s look at the Java code outputted, and the difference becomes apparent.

The first control has the following Java code:

The whole value property, including the #{id:…} element is stored into a String , which is passed as a parameter to evaluator.createValueBinding() – not all parameters passed to the method are shown.

But compare computedField2′s Java code.

Here, again, the whole value property including the @UserName element is passed into a String. But notice it is passed in as #{…}. The ${…} serves only to tell Designer that it needs to call evaluator.getBindingValue() instead of evaluator.createValueBinding(). Because the value property is passed as a String parameter of a method, everything must use createValueBinding() or everything must use getBindingValue(). You cannot combine both, nor do I expect that you ever will.

Someone more knowledgeable in the intricacies of JSF can probably explain this  better than me. But the key to remember is to use #{…} or ${…}, but not both.