92209002 Xpages Lab 05 Custom Controls

Domino's XPages Workshop

Lab Manual

Lab 5

Custom Controls for the Profile Application

COPYRIGHT IBM CORPORATION 2010. ALL RIGHTS RESERVED. LAB 5 IBM ISV & DEVELOPER RELATIONS.

Page 1 of 17

Introduction:This lab will teach you how to complete the tab navigation and how to communicate state information. You will learn how to use the Java perspective to add a Page Icon to your page. You will prepare additional form and view elements to complete the Profile XPages application. You will also learn how to use the repeat control. It will allow you you have free form repeating elements.

Description:This lab introduces the concepts of navigation flow. Make sure, that the right tab is displayed based on the XPage loaded. Make sure, that the complete list of profiles is shown when the results page is opened directly rather than through a query. You will familiarize yourself with Eclipse's perspectives and you will add an icon file to give your application a unique identifier in the browser address bar and bookmarks. Every profile will be able to list connected profiles. To be able to do this we need a form that stores this connection information and a view that lists these connections. In the next exercise you will put these elements to use in your profiles application. On the profile custom control you will add a form that allows to add a profile as a friend as well as the list of current friends with the option to remove them.

Objective:At the end of the lab, you should be able to:

• Know how to link XPages to each other through button or tab navigation

• Know how to add an program icon to your XPages applications

• Understand advanced form and view elements

• Understand the function and usage of the repeat control

Procedure:

SECTION 1: ADD NAVIGATION FOR THE PROFILES XPAGES

In this section, you will learn how to complete navigation for the Profile XPages application. You'll make sure that the right tab is displayed based on the XPage loads. You'll also make sure that the complete list of profiles is shown when the results page is opened directly rather than through a query.

Step 1 Open the container custom control.

Step 2 Select the resultsTab tab, then right-click on it in the design editor.


Page 2 of 17

Step 3 Select the Select Active Tab Contents context menu option.

Step 4 In the Events view for the Results tab, add a simple action for Execute Script with this formula (this clears an eventually entered search term):

sessionScope.nameToSearch = null


Page 3 of 17

Step 5 Add another simple action that will Open Page specifying the Results.xsp page and no data validation.

Step 6 Repeat steps 2, 3, & 5 (but not 4) for the other two tabs. Specify their respective pages to open.

Step 7 Click on the custom control (the outline view is a good place to do that) and then select the Property Definition category under the Properties tab.

Step 8 Click New Property to add a new property to the custom control, and name it selectedTabId with a type String. Note that you don't need to provide validation or visibility rules here.


Page 4 of 17

Step 9 Select the Tabbed Panel in the design editor (or from Outline view) and edit the Tab opened by default option as a computed value option use this formula:

compositeData.selectedTabId

Step 10 Open all the 3 XPages (home, profile, & results) and select the container control within the page (or once again from Outline view). Click on All Properties.

Step 11 For each page enter the corresponding tab name into the custom > selectedTabId property field.

Step 12 Save all of your changes to the custom control and XPages.


Page 5 of 17

Step 13 Preview your results in both the Browser and Notes Client. Test to make sure that you can successfully navigate to the correct XPages via the tabs.

Things to Explore: 1) One question typically asked: Can't I just have one page and use partial page refresh to switch the tabs? The answer: yes of course. But then you loose direct adressability of a page.

2) Rewire the application, so it only uses a single xPage. Define a mechanism that still would allow to open a specific results page.


Page 6 of 17

SECTION 2: ADD A PROGRAM ICON TO THE PROFILES XPAGES APPLICATION

In this section, you will learn how to use the Java perspective to add a Page Icon to your page. You will familiarize yourself with Eclipse's perspectives and you will add an icon file to give your application a unique identifier in the browser address bar and bookmarks.

Step 1 Open your sample application in Domino Designer, if not already still open.

Step 2 Select Window > Open Perspective > Other to switch to the Java perspective.

Step 3 Select Java. (Note: in your IDE you most likely will see a different set of perspectives).


Page 7 of 17

Step 4 The Package Explorer view on the left shows the Notes database as a series of folders:

Step 5 Navigate to the WebContent folder of your xScrapbook.nsf database and import (General > File System) the favicon.ico file, which resides in the C:\Lab Files\images folder.


Page 8 of 17

Step 6 Remark: the WebContent directory fulfills the same function as the WebContent directory in a J2EE application. You could introduce additional content here at your own risk.

Step 7 To switch back to the regular designer perspective, click Window > Open Perspective > Other > Domino Designer.

Step 8 Edit the page properties for your XPages (home, results, & profile) and set the basics > pageIcon to favicon.ico and the pageTitle to something meaningful:

Step 9 Save the changes to all 3 pages.

Step 10 Preview the results of the home page within both the Browser and Notes Client.


Page 9 of 17

Things to Explore: 1) Obviously Domino Designer is a regular Eclipse IDE application. So most of the things you know about eclipse will work here:

Add additional files to the NSF using the Eclipse Java perspective

Open a form or a view while in the Java perspective

Add standard Eclipse plug-ins (e.g. Aptana.com or XMLSpy.com)

Further Readings:

http://www.eclipseplugincentral.com/

http://eclipse-plugins.info/

http://www.eclipse.org/articles/using-perspectives/PerspectiveArticle.html

http://java.sun.com/j2ee/tutorial/1_3-fcs/doc/WebComponents3.html

SECTION 3: COMPLETE THE PROFILES APPLICATION WITH FORM & VIEW ELEMENTS

In this section, you will prepare additional form and view elements to complete the Profile XPages application. Every profile will be able to list connected profiles. To be able to do this we need a form that stores this connection information and a view that lists these connections. In the next section, you will put these elements to use in your profiles application.

Step 1 Create a New Form named friend, this will be a classic Notes form.


Page 10 of 17

http://www.eclipseplugincentral.com/

http://java.sun.com/j2ee/tutorial/1_3-fcs/doc/WebComponents3.html

http://www.eclipse.org/articles/using-perspectives/PerspectiveArticle.html

http://eclipse-plugins.info/

Step 2 Create 3 fields to that form:- FriendID (Text – Editable)- Name (Text – Editable)- Email (Text – Editable)

Step 3 Create a New View named friends.

Step 4 Use the selection conditions of By Formula and enter the following for the formula:

SELECT form = “friend”

Step 5 Open the new friends view and then add the following columns (all sorted ascending):- FriendID- Name- eMail

Step 6 You should now have both a new form and view for friends.


Page 11 of 17

Things to Explore: 1) Add additional fields like: friendTags (Multi-Value).

SECTION 4: EXTEND PROFILES TO ALLOW ADDING FRIENDS

In this section, you will learn how to use the repeat control. It will allow you you have free form repeating elements. On the profile custom control you will add a form that allows to add a profile as a friend as well as the list of current friends with the option to remove them.

Step 1 Open the profileForm custom control.

Step 2 At the bottom add a Table control with 5 rows and 2 columns and name it friendsTable.

Step 3 Add a visibility formula to that table: !document1.isNewNote()

Step 4 Merge the 2 columns in the first row and add a heading Friend List.

Step 5 In Row 2 Col 1 add a label: Friend Name.

Step 6 In Row 3 Col 1 add a label: Friend eMail.

Step 7 In Row 2 Col 2 add a Editbox: friendName.

Step 8 In Row 3 Col 2 add a Editbox: friendEmail.


Page 12 of 17

Step 9 Add a Type Ahead formula for the friendName field (partial):

@DbColumn(@DbName(), "profiles", 0)

Step 10 Switch to the Events tab and Add a simple action > Execute Script to the Focus > onBlur event of the friendName field:

var value = @DbLookup(@DbName(), "profiles", getComponent("friendName").getValue(), "Email");

var email = getComponent("friendEmail");if(null != value){

email.setValue(value);}

Step 11 In Row 4 > column 2, add a button named cmdfriendsButton with a label of Add as friend.

Step 12 Add action > Execute Script to the onClick event for that button:

var newFriendDoc = database.createDocument();newFriendDoc.appendItemValue("Form", "friend");newFriendDoc.appendItemValue("FriendID", document1.getNoteID());newFriendDoc.appendItemValue("Name",

getComponent("friendName").getValue());newFriendDoc.appendItemValue("Email",

getComponent("friendEmail").getValue());newFriendDoc.save();

getComponent("friendName").setValue("");getComponent("friendEmail").setValue("");


Page 13 of 17

Step 13 Select the Server Option Partial Update and select friendsTable as the element.

Step 14 Add a panel in row 5 column 2 and call it friendsContainer, you will use that as a refresh target later on.

Step 15 Add a Repeat container inside the friendsContainer panel, name it friendsRepeat.

Step 16 Set the collection name variable to friend.


Page 14 of 17

Step 17 As data binding add JavaScript:

if(!document1.isNewNote()){var friendsView = database.getView("friends");friendsView.refresh();return friendsView.getAllDocumentsByKey(document1.getNoteID());

}

Step 18 Add a panel inside the repeat control. This panel is used as container for the data binding. Call it friendsPanel. You can use that for styling the friends list (optional).

Step 19 Add 2 Computed Fields below each other and use Javascript data binding to bind them to:

- friend.getItemValueString("Name")- friend.getItemValueString("Email")

Step 20 Add a Link control to the right of the second computedField control, and label it (Remove).

Step 21 Add a Simple Action > Execute Script to the onClick event:

friend.removePermanently(true)

Step 22 Select Partial Update to the element friendsContainer.

Step 23 Your table should now look like the following:


Page 15 of 17

Step 24 Save the changes to the profileForm custom control.

Step 25 Preview your changes in both the Browser and Notes Client. Test the new functionality by adding a few friends. Notice that if you add a friend who already has a profile, their email address is pulled from the database automatically for you!


Page 16 of 17

Things to Explore: 1) Is the onBlur event the right place for our friend lookup?

2) Move the entire friend mechanism into a custom control. Use control properties to communicate with the main page/control.

Summary:

Congratulations! You have completed this fifth lab of the XPages workshop.

In this lab, you completed the following procedures:

• Added navigation to the Profiles XPages application

• Added a program icon to your Profiles XPages application

• Completed the Profiles application with additional form and view elements

• Extended the Profiles application by allowing user to add friends


Page 17 of 17