Section VI - Understanding Domino design elements, specific to building an XPages application 

Table of Contents | Previous Page | Next Page

Introduction to this section

This section is intended to help you better understand the Domino design elements which are especially relevant within an XPage application.It also provides some recommendations for dealing with existing Domino code.

The design elements highlighted here include:

• The XPage View Control
• The XPage Repeat Control
• Themes
• Recommendations and Considerations for Re-use of existing Domino Code
• Methods for Active Content Filtering
• Methods for adding Java to the template and build path

XPage View control

The XPage View Control is the main XPage building block for displaying tabular data that is quick and easy to use. The rows, columns, titles and pager are all added for you, allowing you to quickly customize it after it's created.
You can embed multiple views in the same XPage, even from different nsf's. The View control automatically shows category “twisties” for categorized columns as before. Finally, note that it is not a property – it is read from view design


The XPages View Control is a Container Control, and is Wizard driven, allowing you to get the view created quickly.



The image below illustrates the Wizard used for creating and defining the new View Control.

Pager

The pager is the navigation control used to move between pages of tabular data. It is automatically added as part of the view control



The pager has further configuration options that let you select which individual controls to show. These are set within the properties.

Filtering within the view

Views can easily be filtered via the All Properties of the view control panel.



Filtering the basic categorized view was done with the the setting “&restricttocategory=” in a standard Domino View or embedded view via “show single category”.



Now this is done through the property categoryFilter.



This can be a hard coded text value, computed value (e.g.from a custom control setting), or taken from a URL. To take a value from a URL use context.getUrlParameter("RestrictToCategory"). This would pull from the URL "/xpage.xsp?&RestrictToCategory=Customer self-assist" and restrict the view to the category "Customer Self-assist"

Filtering is done by using keys similar to the LotusScript view.getAllDocumentsByKey. This enables you to filter by more than one column by using the property “keys”. This can be a hard coded text value, computed value, or taken from a URL

The example below illustrates how the filter takes a java.util.Vector as a parameter:

Searching within the view

Filtering a view by using a search parameter is similar to standard filtering, but uses the parameter “search”. It works then like a normal view control (navigation via pager etc).

Searching Techniques

The following section describes one technique to request and process search.
There are two parts to this:

• First Step - supply Edit Box to take search parameter. To do this,

1) Add the control Edit Box


2) In Data properties, link to “Scoped Variable” - “View Scope” and give data a name (this then places the data in memory to be picked up by search action Link)

• Second step - supply the submit button to send the search parameter. To do this:

1) Add Link control
2) Using either a computed Link or onClick Event to compute the next page or url and retrieve the search value using “viewScope.searchValue”.


3) From the wiki template – custom control “prtTitleBar” - is an onClick event to open an Xpage. The value is computed as shown below

Please refer to the additional View Control Resources on the Lotus Wiki
Working with View Controls How To Create a View Control Working with View Controls - Display HTML Working with View Controls - Computed Column

XPage Repeat control

XPage control for “repeating” data is an essential developer tool. It enables you to create “views” of data like a view control, however with more degrees of flexibility (e.g. multiple rows of data per document). This can also be used for those small lists – computed sidebar links, lists of “anything” (e.g - in the wiki – categories, tags, popular pages).

So use this approach to go from the very simple to the very complex.

Here is a simple example case shown below:



And, here is a more complex example case. Building upon the complex example, you can allow multiple lists on the same XPage – from multiple sources.

Adding a Repeat Control to your XPage

The XPage Repeat Control is a “Container Control” that the developer manually configures using properties in Domino Designer



To begin working with the Repeat Control, first you assign the data source via properties and give a “Collection Name” as shown in the example below.



The image below shows how to create a link to the data source.

Adding Row Data

You can add anything to your repeat (text, field data, images etc). Just drag them into the repeat box (tip - use “source” for fine tuning)
You have direct access to the data source and can create your own html



You access the data source using collectionName.getColumnValue("field") for each individual field/value.



You can even nest repeat controls to give you even more power. For example, you could create a fancy list of data within each row, possibly from a multi value field of tags. The example below shows nested repeat controls.

Pager

The pager is the navigation control used to move between pages of tabular data. Unlike the view control you need to add it/them manually using the “core control” “pager”.



When you add your pager you need to first attach it to the repeat control it should work with. This allows you to have multiple lists of working data on one XPage. The operation of the pager is then automatic with no further coding required.



The pager has further configuration options that let you select which individual controls to show. These are set within the properties.

Filtering or Searching using a Repeat Control

Filtering or searching using a Repeat control is done identically to View Controls. (See the section above, Filtering within the view )

To detecting the Number of Rows, use SSJS getComponent("repeatID")". The count is then referenced .getRowCount()

Themes

Themes are for determining which style sheets to use for your application and/or the styling for individual components.

• They are found under Resources > Themes (an XML file).
• You can set themes globally for the server (dominodata/properties/xsp.properties) or by nsf via application properties > XPages.
• They can inherit from other themes such as the in built WebStandard or OneUI ().
• The settings higher up the tree (themes you have extended from, styling set within the control) can be overridden by using
• Stylesheet and styling information is fully computable: rendered="#{javascript:context.isDirectionRTL()}"

There are many advantages to using themes, although you can still just use a stylesheet on its own. Some of these advantages to using themes include:

• This allows you to build applications which are easily customized by a third party
• You can compute the styling by requested device/language type/browser type, so you can tailor your site to the user's browsing device.
• Core and developer component styling can be globally controlled (no need to set style information or class) eg buttons across all nsf's can be the same style – and one place edits this

Examples of ways to use themes

Here are some relevant examples for themes:

• Importing Resources (custom.css from nsf)

• Styling Core Controls that have no Theme id's

• Styling controls with Theme ids

You provide an element/control with a theme id, then refer to that id in your theme document which then assigns the styling. The benefit of doing this is having more global control and making it easy for others to provide customization's.

Here is an example of the code:


The illustration below shows the naming of the ThemeID within the AllProperties panel.

Extended use of themes

Themes can control more than styling, there are other properties can be set/overridden. For example a page title can be set within a theme file


Style Classes can be set depending on scoped variables

Reuse of current Domino code

Building new applications is more fun, but we can also quickly provide old applications with a new lease of life with XPages
Things to consider:

• Bookmarks to existing web pages. The XPage url is different for pages and views
• Lotusscript is not currently supported in XPages directly - you may want to use existing Lotuscript logic to process data
• You can mix/match standard Domino and XPage design elements, however you cannot do things like re-use subforms in XPages – so you will need to recreate as a custom control

URLs

Forms can be marked to launch the document instead using a selected XPage. Accordingly, if a user has a bookmark to an existing view/document url internally, the XPages code will redirect to the XPage url. The setting is in Form Properties, second tab “Display Xpage instead”, as shown in the image below. This is used in the Domino Wiki Template Form “Content” so the wiki template is backwards compatible with a standard Domino version.

Reusing Existing LotusScript Logic

You may currently have a lot of logic sitting in Lotusscript agents or libraries, and you want to use these when using XPages.While in the long term, using the XPages way of doing things is probably better, and there will hopefully continue to be improvements in this area soon, there is a way of leveraging say LotusScript based webQuerySave agents or script libraries.

You can do this by using the agent.RunOnServer(docid) command (as when the agent executes, we do not have the usual documentcontext handle) to run your agent after an XPage document save. The difference to note, is when you perform any actions on the document (via your code), it has already been saved, so you are not able to do anything before save. (Tthese are the actions you will need to write in XPages javascript).

You can see this working in the wiki template custom control “prtContent”. The postSaveDocument code calls the agent “XPSavePage”.



To do this you would create an agent as normal, and instead of collecting the document reference via session.documentContext, instead use agent.ParameterDocID via Set doc = db.GetDocumentByID(agent.ParameterDocID):



Then in your XPage, navigate to "Events > Data > Your Document as specified already as a data source > postSaveDocument" add an action "Basic > Execute Script". You can then use the code var agent=database.getAgent("youragent"); to get a handle to the agent and then agent.runOnServer(document1.getNoteID()); to pass the document reference to your agent (which we collected using agent.ParameterDocID).

Use Web Site Rule Substitution

If you have a particular agent or view that takes url parameters and you want to preserve the url, but rewrite using an XPage, a Site Substitution rule could help you. Just add a new Web Site Rule to the server address book under Web / Internet Sites.

For example: to change from: notesini.nsf/use?openview&cat=* to notesini.nsf/xpViewCategories.xsp?lookupName=*, but keep the ability to pass a parameter over.

Active Content Filtering ACF

Uses a pure Java open source engine that is bundled with XPages/Domino. It can automatically Filters nasty html or JavaScript embedded within rich text or fields. You can switch it on through the All Properties and “htmlFilter” or “htmlFilterIn”. The setting “acf” will do a full filter while “striptags” will strip html tags only.

Client Side JavaScript

You can on the Client Side reference server side code
tmp="#{serverScope.variable}" or tmp="#{javascript:@DbName()}"

Client Side object location:
var o=document.getElementById("#{id:Name}");

Getting id of element:
"#{id:elementName}"

Server Side JavaScript SSJS

Full XSP and Domino object model
Can embed @Formula language within your code
Server Side object location:
o=getComponent("Name");

Adding Java to template and build path

Goto java perspective and navigate to WebContent/WEB-INF.



Now Right Mouse click on WEB-INF - New Folder (name folder say src). Then go to Project > Properties > Java Build Path > Source > Add Folder. Select the WebContent>WEB-INF>src folder - and Click ok. Create new package Inside Local > your new folder

Using Pure Java within SSJS

You can build java classes within the java perspective of Eclipse/Designer and import them into your SSJS for use

ImportPackage (package) will do the import