XPages Blast Paul Withers Intec Systems Ltd - By Kind Permission of Matt White and Tim Clark

XPages Blast

                Paul Withers
             Intec Systems Ltd

By Kind Permission of Matt White and Tim Clark

Matt White
●
    Lead Developer at

●
    Creators of IdeaJam™ and
    IQJam™

●
    Creator of XPages101.net

●
    Founder member of the LDC

Tim Clark
●   17 years in IBM® Lotus®
    –   Support, Sales and Channel
●   Creator of the X Cast, XPages
    podcast
    –   http://www.thexcast.net

Paul Withers
●   Senior Developer at Intec Systems Ltd
●   XPages developer since April 2009
●   Co-host of The XCast podcast
●   Blog posts on XPages and more
●   Articles on XPages on App Dev Wiki

Products In Use
●   IBM® Lotus Domino® Server 8.5.2
    –   Most of the session is based on 8.5.2, where we
        use earlier versions we’ll mention it
●   IBM® Lotus Notes® 8.5.2
●   IBM® Lotus Domino Designer® 8.5.2

Agenda
●   General Programming Tips
●   Debugging
●   UI
●   Notes Client
●   Dojo
●   Extras

Tip Grading
●   Beginner

●   Intermediate

●   Advanced

Sample Database
You can download the original database which
demonstrates a lot of tips here:

http://tinyurl.com/ls11xpagesblast

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

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

1a. Flash Scopes
●   If you want to go a bit further...

●   Look at Flash scopes
    –   Java code to pass scopes between nsf’s

http://www.bleedyellow.com/blogs/andyc/entry/
a_flash_scope_for_xpages

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

                                               repeats.xsp

3. Calling an 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)

4. Calling an Agent in 8.5.2 +
●   In 8.5.2 you can call an agent and pass an
    “in memory” document to it:
    Agent.runWithDocumentContext(NotesDocument)
●   Running SSJS is always going to be faster
    than calling an agent

4. Calling an Agent in 8.5.2 +
●   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

5. ACLs in XPages / Custom Controls

●   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

5. ACLs in XPages / Custom Controls
●   Settings can be made for:
    –   Default
    –   Anonymous
    –   Individuals
    –   Groups
    –   Roles
●   As with ACLs, in case of conflict, highest
    access wins

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

                                           clientsidreferences.xsp

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

                                         clientidreferences.xsp

8. 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

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

10. Custom Properties
●   It’s very easy to pass data around different
    custom controls
●   In the Custom Control properties go to the
    Property Definition section
●   Add a new property for each setting
    –   Can be any data type (e.g. String, Boolean,
        Document data etc)
    –   Can have a default value if the property is not
        set when the custom control is used
    –   Can choose a specific editor

10. Custom Properties
●   When you add the custom control to an
    XPage, the Custom Properties tab of the
    custom control contains the list of all of the
    different properties which you can set

11. Use 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());
                                                        java.xsp

12. 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:

                                             servlet.xsp

12. Using an XPage as a Servlet
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);
}

●   Can be used to "write" to Excel in a browser

                                               servlet.xsp

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

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

14. Configure Firewall / Skype etc
●   A lot of local firewalls block ports on the local
    machine
●   You’re basically running a local web server
    and it will want to operate on port 80, but if
    something else already has that port then
    you have problems
●   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

15. 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

16. Common Error Messages
Error Code   Most Likely Cause

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

17. 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

17. Use OpenLog
●   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);

18. 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”);

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

19. Themes and 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:

19. Themes and Global Config

  text/css
  custom.css

  InputField.RichText
  
     styleClass
     domino-richtext
xspInputFieldRichText

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!!!!!

XPages in Notes Client
●   XPiNC

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

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

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

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

Dojo
●   Not the fight place!

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

26. Dialog Box
●   If you want to interact with the server from
    inside your dialog box. You have to work
    around a “feature”.

                     “feature” = BUG           dialog.xsp

26. Dialog Box
●   Dojo moves the div outside the  tag
    so content is not posted back to server
●   Best option is to use Jeremy Hodge’s
    approach: http://tinyurl.com/xpbdialog
●   Include CSJS Library or File Resource in
    your XPage, then enable dojoParseOnLoad
    and dojoTheme

27. Dojo AJAX Request
●   Writing your own Ajax can still be useful,
    simply use the xhr API:

                                                 ajax.xsp

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

                                               chart.xsp

28. Charting
●   No flash required
    –   offers animation
    –   Tooltips
    –   Legends
    –   Gradients (with Dojo 1.5.0)

                                      chart.xsp

29. How to Show Images
●   Add Dojo resource:
    –   dojox.image.Lightbox
●   Add Stylesheet
    –   /.ibmxspres/dojoroot/dojox/image/resources/Ligh
        tbox.css

                                                  lightbox.xsp

29. How to Show Images
●   Build  tags with dojoType of
    dojox.image.Lightbox and then enable
    ParseOnLoad

                                           lightbox.xsp

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/
                                            jquery.xsp

Extras
●   Some additional tips I’m adding for you

31. Mastering XPages
●   Very well-written – not too techy!
●   Beginner, Intermediate and Advanced
●   Aimed at Domino developers and non-
    Domino developers
●   Lots of examples
●   Sold out Tuesday 10am at Lotusphere 2011
●   Just Volume 1...

32. XPages CheatSheet
●   Compiled by David Leedy, community effort
●   Lots of tips and tricks
●   Not only for beginners
●   http://xpag.es/cheatsheet
●   http://xpagescheatsheet.com
●   Version 2 already in development

33. Minimum Supported Release
●   Application Properties (Designer), XPages
    tab
●   Allows you to develop on latest Designer
    client

34. Performance: # or $
●   In SSJS:
    – $ calculates only when the page first loads
    "${javascript:@Now()}"
    – # recalculates every time the page (or relevant
      area of the page) is refreshed
    "#{javascript:@Now()}"

35. recycle()
●   All Domino objects on an XPage are
    automatically recycled after each request
●   One XPage (/myPage.xsp) = one request
●   To avoid memory leaks, in loops, use
    recycle()
var dc=database.getAllDocuments();
var doc=dc.getFirstDocument();
while (doc != null) {
   subject=document.getItemValueString("Subject");
   var tmpDoc=dc.getNextDocument();
   doc.recycle();
   doc = tmpDoc;
}

36. OAT Pivot Table
●   Dojo offers a variety of charts but not pivot
    tables
●   OAT (OpenAJAX Toolkit) has a pivot table
    example

                                                    pivot.xsp

36. OAT Pivot Table
●   Download zip file
    –   http://oat.openlinksw.com/
●   Extract oat folder to server / nsf
●   Extract oat\styles folder to server / nsf
●   Create a CSJS library for featureList variable

●   Add init() CSJS function to XPage
                                                pivot.xsp

37. Compare With...Local History
●   For newer design elements
    using Eclipse editors
    –   XPages (source tab)
    –   Custom Controls (source tab)
●   Allows you to compare
    source code with previous
    versions you created

                                       pivot.xsp

36. OAT Pivot Table
●   Download zip file
    –   http://oat.openlinksw.com/
●   Extract oat folder to server / nsf
●   Extract oat\styles folder to server / nsf
●   Create a CSJS library for featureList variable

●   Add init() CSJS function to XPage
                                                pivot.xsp

Evals, Questions & Contact Details
XPages Blast
Paul Withers
email: pwithers@intec.co.uk
twitter: @PaulSWithers
skype: PaulSWithers
blog: http://hermes.intec.co.uk/intec/blog.nsf
YouTube channel: http://www.youtube.com/intecsystems
website: http://hermes.intec.co.uk