Mastering XPages

The authors of this book have a number of things in common. All three hail from Ireland, work for the IBM Ireland software lab, and have made significant contributions to the development of XPages over the past number of years. Martin Donnelly is a software architect and technical lead for the Domino Designer and XPages teams in IBM Ireland. He has worked on all XPages releases to date and also on a precursor technology known as XFaces. Martin was also a development contributor to such products as the IBM Java Visual editor and IBM Rational Application Developer. In the 1990s while living and working in Massachusetts, Martin was a lead developer on Domino Designer; this has now gone full circle as he rejoined the Domino Designer team in 2013 to head up the 9.0.1 release. Martin lives in Cork with his wife Aileen, daughters Alison, Aisling, and Maeve, and retired greyhounds Evie and Chelsea. Outside of work his main leisure time pursuits are soccer, fishing, and gardening. Mark Wallace is a software architect in the IBM Ireland software lab. In the past, he worked on the XFaces runtime, which was developed for Lotus Component Designer and subsequently evolved into the XPages runtime. He has a keen interest in programming models and improving developer productivity. Mark has worked in Lotus and IBM for more than 17 years on various products, and he is currently leading the Social Business Toolkit open source project. Mark lives in Dublin with his wife and two children and spends as much time as possible in the Ireland’s sunny south east enjoying fishing and kayaking with his family. Tony McGuckin is a senior software engineer in the IBM Ireland software lab. Having studied software engineering at the University of Ulster, he began his career with IBM in 2006 and joined the XPages core runtime team shortly thereafter. When not directly contributing to the core runtime, Tony is busy with software research and development for the next generation of application development tooling, most recently focusing on mobile and responsive design. Tony also spends a lot of time directly engaging with IBM customers as an XPages consultant, where he shows his flair for UI development and his deep understanding of application performance. Tony enjoys spending time with his wife and daughter, and getting out into the great outdoors for hill walking and the occasional chance to do some hunting in the surrounding hillsides of his native County Derry.

Foreword     xxiii
Preface     xxvii
PART I:  GETTING STARTED WITH XPAGES
Chapter 1  An Introduction to XPages     3
XPages Fundamentals     3
Onward and Upward: A Path of Continuous Improvement     4
The XPages Development Paradigm     8
   The More Things Change, the More Things Stay the Same     10
New Horizons     11
Conclusion     12
Chapter 2  Getting Everything You Need     13
Downloads, Versions, and Locations     13
Installing Domino Designer      14
Installing Client Fix Packs     14
Client Configuration     15
Quick Tour of Domino Designer     16
   Domino Designer Home Page     17
   Domino Designer Perspective     17
   Creating a New Application     19
   Creating an XPage     20
   Previewing in the Notes Client     21
   Previewing in a Web Browser     22 
   Adding a Control to an XPage     24
Working with the XPages Extension Library     26
   Some Quick Notes on Extension Library Structure      30
Conclusion     32
Chapter 3  Building Your First XPages Application     33
Laying the Foundations     34
Forms and Views     36
Building an XPages View     41
Completing the CRUD     47
Conclusion     53

PART II:  XPAGES DEVELOPMENT: FIRST PRINCIPLES
Chapter 4  Anatomy of an XPage     57
What Exactly Is an XPage?     58
Understanding XSP Tag Markup     59
   Getting Started with XML     59
   XPages XML Syntax     62
   Simple Properties     63
   Complex Properties     64
   Complex Values     66
   Computed Properties     67
   Data Binding     72
   XPages Tags     72
Data Sources     73
   Domino Document     73
   Domino View     74
   Data Context     75
Controls     76
   Editing Controls     77
   Command Controls     82
   Selection Controls     85
   Display Controls     94
   File-Handling Controls     95
Containers     98
   Panel     98
   Table     101
   View     102
   Data Table     105
   Repeat     106
   Include Page     109
   Tabbed Panel     110
   Section     111
XPage Resources     111
   JavaScript Library     112
   Style Sheet     114
   Resource Bundle     115
   Dojo Module and Dojo Module Path     116
   Generic Head Resource     116
   Metadata Resource     117
Converters     118
Validators     121
Simple Actions     128
Client-Side Scripting     134
HTML Tags     136
Extension Library     137
   Dynamic Content     138
   Change Dynamic Content Action     142
   In Place Form     143
   Dialog, Dialog Context, and Dialog Button Bar     147
   Tooltip Dialog     150
   JSON RPC Service (Remote Service)     154
Conclusion     156
Chapter 5  XPages and JavaServer Faces     157
What Is JavaServer Faces?     158
JSF Primer     159
How Does XPages Extend JSF?     166
   XML-Based Presentation Tier     169
   Request Processing Lifecycle     169
   User Interface Component Model     170
   Standard User-Interface Components     176
   Value Binding and Method Binding Expression Evaluation     179
   XPages Default Variables     182
Conclusion     186
Chapter 6  Building XPages Application Logic     187
Adding Application Logic     187
   Using the xp:eventHandler Tag     190
Simple Actions     198
   Change Document Mode     198
   Confirm Action     199
   Create Response Document     200
   Delete Document     201
   Delete Selected Documents     202
   Execute Client Script     203
   Execute Script     204
   Modify Field     205
   Open Page     205
   Publish Component Property     207
   Publish View Column     208
   Save Data Sources      209
   Save Document      211
   Set Component Mode     213
   Set Value     214
   Action Group     215
   Send Mail     217
Change Dynamic Content     219
Move to Application Page     220
Using JavaScript with XPages     220
   Server-Side JavaScript     221
   Client JavaScript     240
Conclusion     250

PART III:  DATA BINDING
Chapter 7  Working with Domino Documents     253
Domino Document Data Source     254
   Creating and Editing Documents     257
   Controlling URL Parameter Usage     258
   Creating Response Documents     258
   Executing Form Logic     263
   Managing Concurrent Document Updates     266
   Multiple Document Data Sources     272
   Document Data Source Events     274
   webQuerySaveAgent     278
   Common Data Source Properties     282
   Miscellaneous Data Source Properties     282
Working with Domino Documents—Programmatically!     283
   Simple Actions     283
   JavaScript     284
Rich Documents     286
Conclusion     291
Chapter 8  Working with Domino Views     293
databaseName Property     295
View Data Source Filters     296
   categoryFilter Property     297
   Full Text Search Properties     299
   parentId Property     304
   ignoreRequestParams Property     305
   keys, keysExactMatch Properties     306
Other View Content Modifiers     309
   startKeys Property     310
   expandLevel Property     310
A Page with Two Views     312
   requestParamPrefix Property     313
When Is a View Not a View?     314
Go Fetch! Or Maybe Not     315
   loaded, scope Properties     316
   postOpenView, queryOpenView Properties     316
Caching View Data     318
Sorting Columns     323
   Combining Searching and Sorting     323
Accessing Calendar Data     326
   The XPages Calendar REST Service     327
   The iNotes Calendar Control     330
Conclusion     336
Chapter 9  Beyond the View Basics     337
Pick a View Control, Any View Control     337
The View Control: Up Close and Personal     340
   Column Data Like You’ve Never Seen Before     341
   Simple View Panel Make Over     343
   Working with Categories     357
   View Properties and View Panel Properties     366
Data Table     370
   Building a Mini Embedded Profile View Using a Data Table     376
Repeat Control     381
   A Repeat Control Design Pattern     383
   Nested Repeats     384
   The Rich Get Richer     386
Data View     387
   Configuring a Basic Data View Control     389
   Using More Advanced Data View Control Features     392
Some Fun with the Pager     395
Conclusion     398

PART IV:  PROGRAMMABILITY
Chapter 10  Custom Controls     401
Divide and Conquer     402
Getting Started with Custom Controls     403
Using Property Definitions     411
   Property Tab     415
   Validation Tab     417
   Visible Tab     419
   Property Definitions Summary     420
Using the compositeData Object     421
Send and You Shall Receive     427
   Multiple Instances and Property Groups     430
Custom Control Design Patterns     432
   Aggregate Container Pattern     432
   Layout Container Pattern     433
Conclusion     441
Chapter 11  Advanced Scripting     443
Application Frameworks     443
AJAX and Partial Refresh     444
   Partial Refresh: Out-of-the-Box Style!     445
   Partial Refresh: Doing-It-My-Way Style!     453
Event Parameters     460
Dojo Integration     463
   dojoTheme and dojoParseOnLoad Properties     463
   dojoModule Resource     464
   dojoType and dojoAttributes Properties     466
    Integrating Dojo Widgets and Extending the Dojo Class Path     466
Working with Traditional Notes/Domino Building Blocks     478
   Working with @Functions, @Commands, and Formula Language     479
   Working with Agents, In-Memory Documents, and Profile Documents     482
Managed Beans     490
Fulfilling a Customer Requirement: A Practical Field Study     496
   Comparing Apples with Apples!     497
   Who, What, Where, and (More Important) How?     503
Conclusion     536
Chapter 12  XPages Extensibility     537
How to Create a New User Interface Control     538
Example Component     539
Let’s Get Started     540
   Create the Initial Application     540
   Add Package Explorer to the Domino Designer Perspective     541
   Add a Java Source Code Folder     543
Building a Component     544
   Create a UI Component Extension Class     545
   Create Tag Specification (.xsp-config) for the UI Component Extension     547
Create a Renderer and Register It in the Application Configuration
   (faces-config.xml)     551
Quick Test Application to Verify Everything Is OK So Far     554
Working with Component Properties     555
   Component Properties and Attributes     555
   Adding a Property to a Component     556
   State Holder: Saving State Between Requests     556
   Specifying Simple Properties     557
   Inheriting xsp-config Properties     558
Create the Initial xsp-config Definitions     562
   Create base.xsp-config     562
   Create an Interface to Match the Group Property Definition in base.xsp-config     565
   Revisit the Component Properties in Domino Designer     568
Specifying Complex Properties     568
Complete the xsp-config for the UISpinner Component     579
Complete the UI Component Extension, UISpinner     588
Complete the Renderer UISpinnerRenderer     591
Create a Sample Application Using the UISpinner Component     597
   Take Your New UI Component Extension for a Test Drive     597
   Create a Backing Bean     597
   Register the Backing Bean     600
   Create the Final Test Application     600
   Nice Look and Feel     604
   Test to Ensure That It All Works!     604
Where to Go from Here     605
   XPages Extensibility API Developers Guide     605
   XPages Extension Library     606
   IBM developerWorks     606
Conclusion     606
Chapter 13  XPages in the Notes Client     607
Think Inside the Box     608
Getting Started with XPages in the Notes Client     610
3, 2, 1...Lift Off     612
Bookmarks     614
Working Offline     616
One of These Things Is Not Like the Other     619
Other Subtle Differences     621
Extended Client-Side JavaScript Commands     624
XPages: A Good Notes Citizen     632
Introducing enableModifiedFlag and disableModifiedFlag     634
Keeping Tabs on Your Client Apps     637
Notes Links Versus Domino Links     641
Some XPiNC Debugging Tips     645
Optimizing XPages for Notes     649
   Single Copy XPages Design Meets Preload     652
   XPages RunOnServer     657
XPages and Composite Applications     664
   Making a Component of an XPages Application     664
   Is Anyone Out There? Creating a Component that Listens to Your XPages Component     666
   Assembling a Composite Application: Aggregating the XPages Discussion Component and Notes Google Widget        668
   Hey, This Is a Two-Way Street. A Component May Receive and Publish Events     672
Further Adventures with Composite Applications     675
Chapter 14  XPages Mobile Application Development     677
Getting Started with Mobile Application Development     678
   Safari Browser     680
   Chrome Browser     681
   Firefox Browser     682
   User Agent Device Detection     682
   Device Bean     683
Single Page Application Design Pattern     685
   Mobile XPage Properties     686
   Single Page Application Control (xe:singlePageApp)     687
Mobile Application Navigation     688
   Navigator     690
   Hierarchical Navigation     692
   Context-Sensitive Navigation     694
Interacting with a Mobile Application     697
   Orientation-Based Interaction     697
   Touch-Based Interaction     701
   Multitouch-Based Interaction     702
Mobile Themes     703
   Data View     704
   Outline     706
   Form Table     706
   Styling XPages Controls for Mobile Applications     707
Debugging Mobile XPages     710
   Debugging XPages on iOS     711
   Debugging XPages with Web Inspector Remote (aka weinre)     713
XPages Mobile Extensions     716
   Infinite Scrolling     717
   Single Page Application Wizard     718
Summary     724
Chapter 15  XPages Unplugged and Debugged     725
Debugging XPages Apps on the Server Side     726
   Printing, Dumping, and Logging     726
   try / catch / finally     729
   Introducing the SSJS Debugger     735
   Using the Java Debugger     748
   Enabling XPages Java Logging     755
Debugging XPages Apps on the Client Side     759
   CSJS Debuggers     760
   Debugging Dojo     762
Conclusion     765

PART V:  APPLICATION USER EXPERIENCE
Chapter 16  XPages Theming     769
It Used to Be Like That...But Not Anymore     769
Styling with Style     771
   Setting the Style Property Manually     776
   Understanding How the Style Property Is Used     777
   Computing the Style Property     778
Styling with Class     779
   Getting Something for Nothing     779
   Understanding How the styleClass Property Is Used     785
   Computing the styleClass Property     788
   Working with Extended styleClass and style Properties     790
Theming on Steroids!     794
   What Is a Theme?     794
   What Can You Do with a Theme?     795
   Understanding Theme Architecture and Inheritance     796
   Working with a Theme     804
   Theme Resources     814
   Resource Paths     824
   Theme Properties, themeId, Control Definitions, and Control Properties     832
Conclusion     848
Chapter 17  Application Layout     849
Divide and Conquer     849
Application Layout: One Easy Way     850
Application Layout: Customizing the Content Area     865
Conclusion     870
Chapter 18  Internationalization     871
Using Localization Options     872
   Localization with Resource Bundle Files     873
   Setting Localization Options     874
   Testing a Localized Application     877
   Working with Translators     878
   Merging XPage Changes     881
   Gotchas!    883
Localizing Computed Expressions and JavaScript     885
   Adding a Resource Bundle     887
   Localizing Computed Expressions     889
   Localizing Client-Side JavaScript     889
Localizing Script Libraries     890
   Server-Side Script Libraries     890
   Client-Side Script Libraries     891
International Enablement     893
Locales in XPages     894
Deprecated Locale Codes     898
Localizing Computed Fields     900
Conclusion     901

PART VI:  PERFORMANCE, SCALABILITY, AND SECURITY
Chapter 19  A First Look at Performance and Scalability     905
Golden Rules     906
Understanding the XPages Request Processing Lifecycle     908
   GET-Based Requests and the XPages Request Processing Lifecycle     909
   POST-Based Requests and the XPages Request Processing Lifecycle     910
Reducing CPU Utilization     912
   GET-Based Versus POST-Based Requests     912
   Partial Refresh     917
   Partial Execution Mode     919
Reducing Memory Utilization     923
   HTTPJVMMaxHeapSize and HTTPJVMMaxHeapSizeSet Parameters     924
   xsp.persistence.* Properties     925
   dataCache Property     926
Conclusion     928
Chapter 20 Advanced Performance Topics     931
Making Efficient XPages Requests     931
   Profiling XPages Applications     932
Introspecting XPages Requests Using a PhaseListener     949
   The Myths and Realities of the Rendered and Loaded Properties     964
   Using Partial Refresh, Partial Execution, and Dynamic Content     981
Making Scalable XPages Requests     1004
   Understanding the XPages Memory Model     1005
   Analyzing XPages Memory Usage     1008
   Establishing the Optimal Scalability Configuration     1020
Conclusion     1034
Chapter 21  Security     1035
Notes/Domino Security and XPages     1035
   Server Layer of Security     1036
   Application Layer of Security     1037
   Design Element Layer of Security     1039
   Document Layer of Security     1046
   Workstation ECL Layer of Security     1048
   Useful Resources     1049
Now Get Started     1049
   Creating the Initial Application     1049
   Implementing ACLs     1051
   Sign the XPages with Your Signature     1052
Programmability Restrictions     1053
   Sign or Run Unrestricted Methods and Operations     1054
   Sign Agents to Run on Behalf of Someone Else     1055
   Sign Agents or XPages to Run on Behalf of the Invoker     1055
   Sign Script Libraries to Run on Behalf of Someone Else     1055
Restricted Operation     1056
XPages Security Checking     1057
   NSF ClassLoader Bridge     1058
XPages Security in the Notes Client     1058
   Execution Control List (ECL)     1059
Active Content Filtering     1062
Public Access     1065
   Setting Public Access for XPages     1065
   Checking for Public Access in XPages     1066
SessionAsSigner     1067
Enabling Extended Java Code with the java.policy File     1069
Conclusion     1071

PART VII:  APPENDIXES
Appendix A  XSP Programming Reference     1075
XSP Tag Reference     1075
XSP Java Classes     1076
Notes/Domino Java API Classes     1078
XSP JavaScript Pseudo Classes     1078
Appendix B  XSP Style Class Reference     1081
XSP CSS Files     1081
XSP Style Classes     1082
IBM OneUI Themes and Documentation     1086
Appendix C  Useful XPages Sites on the Net     1087
Index     1089