Thursday, January 28, 2010

XPages: Using the powerful Design Definition in custom controls

I've recently started using the Design Definition in my custom controls to save space on the XPages they are included in.

When I first encountered this new (since Domino 8.5.1) feature, I believed it was a static feature. It turns out it's highly dynamic, and quite powerful.

Immediately, when I read the "Providing illustration for your XPage custom controls" article from the Lotus Notes and Domino Application Development wiki, I thought of JSP. What reminded me of JSP was this little snippet:
<%=this.viewName %>

I've only tested if/else statements, as I know very little JSP/haven't had the need for anything else. If you know JSP/have a blog, please test out this feature, and share your findings.

Included in todays demoapp, there is a custom control that lets you open up a "remote" Dojo dialog (dijit.Dialog). The developer can choose between using a link and a button as the "launcher". This is controlled by the property definition in the custom control.

The design definition for the control:
<?xml version="1.0" encoding="UTF-8"?>
<xp:view xmlns:xp="">
<% if(this.activationControl==='link' ){ %>
<a href="#"><%=this.showDialogLabel || 'DojoDialogLink' %></a>
<% } else { %>
<%if( this.btnImage ){%><img src="<%=this.btnImage %>" /><%}%>
<%=this.showDialogLabel || 'DojoDialogButton' %></button><%

this is (amongst other things?) the compositeData-object that contains all the properties from the property definition. this.btnImage in the design definition is the same as compositeData.btnImage in the custom control.

If you set the custom control to use a link to launch the dialog, the custom control shows up as a link in the XPage it's included in. If you change that to a button, immediately the representation of the custom control changes into a button. If you haven't typed a label for the link/button, it has the label DojoDialogLink/DojoDialogButton, depending of the action type you've chosen. When you type in a label, the link text/button label changes correspondingly. If you've chosen an image for the button, the image shows up in the XPage.

Flash video of the design definition in action:

>> Small demoapp

Share and enjoy!