Learning XPages - eknori.de

newjerseyshakyΛογισμικό & κατασκευή λογ/κού

30 Οκτ 2013 (πριν από 3 χρόνια και 9 μήνες)

175 εμφανίσεις

Learning XPages

by Declan Sciolla-Lynch, 2009

Learning XPages
Table of Contents
1.
Application Objectives
................................................................................
4
2.
The Basics Of OneUI
..................................................................................
6
3.
Using Themes To Apply Your CSS
..............................................................
8
4.
Breaking Up Is Easy To Do
.......................................................................
10
5.
Adding An Image To The Right Banner
....................................................
13
6.
Showing The Username In The Banner
...................................................
15
7.
The Banner Login Logout Button
..............................................................
17
8.
Adding The Application Title
.....................................................................
19
9.
Using Values From A Profile Document
....................................................
21
10.
Finalizing The Footer
................................................................................
23
11.
Adding Some Forms And Data
.................................................................
25
12.
Preparing Our First Sidebar Widget
.........................................................
26
13.
Listing The Locations In The Sidebar
.......................................................
28
14.
Applying OneUI To the Locations List
.......................................................
32
15.
Building The Homepage Content
..............................................................
33
16.
A Better Homepage Look
..........................................................................
36
17.
Styling The Homepage Table
....................................................................
39
18.
Building The Second XPage
.....................................................................
42
19.
Another Repeat Another Table
..................................................................
44
20.
Restricting The Repeat To A Single Category
...........................................
46
21.
Linking The Sidebar To The Location XPage
...........................................
49
22.
Creating The User Document
...................................................................
52
23.
Adding Data Fields To The Person Details XPage
...................................
54
24.
Linking To The Person Details XPage
......................................................
56
25.
Scripted Links Between XPages
...............................................................
59
26.
Dropping Some Breadcrumbs
..................................................................
61
27.
Naming The Breadcrumbs
........................................................................
65
28.
Creating A Tabbed Panel
..........................................................................
68
29.
Giving The Tables Some Feedback
..........................................................
71
30.
Creating An Action Bar and Action Buttons
...............................................
73
31.
Adding Actions To the Action Buttons
.......................................................
75
32.
Using Roles To Make Fields Editable
.......................................................
76
33.
Simple Data Validation
..............................................................................
78
34.
Server Side Validation
..............................................................................
81
35.
Advanced Validation using RegEx
............................................................
84
36.
Saving The Document And Hiding The Actions
........................................
86
37.
Adding a RichText Control To The Page
...................................................
88
38.
Uploading An Image For The Person's Picture
.........................................
90
39.
Adding Pagers To Our Repeats
................................................................
93
40.
Two Data Sources One XPage
.................................................................
97
41.
Simple Debugging Of Your XPages Code
..............................................
100
42.
Creating A New Person Document
.........................................................
102
43.
Enabling All Fields On A New Document
................................................
104
44.
Adding A Dropdown Combobox Lookup To A Field
.................................
107
45.
Deleting A Document
..............................................................................
109
46.
Setting Up To Add, Edit And Delete Locations
........................................
111
47.
Using A View Control To List Locations
...................................................
114
48.
Linking Checkboxs To An Action
.............................................................
117
49.
Building The LocationEdit XPage
...........................................................
121
50.
Creating A Search Function
....................................................................
124
51.
Giving Function To The Search Bar
........................................................
126
52.
Getting And Displaying The Search Results
...........................................
128
53.
Building The Search Results XPage
.......................................................
130
54.
The End
..................................................................................................
133
1.
Application Objectives
Welcome to the first in a series of blog entries on learning XPages to develop a simple
application. In each part of this series of blog entries we will build, from scratch, a
XPages based phonebook application with the resulting application being released on
OpenNTF once it is complete. As I'm still learning XPages myself this should be a
fascinating exploration into the capabilities of XPages and should help both myself and
you, my readers, to get over the learning curve that is involved in learning XPages in
Lotus Domino 8.5.
Building a phonebook application is probably one of the easiest applications you can
create and phonebook applications can be found in many companies as part of their
intranet in one form or another. For the purpose of this blog series I'll be keeping the
application simple at first and then as the application progresses we can adding some
advanced features. Lets have a look at some of the objectives that I've set for the
application.
Xpages OneUI.
The base layout and look and feel is going to use the OneUI CSS that IBM has
developed. This is the same look and feel that is used in the OpenNTF XPages Wiki
application by Steve Castledine and is also similar to the look and feel that the
Discussion template in 8.5 uses. I have been told that the discussion template may even
be moving to the OneUI CSS in the 8.5.1 release but that remains to be seen. By using
this OneUI we can quickly set a predefined look for the application and not have to
worry about too much additional CSS.
Locations and People.
There will be two main data sources, the first being a 'location' document that stores the
main contact information for an office, the office address, main fax number etc. and the
second will be a 'person' document that will contain all the information about an
individual person. The person document will also contain a field which specifies which
location the person belongs to.
Editable profiles.
When a user is logged in they should have the ability to edit their own person document
so that they can update their details. This could be linked to a configuration setting so
that the application owner can disable this ability.
Notes client interface.
The notes client interface will be developed using the Java Views to provide a similar
look and feel to the Xpages Wiki template. This will probably be the last thing that will be
done to the application as the main interface will be the XPages part.
Domino Addressbook Sync Agent.
Finally we'll look at creating an agent that will keep the phonebook up-to-date with the
names found in the Domino Directory. Again this will be done in the final stages as we'll
mainly be concentrating on the XPages parts.
So there you have it, a rough plan for the objectives of the XPages phonebook
application. In the next part of this series we'll look at creating the initial OneUI layout in
XPages and then after that we'll adding the data sources to the Xpages and linking
them all together.
2.
The Basics Of OneUI
Welcome to part 2 in a series of blog entries on how to create a simple phonebook
application in Lotus Domino 8.5 using XPages. In this part we are going to look at the
basics of OneUI and understand how to use it to provide the standard layout for your
application.
By using a combination of DIVs and CSS it is very easy to create a layout for your web
based application. Your CSS file will contain styles that match up with the divs in the
html page and this is what creates the layout. When we examine the OneUI core.css file
we find a section for structure that looks like this :
/*** S T R U C T U R E ***/
#lotusFrame, .lotusFrame
{margin:0 auto;
padding:0;
min-width:990px;}
#lotusTitleBar,#lotusPlaceBar,.lotusTitleBar,.lotusPlaceBar
{margin:0 20px}
#lotusMain, #lotusFooter, .lotusMain, .lotusFooter
{border-style:solid;
clear:both;
margin:0 20px 10px 20px;
overflow:hidden}
#lotusMain, .lotusMain
{padding:0 0 5px 0;
min-height:400px;
border-width:0 1px 1px 1px;
-moz-border-radius:0 0 4px 4px;
-webkit-border-bottom-left-radius:4px;
-webkit-border-bottom-right-radius:4px;
background-repeat:no-repeat}
#lotusColLeft, .lotusColLeft
{width:180px;
padding:20px 10px 10px 10px;}
#lotusColRight, .lotusColRight
{width:180px;
padding:15px 10px;
font-size:.9em}
#lotusColRight h2, .lotusColRight h2{}
#lotusColLeft .lotusFirst,
#lotusColRight .lotusFirst, .lotusColLeft .lotusFirst, .lotusColRight .lotusFirst{margin-top:0;}
#lotusContent, .lotusContent
{padding:16px 20px 20px 20px;
overflow:hidden;margin-right:auto;margin-left:auto;}
.lotusContentColOne{width:45%;}
.lotusContentColTwo{width:45%;}
This defines parts of the basic layout however it does not include the OneUI color
scheme or graphics. These are stored in a separate css file called defaulttheme.css. If
you match these two css files up with some simple html that looks like this :

<div id="lotusFrame">

<div id="lotusBanner">Banner Contents Here</div>

<div id="lotusTitleBar">Titlebar Here</div>

<div id="lotusPlaceBar">PlaceBar Here</div>

<div id="lotusMain">

<div id="lotusColLeft">Left Sidebar Here</div>

<div id="lotusContent">Main Content Here</div>

</div>

<div id="lotusfooter">Footer Contents Here</div>

</div>
You'll end up with an instant webpage with a nice look and feel that looks like this :
( footer and banner contents not shown )
The core.css and defaulttheme.css and a couple of other css files are all stored on the
domino server in the datadirectory\domino\java\xps\theme\oneui directory. We could
reference the files directly in the XPage application but as you will see in part 3 of this
series we are going to use a theme document to include the files instead.
3.
Using Themes To Apply Your CSS

In the last part we talked about the oneUI css files that are supplied by IBM and how we
are going to use them to apply a standard look and feel to our application. In this part
we will look at how to put them into the XPages application by using a theme document.
Themes are a very powerful aspect of XPages. They allow you to define which CSS files
you want to be sent down to the users web browser when they access your application.
If you are designing applications for a corporate environment you may already have a
look and feel that all your applications should use and with some careful planning you
could turn those css files into a theme that you can apply for all your future XPage
applications. The CSS files that the theme references can be stored either in the actual
database or on the domino file server in the same way the oneUI css files are stored.
The oneUI css files are stored in the datadirectory\domino\java\xps\theme\oneui
directory on the server and if you look at this directory you will find quite a few files in
addition to the core.css and defaulttheme.css that I mentioned in part 2 of this series. In
that directory you will also file files like iehacks.css, xps.css, xpsIE06.css, xpsIE78.css
and xpsFF.css. As you may notice some of these css files are specific to the web
browser hitting the XPage application and it is through the use of the theme document
that we can make sure that the Firefox specific css is not sent to the internet explorer
browser and vice versa.
Lets have a look at a few lines from a theme document to see what I mean...

<!-- Internet Explorer 7 & 8 Specific -->

<resource rendered="#{javascript:context.getUserAgent().isIE(7,8)}">

<content-type>text/css</content-type>

<href>/.ibmxspres/global/theme/oneui/xspIE78.css</href>

</resource>


<!-- FireFox Specific -->

<resource rendered="#{javascript:context.getUserAgent().isFirefox()}">

<content-type>text/css</content-type>

<href>/.ibmxspres/global/theme/oneui/xspFF.css</href>

</resource>
By using the rendered="#{javascript:context.getUserAgent().isFirefox()}" line for the
resource we can check to see if the user is using Firefox and if it evaluates as true then
that specific css file is sent to the users web browser. By using javascript to return the
true of false result to the rendered line you can do all sorts of tricks here, Imagine being
able to return a different set of css files between certain dates to give your applications a
seasonal look and feel or use a different look and feel based on if the site URL ends
in .net or .com. Infact the oneUI theme document is setup in such a way that it will use a
different set of css files depending on if the browser is setup for Left To Right reading or
Right To left reading.
Once you have created your theme document don't forget to tell your application to start
using it by looking at the application properties.
To get you started here is your first download. There are THREE design elements in this
database, The first is a theme document that references the oneUI css files on your
domino server, the second is an internal css file called cutom.css, it is currently empty
but it is referenced by the theme document as an example of how to include a mixure of
both external and internal css files. We will eventually end up using this css file in future
parts when we need to add application specific css to the phonebook. The theme
document in this database originated in the OpenNTF xPages Wiki application.
The last design element included in the download is a single xpage called home.xps.
This xpage just contains the simple html that I showed in part 2 of the series so that you
can view how the oneUI theme document works. In the next part of the series will will
replace this simple html with proper XPages and Custom Controls to show you how to
build the basic parts of the XPage application.
4.
Breaking Up Is Easy To Do
When developing an XPages application you can, if you want, put everything into a
single XPage but this can lead to inconsistencies in the look and feel of your application
if it contains multiple XPages, for example in our Phonebook application we will have an
XPage for the homepage, an XPage for the list of people at a single location and an
XPage for the persons details. All of these XPages will have the same basic layout but if
I put that layout directly in each XPage it means you have to change three different
XPages if you want to change part of the layout that is common for each page.
So lets break up our XPage into Custom Controls that we can then include them in
future XPages in the application. We'll use the oneUI structure as the basis for the
custom controls that we need. Let's look at that original simple HTML again to see the
DIV names :

<div id="lotusFrame">

<div class="lotusBanner">Banner Contents Here</div>

<div id="lotusTitleBar">Titlebar Here</div>

<div id="lotusPlaceBar">PlaceBar Here</div>

<div id="lotusMain">

<div id="lotusColLeft">Left Sidebar Here</div>

<div id="lotusContent">Main Content Here</div>

</div>

<div id="lotusfooter">Footer Contents Here</div>

</div>
Each of the DIVs that contain content make a logical breakup of the html into Custom
Controls. You may be tempted to also create custom controls for lotusFrame and
lotusMain but there really is no need, they are just containers and will probably never
change.
To get started open up the Custom Controls view in Domino designer and click the 'New
Custom Control' button. You will be prompted for a name for the custom control. You can
give it whatever name you like but I have found that I am leaning towards a standard
naming convention for the different types of custom controls that I create so I'm going to
call mine layout_Banner. You can name your custom control however you like but you
should also try stick to a standard naming convention so if you come back to the
application after a while you can easily work out how everything fits together.
Once you have you blank custom control open, switch to the source view and put in the
single div for lotusBanner and then save and close it. Here is how it's going to look in
the source view once your done :
UPDATE: The above screenshot should say class='lotusBanner' and not
id='lotusBanner' the OneUI css does not have a DIV style for lotusBanner, just a class
style. the reast of the div's are fine and should read id= for their names.
Do the same for the other parts of the oneUI structure with one exception, for the
lotusContent DIV give it's custom control a slightly different name, I'll be calling mine
content_HomePage. The reason for this is that I'll eventually have different custom
controls to include in this spot for the other XPages I'll be making in my application.
Here are the Custom Controls I currently have in my demo database :
If we open up the original XPage we can now replace the DIVs in there with links to the
Custom Controls. Just drag the custom controls in from the controls pane on the right
hand side and then switch to the source view and move them to the correct places in the
source for the XPage, remembering to delete the unneeded DIVs. Here is the new
source for my XPage
If we preview this in our web browser we end up with the exact same result as before
but now it has been broken down into little chunks that will be easier to work with. In the
next few parts of the series we will be looking at each of the custom controls and adding
some real content to them.
5.
Adding An Image To The Right Banner
If you have been following along so far you will know that we now have a basic layout for
our application but no real content yet. In these next few parts of the series we are going
to take a look at each of the sections of the layout and start putting some real content
and code into them. The first part of the layout that we are going to deal with is the
banner that appears at the very top of the page.
If you look at any of the other oneUI applications from IBM you'll see that they use the
banner in a fairly consistent way, They have a logo on the left side of the banner for the
application and on the right side they have a login/logout link and maybe the name of
the person currently logged in. We are going to duplicate this look and feel for our
application and show how we can use some server side JavaScript to decide if the link
we need to show is the login link or the logout link. lets start with the image on the left
side of the banner.
Lets get started by opening the layout_banner custom control that we created in the last
part of the series. We are going to remove the placeholder text and then drag in a new
control from the controls panel on the right side of your screen. The control we are going
to drag in is the 'Panel' container control. A panel is a special type of control that allows
you to put other controls inside of it. Go ahead and drag in a panel and then have a look
at it's properties. Leave the name of the panel blank and go down to the 'All Properties'
tab. Because we are following the OneUI we need to give this panel a special
StyleClass of 'lotusRightCorner'. When the page is rendered to the users web browser it
will appear as <div class="lotusRightCorner"> referencing that class in the OneUI CSS
files. Lets pull in another panel control and give it a StyleClass of 'lotusInner' while we
are here.
UPDATE
: The second panel is nested inside the first panel as noted in the comments.
Before we can add an image to our banner we will need an image file. I have created a
new 'Image Resource' in the design of my database called OpenNTF.jpg. This is the
image that I'll be using for the final version of the application when it's published on
OpenNTF. if you are writing your own applications for a corporate environment then you
may want to create your own standard image. To fit in properly it should have a height of
24 pixels and should have a transparent background so that it blends in well with your
application. Once you have your image resource in the database we need to drag in a
new control from the right hand side, it is a stand control called 'Image', drag it into the
last panel you created and have a look at it's properties.
We have given the image control the name of 'lotusLogo' and then selected the Image
Resource by clicking on the folder icon in the options section of the properties. We have
also provided some alternative text that will display when the user hovers over the image
in their web browser. The last thing we need to do is look at the 'All Properties' section
and give it a styleClass of 'lotusLogo'. save you custom control and preview it in your
web browser
While this seems like a lot of work just to add an image to the banner we have laid the
groundwork for the other side of the banner by adding in the two panels. In the next part
we are going to add in an unordered list of items styled with the OneUI styles to make
horizontal option menu that looks like this :
6.
Showing The Username In The Banner
In the last part we set the groundwork for the banner section of our application and
added a small graphic to the left side of the banner. In this part we are going to build the
links on the right side of the banner and show how we can use some server side
javascript to determin if we should show a login link or a logout link.
Examining the sample XPage applications that use the OneUI interface we see that the
right side of the banner is made up of an unordered list with a special style class. In the
XPages designer there is no easy control to drag over to the XPage to create the list so
you need to rely on your basic HTML skills to get you started. First open the
layout_Banner custom control that you have created from earlier and put it into the
source view. You should see the control that we created for the image in the last part, it
will look something like this <xp:image url="/OpenNTF.jpg" id="lotusLogo"
alt="OpenNTF" styleClass="lotusLogo"></xp:image>. We will add in our basic
unordered list below this, add in a new line and paste the following html directly into the
source view :

<ul class="lotusInlinelist">

<li class="lotusFirst">

First List Item

</li>

<li>

Second List Item

</li>

</ul>
The ul class name of 'lotusInlinelist' is defined in the oneUI css as a horizontal list. List
items in this class of list have been defined to have a left side border of 1 pixel however
that would look a little out of place on the first item in the list so the class name of
'lotusFirst' overrides this css behavior and ensures that the first item does not display
the left side border. If you switch back to the design view of the XPage you can see you
list or you could save the XPage and preview it in your browser to see how it's going to
look.
Now that we have the basic list in place we can replace our placeholder text with some
XPages controls and write some code to make them display what we need. lets start
with the first list item. For the moment we would like this to be a simple computed text
field that displays either 'anonymous' or the users common name depending on if they
are logged in or not. Remove the first bit of placeholder text and then drag over the
'Computed Field' control from your controls list on the right side of your screen. Once it's
in the correct place on the list we can have a look at it's properties. Don't worry about
the controls name and make sure the 'visible' option is enabled and then go to the
'Value' tab of the properties. You will see a reminder hint that you need to bind the value
to something, you can ignore this, we are going to use some server side JavaScript to
work out the value.
Select the JavaScript option and then click on the 'Edit Script' button to bring up the
JavaScript editor. here is the JavaScript that we are going to use :

var userName:NotesName = session.createName(@UserName());

return(userName.getCommon());
If you have done any LotusScript code in the past then you can very quickly see that we
are creating a new object called userName based on the NotesName class and setting it
to the notes name of the user who is currently logged in on the session. In LotusScript
we would look at NotesSession.Username() but here we have an @UserName() which
is based on formula language. Yes, your existing LotusScript and Formula language
skills are certainly not going to waste, you'll just learn a new way to put them to use.
Lets save the XPage and refresh the preview in the browser and see what we have.
In the next part we'll do the second list item. It's pretty much the same as the first list
item but there is a little more JavaScript to deal with.
7.
The Banner Login Logout Button
In the last part of the series we saw how we could just some simple server side
javascript with code that looked very much like a mix of LotusScript and formula
language to show the name of the currently logged in person above our application in
the banner. In this part we will finish off the banner by providing the user and way to
login or logout of the application.
Lets start by opening our layout_Banner custom control again. You should see the list
that we created in the last part, remove the second bit of placeholder text and drag in a
new control form the controls pane on the right side of the screen. the control we are
going to use this time is a 'Link' control. Drag it in and position it where the second bit of
placeholder text in the list used to be.
Once you have it in place ( which you can confirm by using the source view of the
custom control to make sure it appears inside the <li> & </li> tags like in the above
image have a look at it's properties. There are quite a few different properties that we
can set but we are only interesting in two of them, The label to make it say 'Login' or
'Logout' and the URL that the end user will be directed to when they click the link.
Almost every property in an XPage control can be computed. Just look for the little
diamond at the end of each property. If the diamond is a solid blue color then you know
that the property is using a computed value.
We are going to compute the value for the link so click the diamond and select the
'compute value' option. You'll see the JavaScript entry dialog box appear on your screen
and we are going to use the following code :

var userName:NotesName = session.createName(@UserName());

if (userName.getCommon()=="Anonymous")

{

var rtnvalue = "Log In"

}

else

{

var rtnvalue = "Logout"

}

return(rtnvalue);
Here we set the userName variable in the exact same way as we did for the other part
of the banner but we then use a standard IF THEN ELSE style statement to return either
login or logout as a string. For the URL we can do pretty much the exact same, click the
diamond to set it to a computed value and use the following code :

var userName:NotesName = session.createName(@UserName());

if (userName.getCommon()=="Anonymous")

{

facesContext.getExternalContext().getRequestContextPath() + "?login"

}

else

{

facesContext.getExternalContext().getRequestContextPath() + "?logout"

}
This time instead of returning a simple string we are going to construct the returned
value. The .getRequestContextPath on the externalContext is a way to figure out what
URL the user typed in to get to your application. The '?login' and '?logout' that is
appended to the end are just standard Lotus Domino URL constructs to log a person in
or out of a database. You can use these constructs today on non-XPage applications
also. By using the external context path we don;t need to hardcode anything into the
application so you can move the database to any server, path or filename.
Lets save the the XPage and preview it in our web browser to see how it looks :

or
We have now completed the first layout section of our XPage application. Included
below is a copy of my development database that contains all the design changes that
we have made so far in the series. We have covered quite a few topics so far including
how to break your application up into custom controls to make it easier to include
different parts of the layout in pages, we have looked at how to use an image control
and a how to mix html with xpages to produce an unordered list and within that list we
used a computed field control and a link control in combination with some server side
javascript to control what we wanted displayed.
In the next part of the series we'll start working on the next part of the layout. the 'Title
Bar'.
8.
Adding The Application Title
In the last couple of parts of the series we finished off the banner that appears above
the application, in this part we are going to look at the applications title bar. This section
of the application is used to display the name of the application. Now you may be
tempted to hard code in the application name because in reality it will never change in
this application but one of our objectives is to create reusable code so we are going to
programmatically populate the application name.
Before we get started we need to get rid of our placeholder text and drag in two panels
just like we did for the banner in part 3, the first panel will have a styleclass of
'lotusRightCorner' and the second panel will be nested inside the first panel and have a
styleclass of 'lotusInner'. If you save and preview your XPage now you'll see a slight
change in the titlebar.
The title bar now has a nice swoop style graphical background. You can thank the
OneUI theme for this, by adding the panels with their styleclasses you have applied CSS
to the html that was created and this CSS tells the browser that the pane with the
styleclass of 'lotusInner' that is inside a div called 'lotusTitleBar' should have a graphical
background, here's the bit of css from the defaulttheme.css

#lotusTitleBar .lotusInner, .lotusTitleBar .lotusInner {

background-image:url(./images/titlebarLeft.png);

}
Now that we have the panels all setup correctly lets look at two ways to get the
application name in there...
Lets look at the easy method first. We know that all Lotus Notes/Domino databases
have a database title and we can get to this title using formula language by using
@DbTitle or by using LotusScript's NotesDatabase.GetTitle() so we can very quickly
display this in the title bar. Just drag in a computed field control into the panel control
and then look at it's properties.
Change it's name to 'mainTitle' and then go to the 'value' properties tab. Ignore the
simple binding request and click on the JavaScript radio button and enter
'database.getTitle()' and then save and preview the XPage. While it is now showing you
the database title it still doesn't look great so we need to follow the OneUI styles and
add a <h2> and </h2> around the computed text control. Your final XPage source
should look like this :
and when you save and preview the XPage you should see the following :
In the next part I'll show you how to pull a value out of a profile document and use that
to populate the titlebar instead.
9.
Using Values From A Profile Document
When developing web based applications for Domino in the past I have always avoided
using hardcoded url's, titles, lables, well basically everything would be an option of some
sort stored in a notes document that the owner of the application could edit. In this part
of my Learning XPages series I'm going to replace the application title that I'm showing
in the titlebar with a value pulled from a profile document. You might ask why bother
when It is already softcoded using the database title and it's a good question, my
answer, what if the application owner is not the admin and they don;t have access to
change the database title.
Before we get started on the XPages code for this section I needed to do a little bit o
traditional notes client development. I have added my first form to the database design
which I have given an alias of 'prof_AppConfig' and I have added a single field to that
form called 'cfg_ApplicationTitle'. I then created a small formula language agent to run
from the actions menu with a single line of code that reads @Command
([EditProfileDocument];"prof_AppConfig");. Then I went into the application in my notes
client, ran the agent and added an application title into the profile document and saved
it. We're now ready to get XPages to read in the profile document and use that value for
the application title.
Open the layout_TitleBar again and select the computed field that we created earlier
that uses the database title for it's value. We are going to be editing it's value so go to
the value properties and double click on the blue 'computed value' text to bring up the
javascript editor dialog box. Here's the code we are going to use :
var profDoc:NotesDocument = database.getProfileDocument("prof_AppConfig","");

return profDoc.getItemValue("cfg_ApplicationName"){0};
NOTE: Replace the curly brackets with square brackets. Due to the way blogsphere
works if won;t display the square brackets correctly.
This is very similar to LotusScript's method of getting a value from a profile document. In
the first line we are setting up a new variable called profDoc that is based on the
NotesDocument class and we set it to the profile document by calling the
database.getprofiledocument method. In the second line we are returning the field we
need by using the getItemValue method of the notesdocument. Notice the square
brackets with the zero in it? This is the same as getting the first value of the array by
using (0) in LotusScript.
When I first implemented this in my application I ran into a CSS issue when the title of
my application was more then 200 pixels wide and it resulted in my page looking like this
:
As you can see the restricted width of the H2 tag when it appears in the lotusTitleBar div
has caused the extra long title to wrap into the next line and it pushed the place bar
over. To get around this I need to override the oneUI CSS with my own custom CSS.
Open the blank custom.css file that we created when we created the theme and add the
following lines :

#lotusTitleBar h2, .lotusTitleBar h2 {

width:auto;

}
If you save and close the css and refresh your XPage in the browser then it still won't
because we need to make one more change.
When I initially created the Theme document and pointed it to all the external CSS files
and the internal custom.css file I listed the custom.css file before all the external OneUI
css files. This means that the OneUI css is overriding the custom.css file. You need to
edit your theme file and move the resource section for custom.css down below where it
loads it's last external css file. Save the theme document and refresh the browser and
everything will look perfect.
I'll attach an updated development database to the next part of the series where I'll jump
down to the page footer and get it completed before starting on displaying some real live
data in the sidebar and main contents.
10.
Finalizing The Footer
Before we move onto to real content for the phonebook application I am going to jump
down to the footer section and finish that off quickly. The footer, according to the OneUI
guidelines, is a place for links to online support and contact information however my
personal preference that that it should be kept as simple as possible. Because this
application will eventually be released on OpenNTF I'm going to just put in a small piece
of text that reads 'An OpenNTF project by Declan Lynch'. and I'll link the word OpenNTF
to their website.
Lets start by opening the layout_Footer custom control that we built earlier and drag in a
few panels, as usual the first panel will have a styleclass of 'lotusRightCorner' and the
second panel will be nested inside the first panel and will have a styleclass of
'lotusInner'. Then we can just type our text directly into the inner panel, Save and
Preview.
Looks ok so far but I'd much prefer it on the right side of the footer so lets add a
styleclass to the text. The styleclass I'm going to use is called 'lotusRight' and it is setup
in the CSS to float anything with this style over to the right of the screen. Select the text
in your XPage and look at the all properties view and just add the styleclass. If you look
at the XPage source now you'll see that the text has been moved into a <span> tag and
the selected class is showing.
If you save and preview your XPage now you'll see the text jump over to the far side of
the screen.
The last thing to do is convert the word OpenNTF into a link. We start by dragging in link
control from the controls pane to where we want the link to appear and then delete the
original OpenNTF text. If we click on the link to get to the properties we can fill in the
label as OpenNTF and the URL as http://www.openntf.org. It's a simple link so we don't
need to compute anything. if we save and close right now things will look a little weird in
the browser, the 'link' will be back over on the left side of the screen because we didn't
give it a styleclass of lotusRight
The reason for this is beacuse the SPAN has been broken into two seperate parts, one
before the link and one after the link and also because the link does not have any
styleclass. A quick way to fix this would be to go into the XPage source view and remove
the extra span tags that XPages designer has added in for you that I have highlighted
below. You'll also need to add in some spacing around the link's title.
Once that's done you can save and preview your XPage and you'll see our nice new
footer :
In the next part we will start working on some domino forms so we can enter in some
details to display in the xpage.
11.
Adding Some Forms And Data
Back in part one of this series I mentioned in the objectives that we would have two
traditional forms in the application, a Location form and a Person form. I'm not going to
get into any specifics on designing the forms as I'm going to assume that you have done
traditional Notes Client development in the past and that you know how to create a form
and a view. The download at the end of this blog entry will have the current version of
the development database with the forms and a few documents in it however there are a
few things I'd like to point out about the forms and views I'm about to create.
If you are developing an XPages application you still need forms and views but they can
be simple with no need for styling or layout unless they are also going to be accessed
from a notes client. In a pure XPages only application your form could just be a big long
list of fields, although for your own sake you may want to create a table to put them into
with a description of what field is so when you come back to an application in a year
you'll know what your looking at.
The Location Document will contain the address and main phone and fax numbers for
that location. It is as simple as that.
The person document will contain the persons name, their work details like their direct
dial number, direct fax ( if they have one ) their internet email address, their managers
name and so on, exactly like the 'work' section of the person document in the NAB. It
will also contain their home address and details just like the nab also. My reason for
doing this is due to another of my application objectives, the Domino agent to sync the
contents with the names in the NAB. By chosing to use the same field names not it
should make it easier as I get to that portion of the application.
I have also created a couple of views, one for the locations and one for the people and I
have added in simple buttons to allow the notes client user to create new documents in
both those categories and I have created a lookup view to populate the locations
dropdown list in the person document.
Download the database and add some data while I start work on the next part of the
series.
12.
Preparing Our First Sidebar Widget
Now that we have the main look and feel of our XPages Phonebook application done it
is time to start showing some actual data on the XPage. From my own experience I
have found that it is easier to get the data displaying on the XPage before linking it to
other XPages so right now we are going work on adding our first component to the
sidebar on the left of the screen.
We will start by going to the custom controls view in the Domino Designer and creating
a NEW custom control. While we could write our code directly into the
layout_LeftSidebar control the choice to use a new Custom Control means that we have
more control over when it appears in the sidebar and by breaking the application down
into smaller parts you can easily reuse parts in other applications. I have called my new
custom control sb_LocationsList, This naming convention tells me that it is something
that goes in a sidebar.
Once you have created the new custom control just add some placeholder text save it
and then open up the layout_LeftSideBar custom control so we can embed our new
custom control inside of it. To put the custom control into the sidebar you just drag it
from the custom controls pane on the right side of your screen to where you want it in
the sidebar. You will need to pop into the source view to make sure it is between the
div's that we created earlier. Here's what my final layout_LeftSidebar looks like :
Now when we save and preview our site we'll see the placeholder text from inside the
sb_LocationsList appearing instead of the original placeholder text from the
layout_LeftSideBar.
In the next part we will replace the placeholder text with a real list of locations
13.
Listing The Locations In The Sidebar
So our new custom control is ready and is embedded in the layout, now comes the fun
part, making it display some real data from the backend domino database. This list of
locations is like the main menu in our application so I'm going to style it using OneUI
and then show you how to use a repeat control to display the list of locations.
Lets start by opening our sb_LocationsList custom control again. Get rid of the
placeholder text and drag over THREE, yes 3, nested panels, you'll need to give each of
these panels a styleclass in the following order : lotusMenu, lotusBottomCorner, and
lotusInner. Your current XPages code should look something like this :
and if you save and refresh your page you should now see the basic menu layout
appearing in your sidebar.
Lets add some content using one of the most powerful features of XPages. The Repeat
Control. The repeat control, as it's name implies, allows you to repeat whatever is inside
the repeat control any number of times. You can have a single control inside the repeat
control, you can have multiple controls inside a repeat control, you can have custom
controls inside and repeat control and you can even have repeat controls inside repeat
controls. Once you start working with repeat controls you will NEVER go back to
traditional Domino web application design, in just minutes to you build part of your web
application when it would have taken days worth of view design, LotusScript and
debugging the old way.
We are going to be repeating information from one of the views that I created in the
database so we need to tell the XPage where to find the data. To do this we first need to
define a data source. If you look at the outline for the XPage on the left side of your
screen you will see one of the outline entries called 'Custom Control', if we were dealing
with an actual XPage then this would say 'XPage'. They are both the same. Select it and
you'll see the properties for the XPage/Control.
We are going to add a new data source based on a domino view. Select the ADD button
and select Domino View to get started. A new section will appear to the right of the
datasources properties box where you can select the view that you want to use.
I have select the Locations lookup view that I created and I have called my data source
DominoView.
Now drag in a repeat control from the control pane on the right of the screen into the
panels that we created earlier and then drag a computed field control into the repeat
control. We'll just use the computed field control to explain how to use the repeat, in the
next part we'll replace it with something a bit nicer that fits in with the menu style.
Go back to the repeat control so you can see it's properties, it may already have the
binding source listed, we then need to add in some extra options so we can get to the
data source.
The collection name is the variable that we can use to get to the documents and the
index name is a count of the current entry. We are just going to be using rowData for
this example of the repeat control.
Now click on the computed field and look at it's value properties. we are going to bind
the data using JavaScript so click the JavaScript radio button and then click on the
button to bring up the editor. Here's the JavaScript we are going to use :

rowData.getColumnValue("Location")
rowData is the collection name we defined in the repeat control's properties and
getColumnValue is exactly like the lotusScript method that you can use on a
NotesViewEntry.
Save and refresh the page and you should see something similar to this depending on
what data you have in your database.
As you can see it does not look great yet so in the next part we will tidy it up and make if
look more useful even though it does not link to anything yet.
14.
Applying OneUI To the Locations List
In the last part of the series me managed to get the data from a view to appear in our
sidebar menu by using a repeat. It didn't look great so we now need to style it with the
OneUI css to make it look nice for the end user.
After reviewing the OneUI CSS I found that there were a couple of different ways that I
could do this. I could create my menu as an unordered list by adding in the <ul> and
<li> tags in the correct places in the XPages source like this
Notice how the <UL> tags are outside the repeat and the <li> tags are inside the repeat.
This is a great example of how you can use a repeat with multiple components or
controls inside of it. While the unordered list format might be ideal I decided to go with a
different OneUI look that I found in the defaulttheme.css file. and that is the <h3> tag.
This produces a nice large menu option that the user can select. So in the code above,
remove those <ul> tags and change the <li> tags to <h3> and save and refresh.
We are going to leave the sidebar menu for the moment and come back to it in a later
part once we have created something for it to link to. In the next part we are going to
add some data to the main contents area.
15.
Building The Homepage Content
Time to display some real content on the homepage of our application. For the
homepage I'd like to list all the locations along with their main phone number and main
fax numbers. Lets start by opening the content_HomePage custom control that we
created when we were building the layout for the site.
Again we are going to be using a repeat control so the first thing we need to do is define
the data source for the repeat control. Using the Outline View on the lft of your screen
select the 'Custom Control' node in the outline tree and then switch to the Data
Properties section on the properties tab. This time I'm going to use the Content
\Locations view in my database.
I have given the data source a name of dominoLocationsView. I could have used
dominoView again just like in the sidebar list of locations and it would have been fine,
the XPages server runtime has no problem with different components having data
sources with the same names, it keeps a handle on what source belongs to what
component however my own preference is to always give things more descriptive
names so that you can quickly work out what they were for when you come back to an
applications design after a long period of time.
Now that we have the datasource defined we can display it on the XPage. I'm about to
introduce you to a new control, the 'View' control but then I am going to remove it and
show you my preferred way by using a repeat control. Lets start by dragging a View
control into the XPage. Make sure it appears between the divs with the 'lotusContent'
class so that it will appear correctly on your XPage. When you drag in the control you'll
see a dialog box prompting you for some basic information for the view's data source.
We have already defined our data source so we can just select it from the dropdown at
the top of the box, you can, however, create other datasources directly from this dialog if
you want. We are just going to select these defaults for our data source and then click
OK at which point you'll see an automatically generated table appear in your xPage.
and if you save and refresh your XPage you'll see some real data appearing in your
application.
Of course because we have not put any styles on the view control yet it looks terrible but
it does demonstrate how quickly we could get data from a view in our notes application
to appear on screen in an XPage.
In the next part I'm going to delete this view control and build it manually using a repeat
control and my own CSS stylings.
16.
A Better Homepage Look
In the last part we added a view control to our content_HomePage custom control and
set it up to display the contents of a view from our application. For simple views this
works great and we probably could have used it in this application also but I like the
level of control that the 'repeat control' gives you so I'm going to replace our view control
with a repeat.
Start by deleting the view control from our XPage. Make sure it's fully gone by look and
at the source, you should just see your data source and the div's or panel with the
'lotusContent' class. Drag in your repeat control and then drag a table control into the
repeat control. When you drag in a table control you will get a helper dialog box asking
how big you want the table.
I have select 2 rows and 3 columns and left everything else at the default. Setup the
repeat controls properties just like we did for the side bar making sure to select the data
source we defined earlier and also making sure to put in the collection name and index
name
Design your table just like you would any other table, Put some headers in and then
drag over some computed field controls to hold the values of the repeat. You table
should look something similar to this
I've setup the values for the computed fields exactly the same way as I did for the
computed field I'm using in the sidebar. I have set the value to JavaScript and set the
script to rowData.getColumnValue("ViewColName") where ViewColName is the name of
each column in the view that I want to display.
If we now refresh the XPage we should see something like this :
It should quickly become obvious as to what's wrong here. Well the entire table is inside
the repeat so for each location document in the database it's building an entire table. To
fix this problem we need to go into the XPage source and move the <xp:repeat> tags to
the inside of the table tags and below the first row of the table because that is the
header. I have also changes the <xp:tr> tags in the header row to <th> tags as this is
the proper setup for a header row in a html table.
The one IMPORTANT thing that is left to do is remove the repeat's name. if you don;t do
this then a DIV will appear inside your table in the web browser and this is not valid
HTML and it will cause havoc with your CSS. The easiest way to remove the name is in
the source view, just delete the entire 'id="repeat1"' bit out of the repeat controls tag.
Save and refresh and your table should look perfect :
In the next part we will create some custom CSS and apply it to our table.
17.
Styling The Homepage Table
In the past section we built our data table on the homepage of our XPages application
using a repeat control. In this section I'll show you how to apply some custom CSS to
the table and how to use a server side JavaScript to alternate the style used for the rows
of the table.
First of all we need to add some CSS to our custom.css file. Open it up in the resources
-> CSS files section of your database design and add in the following CSS

#phonebook,.phonebook {

border:1px solid #CCCCCC;

width:100%;}

#phonebook th, .phonebook th {

background-color:#EEEEEE;

padding:5px;

font-weight:bold;}

#phonebook tr, .phonebook tr {

background-color:#FFFFFF;

padding:5px;}

#phonebook tr.altRow, .phonebook tr.altRow {

background-color:#EEEEEE;}

#phonebook tr.over, .phonebook tr.over {

background-color:orange;

color:#FFFFFF;

cursor:pointer;}

#phonebook td, .phonebook td {

padding:0 2px;

text-align:left;}
Save you new custom.css file and then open up the contents_HomePage custom
control again. We need to tell the table to use the 'phonebook' style. Select the table in
the XPages designer and go down to the all properties section. In the StyleClass just
add in the word 'phonebook' and then save and refresh your XPage in your web
browser. The XPage source for the table should look like this
and the resulting web page will look like this
Wouldn't it be nice if we alternated the background color of the rows in the table? This is
very handy when you start dealing with a larger number of rows in the table as it makes
it easier for the user to read across an individual row.
With a simple bit of server side JavaScript we can very easily achieve this, and because
each row of your table is just a single row inside a repeat in the XPage you only need to
write the code once.
Open the contents_HomePage custom control again and switch to the source view. Find
and click on the <xp:tr> tag that appears inside your repeat control. This will switch the
properties box below the XPage to the properties of the table row. Find the All properties
and scroll down to the styleClass. I mentioned before that nearly everything in XPages
can be computed and this is what we will do now. Instead of typing in a styleClass we
click the blue diamond symbol highlighted below and then we select the 'compute value'
option.
This brings up the script entry dialog box. Here's the script we are going to use :

if (rowIndex % 2 == 0 )

return ""

else

return "altRow";
In this JavaScript we are looking at rowIndex which we setup in the repeat control as the
name of the variable that would store the index. The rowIndex%2 returns the value of
the rowIndex's modulus ( or division remainder ) when the value is divided in two. In
simple terms all the even rows will return a zero and all the odd rows won't. Save this
script, save your xpage and refresh your web page to see this : ( Don't forget the index
starts at zero )
So a single line of serverSide JavaScript, inside your repeat control has allowed to you
make a very nice looking table.
In the next few parts of the series we will build a brand new XPage that will list all the
staff members at a single location and then we'll show you how to link your homepage to
the single location page, both from the sidebar and from the table on the homepage.
Our application is starting to come together now so here is an updated download for you
to work with.
18.
Building The Second XPage
At this stage in our application development we have created a fairly nice looking
homepage for our phonebook. When you load up the phonebook in your web browser
you see the OneUI layout, a menu on the left of the screen listing all the locations and in
the main part of the screen a table listing all the locations with their main phone number
and main fax numbers. While it looks nice it doesn't do anything yet, there is nothing to
click on to get more details and over the next few sections in the Learning XPages blog
series we will create a new XPage and link it from the homepage.
The next XPage that we are going to create will be designed to list all of the people at a
single location. The layout will be based on the OneUI just like the homepage, the only
different will be the contents of the main part of the page. We will start the process by
going to our Custom Controls view in the Domino Designer and creating a new custom
control I have called mine content_Location so that I know what it is going to contain.
In our new blank custom control we will drag in a panel control and then looking at it's
properties we add a style class of 'lotusContent'. I have also added some placeholder
text into the panel, I like to do this so when I preview pages I can make sure that the
content will appear in the correct place. Here's what the source view of my control looks
like right now :
Save the custom control and then go to the XPages view in your Domino Designer. Now
we could create a brand new blank XPage and then recreate all the divs and drag in
custom control for the layout just like we did for the original XPage but why reinvent the
wheel. An easier option is to select the 'Home' XPage and duplicate it by doing a copy
paste. This will result in a new XPage called 'Copy_of_home' so we need to rename it.
In traditional Domino Development you can rename design elements by opening then
and looking at the properties of the element or you can edit the name in-place within the
design view however with XPages you cannot do it this way, you must select the
'Rename' option from the File menu. the keyboard shortcut for this option is F2, so
highlight your new XPage and press F2 to bring up the rename dialog box
Type in your new name and then open the XPage in edit mode. I have given mine the
simple name of 'Location'. Once you have opened the XPage you can remove the
custom control for content_HomePage and drag in the custom control for
content_Location. When your finished your XPage source should look like this
Now you can save your new XPage and preview it in your web browser. You should see
the OneUI layout that we created earlier and your new placeholder text appearing in the
main content area.
In the next part we'll add another repeat control to the contents_Location custom
control.
19.
Another Repeat Another Table
So now that we have our second XPage created lets add some content to it. We'll start
by opening the new custom control that we created called content_Location and clear
out the placeholder text. Once that's done we need to define the data source for the
control. Select the 'Custom Control' node in the outline view on the left of your screen
and go to the 'Data' properties tab. Create a new data source based on the vw_People
view that is in the sample database
Now, just like the home page we will drag in a repeat control and into the repeat control
we will create a table of two rows and six columns by dragging in a table control. Give
the first row of your table some headers and then select the repeat control to look at it's
properties.
Set the Collection Name and Index Name just like before and then, just like the
repeated table on the homepage we need to drag in some computed field controls and
set their values by using JavaScript similar to rowData.getColumnValue("colname");
where colname is the name of the column in the view that we are using as our data
source. Next you move the repeat control inside the table and change the table header
row to <th> tags. I have also given my table a styleClass of 'phonebook' so that it uses
the same CSS as I created for the homepage's table.
You can now save your custom control and preview the 'Location' XPage and you will
see a nice table listing all the people in the database. Feel free to apply the alternating
row styles to the table just like we did for the homepage to give your application a
consistent look and feel.
In the screenshot above you'll notic that the alternating row styles don't seem to have
worked however if you examine the original view that the database is based on you'll
see that it has a categorized column at the start of the view and the two red lines I have
drawn above are rows in the table where those empty categories are showing. In the
next part I'll show you how to pass a variable on the URl to restrict the repeat to a single
category.
20.
Restricting The Repeat To A Single Category
At the moment our location XPage shows us all the entries in our categorized view. In
this part we are going to restrict which category is displayed in the repeat control by
passing a variable in on the URL in the format of http://demosite/xphone.nsf/
location.xsp?location=Dublin.
To retrieve the variable passed in one the URL I am going to use a serverSide
JavaScript library that was created by Thomas Gumz with some modifications by Matt
White. The original script library is available in the XPages Discussion template which
should be on your Domino 8.5 server and the modifications can be found in the
TaskJam application which you can downloaded by going to taskjam.net.. Many thanks
to Matt for giving permission to use the modified version of the script library. The script
library will be included in the next download of the development database.
To add the script library to our application we open the content_Location custom control
and then in the outline view on the left of your screen select the custom control node
and look at the 'Resources' properties tab. Click the button to add a Script Library and
then select the library from the dialog box that appears.
Remain in the properties for the custom control and go to the 'All properties' tab and find
the 'BeforePageLoad' property. In here we are going to write some server side javascript
code that uses the script library. Here's the code :

var cgi = new CGIVariables();

var param = cgi.getURLParam("Location");

if (param) {

if (param != "" )

sessionScope.locationfilter = param;

}
What this code does is before the page has loaded it looks at the URL and finds the
location= part and if it exists it puts whatever the value is into a sessionscope variable
called 'locationfilter'. Session Scope is a special scope where you can add variables that
only last for the duration of the users session. As soon as they close their web browser
the session scope variables are lost. There is also an Application Scope and a Page
Scope that you can use to store these values. Heres how the code will look in the
source view of your xpage, you can see the resource for the server side script library
and the beforePageLoad script. As you get more advanced in XPages you may find
yourself writing code directly in the source view.
So now we have the location taken from the URL and stored in a sessionScope variable
we need to tell the data source to only return the values in that category. To do this we
need to look at the 'All Properties' tab for the custom control and look at the 'Data'
section and expand it out to find the data source that we created for the custom control.
In here we'll find a property called 'categoryFilter'.
In here we can reference the sessionScope variable by clicking on the blue diamond
and selecting compute value and then entering 'sessionscope.locationfilter' into the
script dialog box. Our XPage source will now have an extra line up in the data source
definition :
Save the custom control and then in your web browser add a ?Location=Pittsburgh ( or
whatever location you might have in your sample data ) and load the page.
Here is my ?location=Chicago result
and my ?location=Pittsburgh result
You will notice how the alternating row styles are now appearing correctly.
Now that we have a page to display, in the next part we'll link the sidebar to this page
and then I'll update the downloadable database for you all to work with.
21.
Linking The Sidebar To The Location XPage
By now we have a 'Home' XPage and a 'Location' XPage but they are not yet linked to
each other. In this part we will change our sidebar list of locations into links so that our
users can click on a location in the sidebar and be brought to the correct page with the
location being passed on the URL.
Lets start by opening the SB_LocationsList custom Control that we created earlier. At
the moment we have a repeat control that repeats the items in our Locations lookup
view in the domino database. It currently looks like this :
I decided I wanted to make the list look slightly different and I found a few extra
components in the OneUI CCS files that I could use. Lets start by adding a title to the
menu. Drag a new panel into your XPage so that it is inside the 'lotusInner' panel. You
will need to make sure it appears in the right place so have a look at your XPage
source.
Here you can see it appearing just below my original 'lotusInner' panel. I have given it a
styleClass of 'lotusMenuSection' and inside of that I have placed my menu title
surrounded by <h3> tags. You can save the custom control right now and refresh your
page to test it. You should see your title with a green line below it seperating it from the
rest of the menu, check the screenshots below to see what I mean.
Now lets drag in another panel below that one and give it a styleClass of
'lotusMenuSubsection'
And then in your XPages source select the repeat tags and everything between them
and move it all into that panel. At the moment your repeated control is just a computed
field surrounded by H3 tags. I'm going to make some real links now so drag a Link
control from the controls panel into the XPage and place it beside the computed field
control, you can now delete the computed control field as we don;t need it any more.. If
you look at the properties for the link you can see a 'label' property. We'll set that as a
computed value by clicking the blue diamond and using the code
rowData.getColumnValue("Location") in the javascript dialog box. Then on the right side
of the properties we are going to select the 'Open Page' option and choose the
'Locations' page from the dropdown box.
So now it knows to open the locations XPage but how do we get the ?location= bit onto
the URL. Lets go to the 'All Properties' of the link control. If you scroll down to the data
section you'll see the reference to location.xsp, this is where the 'Open Page' value we
selected in the step above is stored in the All properties. Above that you'll see
'Parameters' select that row and two small buttons will appear, the first button adds a
parameter so click on it and a new parameter will appear. Give the parameter a name of
'location' and for value we need to compute it so click the blue diamond and enter in the
exact same code that we are using for the links label into the script dialog box.
If we save and refresh our home.xps XPage in a web browser our links are now working
and clicking on any of the labels will bring us to the Locations XPage with the parameter
being passed on the URL.
I wasn't too happy with the <h3> tags styling once I had converted the original computed
fields into links so I went into the XPages source and changed them to <li> tags and I
wrapped the repeat control in a <ul> tag.
Our links list now looks like this and is much nicer.
Here is the latest download of the sample database. I have added a new agent that you
can run from the Notes Client side called 'Build Sample Data' that you can run from the
actions menu that will create 10 location documents and 1000 random person
documents. the agent Does not fill in all the details for the person docs yet but it's a
great start for getting some random data in there. ( if anybody wants to update that
agent to provide random addresses and phone numbers then feel free )
Download File xPhonep21.zip
22.
Creating The User Document
So far our XPages Phonebook application is really starting to come together, we have
designed out layout, shown you how to display information from a view in the Domino
backend on the XPage using a repeat and also shown how to restrict the view to a
single category. Over the next few parts we will explore the display of a notes document
in the XPage and also explore a different way of linking one XPage to another without
having to pass parameters on the URL like we did to link the sidebar to the single
location XPage.
Lets start by creating a brand new XPage and Custom Control. Just like we did for the
single location XPage and content_Location custom control we are going to do a little
component reusing by copy/pasting some existing design documents and renaming
them. Start off by copy/pasting the content_Location custom control and then use the F2
key to rename it to content_Person. Once it's renamed go into the source view and
remove everything except the 'lotusContent' panel, I have added some additional place
holder text so mine now looks like this :
Save and close it and then go to the XPages view in the design and copy/paste one of
the existing XPages and press F2 to rename it to 'Person'. Now go into the source of the
XPage and look for the 'lotusMain' DIV and change the reference to the existing custom
control to your new custom control. Below I originally copied my 'Location' XPage and
then changed the reference to the content_Location custom control.
If we save and close the 'Person' XPage at this stage and preview it you should now see
the OneUI layout that we have created and the place holder text appearing in the main
part of the page.
Now that we have our new XPage and custom control setup in the next part we'll
associate it with a notes document
23.
Adding Data Fields To The Person Details XPage
Now that we have our new XPage and custom control created lets add some content to
it. Open up your content_person custom control again and lets get started.
Because we are associating this XPage with a document we will need to tell the XPage
which form we are using so that it can determine what fields are available. To do this we
setup a new data source for the XPage, Go to the root node in the outline view and in
the properties section select the 'Data' properties tab. Click on the ADD button but
instead of selecting a 'Domino View' like we did in earlier parts of tutorial we will select a
'Domino Document' and then select the 'Person' form from the current database.
Now that we have told the XPage where to find the fields that it has access to we can
see then in the 'Data' pane in Domino Designer. To access then have a look at the
'Controls' pane, you should see a drop down arrow, select it and you can choose the
data pane.
You should now see your data source and all the fields that are available.
Lets put them on to our XPage, we'll worry about formatting them a little later but for
now I'd like to just get them onto the Xpage so that I can show you how to link to the
page. In the data view select ALL the fields and then just drag them all on to the XPage.
The Domino Designer will automatically create a table with labels and input fields.
Lets save our custom control but we can't preview the Xpage just yet because we have
not told it which document to open. We'll cover that in the next part.
24.
Linking To The Person Details XPage
We now have a simple XPage to display a persons information so in this section we will
link to the XPage and pass in a document UNID so that it knows which document to
open.
Lets open up the content_location custom control. You should see the table that we
create in a previous part with the repeat control inside the table so that each row of the
table is repeated. When linking one page to another there are a couple of different ways
that we can do it. For the phonebook I'd like the user to be able to click anywhere on the
row of the table to bring them into the person document. I could convert one of the
computed fields on the table into a link but that would require the user to know they
have to click only on the link, by allowing them to click anywhere on the table it will be
easier for the user.
What I'm going to do is add an 'onClick' event to the table row. Switch to your source
view and find and click on the <xp:tr> tag that appears inside the repeat control.
In the properties box below you will need to go to the 'All Properties' tab and give the
row an ID.
you should see your XPage source update to reference the new ID
The reason we have to do this is so that the onClick event has something to latch onto.
Without the ID the table row cannot be referenced by our event. With the <XP:TR> still
selected lets have a look at a new section of the Domino Designer that we have not
touched on yet. The 'Events' section. You'll find it as a tab next to the 'Properties'
section.
The events section will show you all the possible events that you can associate with a
XPage control. We are interested in the onClick event for this particular task so select
that event and have a look at the right side of the tab.
You will see that we have the ability to write JavaScript code for the client side or the
server side and on the server side we can also select some of the simple actions that
IBM have provided for us. Lets try a simple action. Click on the 'Add Action' button.
A dialog box will appear and will actually default for the task that we have in mind. We
want to open a different XPage so we select the name of the XPage and we wnat to
open the document for reading so set the target document as 'Open Document', there
are also options for for 'Edit Document' and 'Create Document'. All we have to do now it
tell it what the document ID is. We will compute this value so select the diamond and
choose 'Compute Value' and in the script dialog box we will use the following code.
If you remember we are inside a repeat control and rowData is the variable that we can
use to refer to the current entry in the repeat collection that we are working with.
rowData.getUniversalID(); returns the UNID for the current document and if we save our
XPage and then preview it in the web browser you will now be able to click on a name in
the table and it will load in the 'Person' XPage and show you their details.
The URL bar in your web browser will show you your simple action and the DocumentID
that your working with.
In the next part I'll rewrite the onClick action to put this information into the
sessionScope and then use the values from there in the person xPage instead.
25.
Scripted Links Between XPages
In the last part I showed you how you can create a simple action on the onClick event to
link the single location list to the person XPage. In this part I'm going to write a
serverside script instead of using the simple actions however before you decide this is
the right way to do your linking there is one important caveat that you need to know
before doing it this way....
Here's what the URL looks like right now for a document
You can see in the URL that the action and the document ID are part of the URL. If you
bookmark this URL and then look at the bookmark at a later date then the link will work
perfectly. With the method I'm about to show you I'm going to be using the
sessionScope to store some values, these values disappear once the user closes their
web browser and the URL will only say Person.xsp so a bookmark won't work so if you
care about bookmarks then you need to make sure the values are part of the URL.
Lets open the content_Location custom control again and find our <xp:tr> tag that's
inside the repeat control. We are going to look at the events tab again and select the
'onClick' event but this time we will use the 'Script Editor' instead of simple actions.
Because we already had a simple action in there it will ask if we are sure because
changing from one to the other will wipe out any code or actions you have created. Go
ahead and click OK and you'll see the script entry box. Here's teh script I'm using :

sessionScope.personDocID = rowData.getUniversalID();

context.redirectToPage("Person.xsp");
The first line sets the sessionScope variable called 'personDocID' to the UNID of the
document that has been selected. The second line instructs the browser to open the
'Person' XPage. If we save and preview our XPage right now it will fail because we have
not told the person XPage how to use the session scope variable. so just save and
close the content_Location custom control for now and open up the content_Person
custom control.
When we first defined the data source for the content_person custom control we did not
specify a document ID. Go back to the data properties for the control and select the blue
diamond beside the 'Document ID' part of the data source and select the 'compute
value' option. The script entry dialog box will appear and in here we add the reference to
our session Scope variable like this :
Now we can save our content_Person custom control and refresh our Xpage in the
browser. Select a person from the location list and it should open up the person XPage
for that person and while the document opens up to the correct person the URL bar will
not contain any extra parameters
Congratulations. You now have the the basic phonebook application completed. You can
view the list of locations, click a location to get a list of the people in that location and
then click on a person in the table to get to the details about that person however we still
have a few more things to do to make our application easier like make the person
details screen look nicer, write some client side javascript to change the background
color of the rows in the list of people so the user know which one they are hovering over
and we also need to do something with our PlaceBar which has remained untouched till
now.
All this and more will be covered in the remainder of the series.
26.
Dropping Some Breadcrumbs
So far in our application I have not done anything with the 'PlaceBar'. It still has the
original placeholder text that we gave it back when we were designing the initial layout
for the application.
I have decided that I'd like to display some breadcrumbs in this section. For those that
don't know breadcrumbs refers to a method of navigation used by website that as you
progress deeper into the structure of the application you are laying a trail of links that
you can follow backwards to return to where you came from. Breadcrumbs normally
take on the structure of 'Homepage > Section > Subsection' and this matches up with
our application in the form of 'Locations > Location > Person'. As you can see we use
the > symbol to separate each section.
Lets start off the process of creating the breadcrumbs using some placeholder text that
we'll replace in the next part of the series with some real content. The reason I'm going
to do this is so I can show you how we can pass information into the PlaceBar custom
control so that we can turn on and off different aspects of the breadcrumb trail. lets start
by opening the layout_PlaceBar custom control and in the source view remove the
placeholder text. Switch back to the design view and drag in a panel and into that panel
drag in a combinations of labels and links
I then switched to the source view again to make sure that the panel was between the
'lotusPlaceBar' div and i changed some of the values for the lables and links. You'll
notice that the 'Home' and 'Location' sections of the breadcrumbs have both a label and
a link. The reason for this is when we're at the homepage of the application you don't
need a link back to the homepage so we'll just display the label but when we are at a
location we need to display a link to the homepage.
Now that we have the labels and links setup Lets look at a way to only show certain
ones at certain time. The method I'm going to use is just one of many that you could
employ, I've decided to do it this way so that I can show you another feature that use
can use when your developing XPage Application.
If you look at the main properties for the layout_PlaceBar cusotm control there is a
section called Property Definition.
A property is a value that you can pass into the custom control when you include it in an
XPage. I'm going to create two properties, showLocCrumb and showPerCrumb. They
are going to be a type of string and that's all I'm going to change in the properties.
Save and close the layout_PlaceBar and go to your XPages view in the domino
designer and open the 'Home' XPage. You'll see the placebar custom control on the
page and if you select it and look at the all properties tab for the control you'll see our
two new custom properties.
Lets just type 'No' into both of these and then switch to the source view so you can see
how it is represented there.
Save and close the XPage and then do the exact same for the 'Location' Xpage and the
'Person' XPage with the location XPages properties set to Yes, No and the Person's
XPage properties set to Yes, Yes. Once you have done that we are ready to use the
properties in the layout_PlaceBar custom control so open that back up.
Let's start from the end of the breadcrumb bar and select the label for 'person'. In it's
properties there is a tickbox for 'Visible', By default is is ticked on but there is also a
diamond on the end of the property which means that we can compute if the control is
going to be visible or not.
Think about your hide-when formulas in traditional domino development and then
reverse your thinking, this is a 'Show When' computation and in this case we want to
show the lable when the showPerCrumb property is set to 'Yes' so select the diamond
and click the compute value option to bring up the script entry box.
compositeData gives me access to the properties that I passed into the custom control
and the simple == 'Yes' is a shorthand way to return a true or false value. You can apply
this same 'Show When' code the the label preceding the 'person' label.
For all the other components you will need to write the appropriate evaluations to return
either a true or false value. In javaScript you do an AND buy using two & symbols and
you do an OR by using two | symbols. here is the final XPage source that I ended up
with after writing all my 'Show When' code.

<xp:label value="Home" id="label1">

<xp:this.rendered><!DATA[#{javascript:compositeData.showLocCrumb == "No" &&
compositeData.showPerCrumb == "No"}></xp:this.rendered>

</xp:label>

<xp:link escape="true" text="Home" id="link1">

<xp:this.rendered><!DATA[#{javascript:compositeData.showLocCrumb == "Yes" ||
compositeData.showPerCrumb == "Yes"}></xp:this.rendered>

</xp:link>

<xp:label value=" > " id="label2">

<xp:this.rendered><!DATA[#{javascript:compositeData.showLocCrumb == "Yes"}></
xp:this.rendered>

</xp:label>

<xp:label value="Location" id="label4">

<xp:this.rendered><!DATA[#{javascript:compositeData.showLocCrumb == "Yes" &&
compositeData.showPerCrumb == "No"}></xp:this.rendered>

</xp:label>

<xp:link escape="true" text="Location" id="link2">

<xp:this.rendered><!DATA[#{javascript:compositeData.showPerCrumb == "Yes"}></
xp:this.rendered>

</xp:link>

<xp:label value=" > " id="label3">

<xp:this.rendered><!DATA[#{javascript:compositeData.showPerCrumb == "Yes"}></
xp:this.rendered>

</xp:label>

<xp:label value="Person" id="label5">

<xp:this.rendered><!DATA[#{javascript:compositeData.showPerCrumb == "Yes"}></