Mastering XPages: A Step-by-Step Guide to XPages Application Development and the XSP Language

IBM's Best-Selling Guide to XPages Development–Now Updated and Expanded for Lotus Notes/Domino 9.0.1 XPages instantly revolutionized Notes/Domino application development, and the newest versions deliver unprecedented performance and flexibility. Now, the popular insider's guide to XPages development has been updated and expanded to reflect all these improvements, through IBM Notes/Domino 9.0.1 and beyond. Three key members of the IBM XPages team have brought together comprehensive knowledge for delivering outstanding solutions. They have added several hundred pages of new content, including four new chapters. Drawing on their unsurpassed experience, they present new tips, samples, and best practices reflecting the platform's growing maturity. Writing for both XPages newcomers and experts, they cover the entire project lifecycle, including problem debugging, performance optimization, and application scalability. This second edition of Mastering XPages fully addresses enhancements to the XPages data sources for Domino views and documents; the latest XPages mobile library; the new Domino Designer Server-Side JavaScript debugger; and improvements to integrated technologies such as Dojo and CKEditor. Nearly every chapter contains at least one downloadable sample application, offering extensive hands-on practice. This guide concludes with complete references to XSP tags, relevant Java/JavaScript classes, and XSP style classes. Coverage includes * Understanding XPages' development paradigm, tooling, runtime framework, and application architecture * Configuring Domino Designer and integrating XPages Extension Library * Constructing application logic and using data binding controls * Reading/writing Notes documents: from use cases to design properties * Using Views, including examples of accessing calendars via REST * Making the most of Notes/Domino 9.0's new DataView control * Coding: from the basics to fully customized behavior * Advanced scripting: AJAX, Dojo, @Functions, managed beans, and more * Extending the Rich Text Editor's functionality * Building and consuming new controls with Extensibility APIs * Taking web applications offline in the Notes client * Building mobile apps: controls, design patterns, and best practices * Debugging Server-Side JavaScript with Domino Designer 9.0 * Creating apps that look and work great–for local and global audiences * Systematically optimizing performance and scalability * Protecting data and users: leveraging Domino and Notes security models

Table of Contents:
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