1) This document provides 30 tips for using XPages in 60 minutes. 2) The tips cover general programming, debugging, user interface design, using XPages in the Notes client, and working with Dojo. 3) Example tips include using scoped variables to store data, calling Java classes from XPages, turning on debugging to view error messages, using themes for global configuration, and enabling Dojo parseOnLoad to initialize widgets.

1. XPages Blast
30 top tips in 60 minutes
1
1

2. Matt White
Lead Developer at
Creators of IdeaJam and IQJam
Creator of XPages101.net
Use coupon code “ilug2010” for a 33%
discount
Founder member of the LDC
2
2

3. Tim Clark
16+ years in Lotus brand
Support, Sales and Channel
Creator of the X Cast, XPages podcast
http://bit.ly/ilugmo
3
3

4. Agenda
General Programming Tips
Debugging
UI
Notes Client
Dojo
4
4

5. Tip Grading
Beginner
Intermediate
Advanced
5
5

6. Sample Database
You can download a database which
demonstrates a lot of tips we talk about here:
http://tinyurl.com/xpagesblast
6
6

7. General Programming Tips
Those useful bits and pieces that make your
coding day fly by!
7
7

8. 1. Scoped Variables
applicationScope
use to store data for all users of the app
sessionScope
use to store data for the current user
viewScope
use to store data for the current page
requestScope
use to store data for a single round trip to the server
8 scopedvariables.xsp
8

9. 2. Repeat ANY data
Repeat controls can be used with any type of
data, not just view data.
As long as the data is a list of some sort and you
know how to reference it
@Functions can return a string or a list, to make
sure the results work, use this $A function:
http://tinyurl.com/xpbrepeats
9 repeats.xsp
9

10. 3. Calling a Notes Agent
in 8.5.0 or 8.5.1
Don’t do it unless you really need to!
Running code as a different user (e.g. an admin)
You’ll probably end up having to save the document twice,
so it’s very expensive.
However, if you really have to...
var agent:NotesAgent = database.getAgent(“myagent”);
agent.runOnServer(noteid);
Or you can always call an old style agent URL using AJAX
(we’ll show you how later on)
10
10

11. 4. Calling a Notes Agents
in 8.5.2 +
In 8.5.2 you can call an agent and pass an “in memory” document to
it:
Agent.runWithDocumentContext(NotesDocument)
There are also three different types of session object available:
session - the current user’s session
sessionAsSigner - a session running as the XPage signer
sessionAsSignerWithFullAccess - a session running as
the XPage signer giving full admin rights
Running SSJS is always going to be faster than calling an agent
11
11

12. 5. ACLs in XPages
If not done, people may be able to create documents that you are not
expecting
Go to All Properties > Data > ACL and add ACL settings
Settings can be made for:
Default
Anonymous
Individuals
Groups
Roles
12
12

13. 6. #{id:mycontrol}
Used if you want to know what the id of the field will
be at runtime
Use this syntax to identify a specific field:
Also works in reused controls
13 clientsidereferences.xsp
13

14. 7. Calling SSJS in CSJS
If you want to pass server side data to the
client side as the page loads you can use:
#{javascript:myfunction()}
Returns the result of “myfunction” at runtime
inside your CSJS
14 clientsidereferences.xsp
14

15. 8. XPages Extension
Library
A free download from OpenNTF:
http://extlib.openntf.org/
Provides a whole bunch of extra
controls for your XPages
Just needs a simple install on the
server to enable to extra controls
15
15

16. 9. Localization
Easy to do
Turn it on
Pick which languages you
want to support
Edit the translation files
You’re done. ;o)
16
16

17. 10. Using Java classes
Great for network operations and other pre-rolled
Java functionality
Create a “lib” folder using the package explorer
Import your .jar file
Refer to the full package structure or use
“importPackage”
importPackage(com.xpagesblast.demo);
var text = getComponent("inputtext").getValue();
var speaker:SaySomething = new SaySomething(text);
getComponent("out").setValue(speaker.whatDoYouSay());
17 java.xsp
17

18. 11. Using an XPage as a
servlet
If you want to get the memory resident benefits of an XPage but don’t want to return
HTML then...
Set the rendered property to False
In afterRenderResponse event return required data:
try{
var exCon = facesContext.getExternalContext();
var writer = facesContext.getResponseWriter();
var response = exCon.getResponse();
response.setContentType("text/plain");
writer.write("Hello World");
writer.endDocument();
facesContext.responseComplete();
writer.close(); //Leave this line out in 8.5.2
}catch(e){
_dump(e);
}
18 servlet.xsp
18

19. 12. IgnoreRequestParams
Control individual document bindings on a single XPage
In All Properties > Data > Data > dominoDocument, set
ignoreRequestParams to false
Then whatever default action you have defined for the
document data binding will take precedence over the
URL Parameters
Useful for blog comments
19 requestparams.xsp
19

20. Debugging
Because although we never create bugs,
sometimes more information is useful
20
20

21. 13. Configure Firewall
A lot of local firewalls block ports on the local
machine
You’re basically running a local Websphere server
on a port somewhere in the 30,000+ range
You will never see an error so it’s difficult to debug
Either disable the firewall or work out a rule which
allows the server to run
21
21

22. 14. Turn on debugging
In the Application properties, check the “Display XPages
Runtime Error Page” box.
Then when there is an error in your code you’ll get a more
useful message
22
22

23. 15. Common Error
Messages
Error Code Most Likely Cause
500 There’s an error in your code. Idiot ;-)
A typo in your URL. Remember the XPage
404 name is case sensitive
Forbidden error, the signing ID doesn’t have
403 rights to run XPages
Shows up a lot in server logs. It’s a
302 redirection and can be ignored.
23
23

24. 16. Use OpenLog
Download OpenLog from OpenNTF
http://www.openntf.org/projects/pmt.nsf/ProjectLookup/
OpenLog
Download TaskJam (which has the script library in) from
OpenNTF
At the top of your SSJS
import OpenLogXPages
Implement using
log.logEvent("Clearing the Cache", SEVERITY_LOW, "serverSide",
"resetApplicationScope", null);
or
log.logError(“There was an error”, ! SEVERITY_HIGH, “Error Message”,
“Error Number”, “Location”, “Method”, “Error Line”, document);
24
24

25. 17. Use Firebug
The single most important debugging tool for XPages
Lets you inspect HTML, CSS and CSJS
Network operations and AJAX requests
Download from Tools in Firefox or
http://getfirebug.com
In CSJS use
dojo.console(“message”);
25
25

26. 18. Use Medusa
A plugin for XPages developers to use inside Firebug
Allows you to test SSJS code live
Compare the HTML to the source XML of your XPage
Download from OpenNTF
Buy Tim Tripcony, Nathan Freeman & Colin McDonald a drink next
time you see them.
26
26

27. User Interface
Because even though we’re programmers,
the UI is important
27
27

28. 19. Themes & Global
Config
Want to set something once and have it used everywhere, use
Themes
Can set; stylesheets, classes on elements or pick a skin
dynamically using simple XML, for example:
<theme>!
! <resource>
! ! <content-type>text/css</content-type>
! ! <href>custom.css</href>
! </resource>
! <control>
! ! <name>InputField.RichText</name>
! ! <property mode="concat">
! ! ! <name>styleClass</name>
! ! ! <value>domino-richtext xspInputFieldRichText</value>
! ! </property>
! </control>
</theme>
28
28

29. 20. Use a CSS framework
OneUI - http://tinyurl.com/xpboneui
Download “XPages framework” from OpenNTF
Or use the OneUI control in the Extension Library
Blueprint - http://tinyurl.com/xpbblueprint
960 Grid - http://tinyurl.com/xpb960grid
Doesn’t matter which one, just USE ONE!!!!!
29
29

30. XPages in Notes Client
XPiNC
30
30

31. 21. Use &SessionID
If manually building URLs for the Notes Client
In 8.5.1 you HAVE TO add the SessionID
parameter:
&SessionID=tclk48931240
Error 503 with no other explanation if you
don’t add it
It’s been fixed in 8.5.2
31
31

32. 22. View Page Source
Toolbar button only available if Designer
installed
Shows the source HTML of XPages in Notes
client
Useful because the HTML in the Notes Client
is not always the same as in a web browser
32
32

33. 23. View Logs in
Notes Client
From menu
Help, Support, View Trace
Where the print statement output from SSJS is displayed
SSJS output only, CSJS output is not visible in XPiNC
33
33

34. 24. Difference in URLs
If you manually build URLs be aware that there
are different structures between the Notes Client
and the web browser:
Web Browser
/directory/XPagesBlast.nsf/test.xsp
Notes Client
/xsp/ServerName!!directory/XPagesBlast.nsf/test.xsp
34
34

35. Dojo
Not the fight place!
35
35

36. 25. Enable parseOnLoad
If you have Dojo widgets on your XPage then you should
set this to true, to have them automatically initialize
Unless you want to manually initialise Dojo Elements
yourself using Javascript
36
36

37. 26. Dialog box
If you want to interact with the server from
inside your dialog box. You have to work
around a “feature”.
Best option is to use Jeremy Hodge’s
approach: http://tinyurl.com/xpbdialog
Include CSJS Library in your XPage, then
enable dojoParseOnLoad and dojoTheme
“feature” = BUG
37 dialog.xsp
37

38. 27. Dojo Ajax Request
Writing your own Ajax can still be useful, simply use the xhr
API:
38 ajax.xsp
38

39. 28. Charting
dojox.charting offers a huge array of charting options
For a simple pie chart
import the basic modules
add the data (formatted as JSON)
add CSJS to initialize the chart
No flash required
offers animation
Tooltips
Legends
39 chart.xsp
39

40. 29. How to show images
Add Dojo resource:
dojox.image.Lightbox
Add Stylesheet
/.ibmxspres/dojoroot/dojox/
image/resources/Lightbox.css
Build <a> tags with dojoType of
dojox.image.Lightbox and then enable
ParseOnLoad
40 lightbox.xsp
40

41. 30. How to use jQuery
Use when you want to make use of
a jQuery plugin
Import the jQuery library into the
database design as a file resource
Everything else works as you
would expect with jQuery
A good example is the Full
Calendar Plugin http://
arshaw.com/fullcalendar/
41 jquery.xsp
41

42. Questions?
?
Matt White Tim Clark
matt.white@elguji.com tim_clark@uk.ibm.com
@mattwhite @timsterc
mattwhite.me blog.tc-soft.com
42
42