Usability - Productivity - Business - The web - Singapore & Twins

XPages Custom controls parameter definitions

One of the very cool features in XPages is the ability to create your own custom controls. While on the first look one could say "well, they are just subforms with a new name" the second look shows bigger differences:
  • Custom controls can appear more than once on a page, subforms only once (yes there was the possibility to add a subform twice if it didn't contain any fields, but that was not intended)
  • Custom controls are self aware: they "know" what is inside and what is outside
  • Custom controls have parameters. You can define parameters that the custom control will address as CompositeData.[parameterName] and the hosting pages address as [controlName].[parameterName]
When you look at the source code of a page you can clearly see the parameters you might have set for a custom control. However when you look at the source code of your custom control, you won't see any definition. Puzzled me for a moment, so I asked the master. At the very end XPages is a JFS application. In JFS a custom control has 2 files (at least): the code and the definition. XPages shields you from the complexity by allowing you to edit everything in one UI. But if you *really* want to have a look, add the Navigator window to your Domino Designer perspective and navigate to the custom control directory. Here you will find MyControl.xsp as well as MyControl.xsp-config. If you want to understand what the containing XML is all about, take a peek at a JSF tutorial

Posted by on 04 April 2009 | Comments (7) | categories: XPages


  1. posted by Jim on Monday 06 April 2009 AD:
    Nice post Stephen. However, can you expand on how to add the Navigator window from the designer?

  2. posted by Stephan H. Wissel on Tuesday 07 April 2009 AD:
    @ Jim:
    Window - Show Eclipse Views ... Others (or Alt+Shift+Q Q)
    Emoticon smile.gif stw
  3. posted by Jim on Wednesday 08 April 2009 AD:
    Thank you Stephan. I had stumbled upon it.

    The article was great. however still making sense of the JSF knowledge being useful for xpages.

    Have you found the EL expressions inside xpages beneficial? Anywhere I can find more information on what can be done with EL that might be better than server side javascript. I am familiar with EL from the JSP world using them with the scope variables.


  4. posted by Edwin on Saturday 23 May 2009 AD:
    Thanks for your help.
  5. posted by jake on Thursday 27 August 2009 AD:
    any idea where I can get my hands on a definitive guide to the XSP EL? I'm sick of trying to guess what's allowed and what's not...
  6. posted by Nick Goddard on Wednesday 24 November 2010 AD:
    Hi Stephan

    I'm struggling a bit with the final method you outlined.
    I have a custom control that allows a property to be set from a list of values.
    If I put a computed field on the custom control I can display the property using CompositeData.period as you have said. (period is the name of the property.)
    If however I drop this Custom Control onto either another Custom Control or straight onto an Xpage I struggle. I give the Custom Control and ID of periodSelector. If I then try and give a computed field a value of periodSelector.period I get a runtime error 'Reference error: 'periodSelector' not found'

    Hope you can help

  7. posted by Stephan H. Wissel on Monday 29 November 2010 AD:
    @Nick: Working eMail required! Emoticon angry.gif