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