Xpages Lab 06 Themes Javascript Notes Agents

Domino's XPages Workshop

Lab Manual

Lab 6

Advanced Concepts – Themes, JavaScript, & Notes Agents

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

Page 1 of 18

Introduction:Now that your Profiles XPages application is pretty much completed, you will next learn about themes, javascript, and Notes Agents. You will learn about Themes and visual customization in the first section of this lab. You will learn how to use a combination of client and server side JavaScript in the second section of this lab. You will learn how to call a Notes agent from xPages and hand over the document for processing in the last section of this lab.

Description:This lab introduces the themes, JavaScript, and Notes Agent concepts. In this lab, you first will explore the Themes used in the discussion template and after that you will create a new Theme for use with your application. Then you will perform two tasks for adding Java Script: 1) Before a server side action is performed you execute a client side script that determines if that server-side script should execute at all.2) In a client side script you want to use server side script constructs. Lastly, use your scrapbook database. Create one form with 3 fields: color, shape (editable, text), statement (text, computed when composed, formula -> empty string), create a view to show those documents. Put both onto a single xpage and make an agent process the document when saved in xPages.

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

• Know what themes are and how to apply them to your XPages applications

• Know the difference between Client side and Server side JavaScript

• Understand how to use Notes Agents

Procedure:

SECTION 1: LEARN ABOUT THEMES FOR XPAGES

In this section, you will learn about Themes and visual customization. You first will explore the Themes used in the discussion template and after that you will create a new Theme for use with your application.


Page 2 of 18

Step 1 Create a New Application based on the discussion template.

Step 2 Set the access control of the database to allow for anonymous access (otherwise you can't preview stuff without a server).


Page 3 of 18

Step 3 Preview the database in the Notes Client and check out the functionality.

Step 4 With the database open in Designer, change the theme in the Application Properties:


Page 4 of 18

Step 5 Save the changes. Preview the database in the Notes Client again and check out the changes to the theme by applying the Tux theme to your application.

Step 6 Open the tux theme in the Designer and have a look inside.


Page 5 of 18

Step 7 Modify this theme for your own application (demo discussion). Scroll to the end of the file and add this code under the comment for :

<control override="false"><name>InputField.EditBox</name><property mode="concat">

<name>style</name><value>;height:20px;font-size:18px;</value>

</property></control>

NOTE: This piece of code will change the height of the edit/input boxes and also the font size for the text that goes in them. Making it easier to read on higher resolution monitors.

Step 8 Modify the <theme> tag (at the top of the file) to be:

<theme extends=”oneui”>


Page 6 of 18

Step 9 Save the changes. Preview the changes to the theme within the Notes Client. You'll have to create a new topic document in order to see an edit/input box.


Page 7 of 18

Things to Explore: 1) Themes can extend other themes. There can be server wide themes or database specific themes. Themes can use JavaScript to determine settings (as can be seen in the Discussion template themes).

2) You also can add code to switch a theme on the fly: var curID = context.getThemeId(); var newID = (curID == "webstandard") ? "oneui" : "webstandard"; context.setSessionProperty("xsp.theme", newID)

Further Readings:

Domino Designer help

SECTION 2: UTILIZE A COMBINATION OF CLIENT AND SERVER SIDE JAVASCRIPT

In this section, you will learn how to use a combination of client and server side JavaScript. There are two tasks: 1) Before a server side action is performed you execute a client side script that determines if that server-side script should execute at all. 2) In a client side script you want to use server side script constructs.

Step 1 Open the profileForm custom control.

Step 2 Navigate to the link control inside the friends repeat control that contains the Remove command. Your server side code should look like that:


Page 8 of 18

Step 3 Click on the Client tab, select the Script Editor option and enter the following formula:

if (confirm(“Are you sure to remove that friend?\n(You always can talk about it)”)) { return true;} else { return false;}

Step 4 Preview the application within a Browser and test the new client check.

Step 5 Create a New XPage in your scrapbook database, name it test.

Step 6 Create a button control with the following server side code:

sessionScope.myVariable = “Server Code test”;

Step 7 Create two more button controls to test the following client side JavaScript Code:

tmp = “#{javascript:@DbName()}”; alert(tmp);

tmp = “#{sessionScope.myVariable}”; alert(tmp);

NOTE: The second line of code must be created as a Client > Simple Action > Execute Client Script.


Page 9 of 18

Step 8 Save all of the changes you just made.

Step 9 Preview the test XPage within the Browser to test the code's functionality.

Things to Explore: 1) What happens if you use ${...} instead of #{...} for your macro inclusion?

Further Readings:

http://www.jmackey.net (Category Domino 8.5 – XPages)

http://particletree.com/features/a-guide-to-unobtrusive-javascript-validation/

http://ajaxian.com/archives/fvalidator-unobtrusive-javascript-tool-for-easy-handling- form-validation


Page 10 of 18

http://www.jmackey.net/

http://ajaxian.com/archives/fvalidator-unobtrusive-javascript-tool-for-easy-handling-form-validation



http://particletree.com/features/a-guide-to-unobtrusive-javascript-validation/

SECTION 3: CREATE A NOTES AGENT USING LOTUSSCRIPT FOR XPAGES

In this section, you will learn how to call a Notes agent from xPages and hand over the document for processing. Use your scrapbook database. Create one form with 3 fields: color, shape (editable, text), statement (text, computed when composed, formula -> empty string), create a view to show those documents. Put both onto a single xpage and make an agent process the document when saved in xPages.

Step 1 Create a New Form and name it AgentDemo. Add 3 fields:- color (text, editable)- shape (text, editable)- statement (text, computed when composed)

Step 2 Select the statement field and enter the formula of an empty string, “”.

Step 3 Create a New View named AgentDemos with 3 columns to show color, shape, & statement. Use this view selection formula:

SELECT (Form = “AgentDemo”)


Page 11 of 18

Step 4 Create a New XPage named AgentSample and add Edit Box fields for color and shape. Below those, add a button to save the form. And below that add a view to see the existing document. (Don't forget the data binding!) It should look similar to this (feel free to make it pretty):

Step 5 In the button, add a simple action to Document > Save Document.


Page 12 of 18

Step 6 Save the changes you made. Preview your AgentSample XPage within both the Browser and Notes Client to test the form, view, & page. It will create new entries with an empty statement column (not that this example makes any business sense, that's why it is in your scrapbook).

Step 7 Locate the data events of the XPage (near the root) and expand the events linked to the document:


Page 13 of 18

Step 8 Add the following code to the postSaveDocument data event:

ag = database.getAgent("agFromXpage");noteid = agSampleDoc.getDocument().getNoteID();ag.run(noteid);

NOTE: The name of the document (ie: agSampleDoc), comes from the data binding options that you created. The document name should be the same as the data source name used.

Step 9 Create a New LotusScript Agent, call it agFromXpage.


Page 14 of 18

Step 10 Add the following code (again not too useful, but does create a statement field out of the color and shape fields entered via form):

Sub Initialize Dim db As NotesDatabase Dim doc As NotesDocument Dim s As New NotesSession Dim ag As NotesAgent Dim noteid As String Set db = s.CurrentDatabase Set ag = s.CurrentAgent noteid = ag.ParameterDocID Dim statement As String Set doc = db.GetDocumentByID(noteid) If doc Is Nothing Then Print "Document not found" Exit Sub End If If doc.color(0) ="" Or doc.shape(0) = "" Then Statement = "Half baken data entry, too bad!" Else Statement = "You choose " + doc.color(0) + " and "+ doc.shape(0) End If Call doc.ReplaceItemValue("statement",Statement) Call doc.Save(True,True) End Sub

Important remark here:In a “classic” WebQuerySave agent a handle to the current document is obtained using NotesSession.DocumentContext. That handle returns the NotesDocument after it has been processed by the server BEFORE it hits the disk. You can use NotesDocument.SaveOptions = “0” to prevent a save.In xPages currently you hand over a NodeID (not a universal-ID!) to the agent and the agent code needs to use NotesSession.currentAgent.ParameterDocID to get the ID of the document and retrieve it. The document will be in it's saved state (so if you call an agent other than from the PostSave event you will have an OLD copy of the data to work on (which can be useful too).In a WebQuerySave agent “Print” statements are sent back to the browser. Currently the xPages implementation doesn't support this, so you might need to write return information into a field in the document, so xPages can pick them up from there.


Page 15 of 18

Step 11 Under the Properties for the new agent, make sure the Runtime Target is set to None.

Step 12 Save all of your changes.


Page 16 of 18

Step 13 Preview your updated AgentSample XPage within both the Browser and Notes Client to test the form, view, & page. Notice how the Statement field now gets filled in, thanks to the LotusScript code.

Things to Explore: 1) Use an auxiliary document to transport values to/from an agent.

2) Checkout the difference between run and runOnServer.

3) Let your agent call a web service?


Page 17 of 18

Summary:

Congratulations! You have completed this overview lab of XPages.

In this lab, you completed the following procedures:

• Learned about Themes within XPages

• Utilized both client and server side JavaScript

• Created a Notes Agent using LotusScript for use within the XPages app


Page 18 of 18

Xpages Lab 06 Themes Javascript Notes Agents

Documents

server side

client side

server side

server side

side script

discussion

empty string

notes client