This document provides an overview of server-side JavaScript (SSJS) in XPages, including what it is, common practices, and code samples. SSJS allows using JavaScript logic on the server similarly to how it is used in browsers but with additional platform-specific features. It discusses how SSJS is both similar to and different from standard JavaScript, and recommends practices such as taking advantage of Java integration and error handling. The document concludes with code samples for applications using SSJS for tasks like managing application state and performing searches.

1. AD111
Harnessing the Power of Server-Side JavaScript and
Other Advanced XPage Techniques
Tim Tripcony | GROUP Experts - XMage
Stephan H. Wissel | IBM - Lotus Technology & Productivity Advisor

2. Agenda
● What exactly is Server Side Java Script (SSJS)
● Common practices: pattern & anti-pattern
● Code samples
The REAL Agenda: code, code, code
2

3. Server-side JavaScript is JavaScript
● all ECMAScript 3 keywords, operators and syntax still apply
▬ var myNumber = 0;
▬ var myArray = [ ]; // preferred over new Array();
▬ var myObject = { }; // preferred over new Object();
▬ function foo(){return "bar";}
▬ var depends = someBoolean ? "default" : "other";
● ECMAScript scope rules apply, including closure
▬ More in the Demo section
3

4. Server-side JavaScript is not JavaScript (1)
● browser-specific globals not available
▬ window
▬ document
▬ location
● Platform-specific globals and JSF-specifics
▬ session: current NotesSession
▬ database: current NotesDatabase, equal to
session.getCurrentDatabase()
▬ param: URL parameters and post data
▬ context & facesContext: current state data and direct access to
servlet engine
4

5. Server-side JavaScript is not JavaScript (2)
● @functions (e.g. @UserName() )
● scope variables
▬ requestScope
▬ viewScope
▬ sessionScope
▬ applicationScope
● Optional type declarations
● Seamless Java™ integration
5

6. Agenda
● What exactly is Server Side Java Script (SSJS)
● Common practices: pattern & anti-pattern
● Code samples
6

7. The use of context
● getUser(): access to name, roles, groups, and more
● getUrl(): no more String parsing to get query string parameters and other
URL info
● getUserAgent(): server-side browser detection
● redirectToPage() / redirectToHome(): easy programmatic navigation
7

8. The use of facesContext
● getResponseWriter() / getResponseStream(): send your own output to
the browser (like Print in LotusScript)
● getExternalContext(): direct access to the servlet
▬ getRequest()
▬ GetResponse()
● You need to understand the difference between the ResponseWriter
and ResponseStream
▬ Writer doesn't take binary data
▬ Stream excludes Writer
▬ Can only use one per request

9. JavaScript Closures
● An object returned from a function has access to variables defined within
that function
▬ Includes arguments passed to the function
● This allows for OOP constructs in JavaScript objects
▬ Private properties
▬ Private functions
▬ Inheritance without .prototype
9

10. Take advantage of XPages' JSF heritage
● Java Objects at your disposal
▬ java.util: powerful storage and iteration
▬ java.net: easy access to remote data
▬ Core JSF packages and IBM's implementation
● Get to the servlet
● Write your own servlet (you are on your own here)
10

11. Write agent Style code in XPages
● Control the rendering
● Get the output writer
● Get the output stream (one of the two)
● Use cases:
▬ Replace web agent (?OpenAgent)
▬ Output other formats (PDF, ODF)
11

12. The use of scope
● requestScope: storage for anything needed multiple times in the same
HTTP request
● viewScope: survives for the life of a page - including partial and full
refresh events
● sessionScope: "shopping cart" storage - survives for the duration of a
user's session, BUT can expire even if the user is still logged in (set in
application properties to balance server performance with application
performance)
● applicationScope: storage shared among all users of the NSF - any data
that numerous users are likely to need but shouldn't be queried on every
request
12

13. Anti-Pattern: What always goes wrong
● The network is fast and reliable
● Configuration parameters are retrieved through @DBLookup
● Connect to JDBC without a session pool
● Use data binding when you access data, not anything else
13

14. Everybody's favorite objects
● UI Elements
▬ Create a control programmatically
▬ Update control properties via event handlers
● DOMUtil
▬ Parse DXL and other XML
● cookie
▬ Set and read cookies using .put() and .get()
14

15. Error Handling
● try/catch: provide individual operations that might fail a specific response
to failure
● Enable “Display default error page” during development and testing
● Create custom error pages to display uncaught exceptions
15

16. Debugging
● print(): send a single String statement to server log and console
● _dump(): send detailed info about any object to log and console
16

17. Unit Tests
● Courtesy of Lorcan McDonald (IBM Lab Dublin)
● Available on OpenNTF
● Enables Test Driven
Development (get used to it)
http://openntf.org/internal/ontfcatalog.nsf/topicThread.xsp?action=openDocument&documentId=9C66A4F3854E61BE852575A1003C6CAD
17

18. Reaching out to Java
● Put source into webcontent/source
● Add directory to Java build path
● Package name required
● Define like a JavaScript variable:
var xy = new com.acme.RoadRunner();
xy.foolCoyote(“Meep Meep”);
18

19. Managed Beans
● Concept inherited from JSF underpinnings
● Bean is described in XML declaration
● Can be used in JavaScript expressions
● Automatically loaded when needed
● Bound to a specific scope
● Take advantage of Java capabilities (e.g. Connection pooling, threading
etc)
19

20. Agenda
● What exactly is Server Side Java Script (SSJS)
● Common practices: pattern & anti-pattern
● Code samples
20

21. Application Chat
● Application Context
● Synchronized Access
● Closure
● Periodic partial refresh
21

22. Shopping Cart
● Session Context
● Closure
● Java integration
22

23. Cached Search
● Application Context
● Managed Bean
● Network handling
23

24. Q&A
24

25. Legal Disclaimer
● © IBM Corporation 2009. All Rights Reserved.
The information contained in this publication is provided for informational purposes only. While efforts were made to verify the completeness and accuracy of the information contained in this publication, it is provided AS IS
without warranty of any kind, express or implied. In addition, this information is based on IBM’s current product plans and strategy, which are subject to change by IBM without notice. IBM shall not be responsible for any
damages arising out of the use of, or otherwise related to, this publication or any other materials. Nothing contained in this publication is intended to, nor shall have the effect of, creating any warranties or representations
from IBM or its suppliers or licensors, or altering the terms and conditions of the applicable license agreement governing the use of IBM software.
References in this presentation to IBM products, programs, or services do not imply that they will be available in all countries in which IBM operates. Product release dates and/or capabilities referenced in this presentation
may change at any time at IBM’s sole discretion based on market opportunities or other factors, and are not intended to be a commitment to future product or feature availability in any way. Nothing contained in these
materials is intended to, nor shall have the effect of, stating or implying that any activities undertaken by you will result in any specific sales, revenue growth or other results.
IBM, the IBM logo, Lotus, and Lotusphere are trademarks of International Business Machines Corporation in the United States, other countries, or both.
Java and all Java-based trademarks are trademarks of Sun Microsystems, Inc. in the United States, other countries, or both.
All references to ACME refer to a fictitious company and are used for illustration purposes only.
25