Skip to main content

Custom Control Design Definition Tricks

I think by now many people are aware of the Design Definition you can set when creating a custom control. Here is a quick refresher if you are not. A design definition simply replaces what you see when you drop the control on an xpage. By default, it shows whatever is in your control, but this property can be used to replace that with:
  • documentation about how to use the control, for example what custom properties mean or other requirements such as using a data source named "document1"
  • A visual short-hand, for example a control could just show <Header Control> instead of everything inside. This is great for minimizing clutter in the designer and it can also speed up the loading/rendering of the xpage in designer.
  • An interactive tool that allows you to drop additional controls inside
 There are a couple of advanced features that can be tricky to figure out unless someone shows you. Here is one:


Setting label text dynamically

If you drop a label and an edit box into a custom control, you can set what they look like through the design definition. For example you could display it this way:

<?xml version="1.0" encoding="UTF-8"?>
<xp:view xmlns:xp="http://www.ibm.com/xsp/core">
    <xp:table>
      <xp:tr>
        <xp:td>fieldLabel</xp:td>
    <xp:td>
          <xp:inputText
            value="dataSource"
          >
          </xp:inputText>
        </xp:td>
      </xp:tr>
    </xp:table>
</xp:view>
The problem with doing it this way is once you drop a few of these controls on your document, you can't tell one from another without looking at the custom properties of each. There is another way of doing this using JSP expressions. By changing the definition a little bit, we can dynamically set the display text of the custom control so that we can identify one instance of a control from another:

<?xml version="1.0" encoding="UTF-8"?>
<xp:view xmlns:xp="http://www.ibm.com/xsp/core">
    <xp:table>
      <xp:tr>
        <xp:td>
          <%=this.labelText || 'Label'%>
        </xp:td>
    <xp:td>
          <xp:inputText
            value="<%=this.bindTo || 'DataSource'%>"
          >
          </xp:inputText>
        </xp:td>
      </xp:tr>
    </xp:table>
</xp:view>
I'd like to find a way to edit these properties directly on the custom control at some point, just to make this a little easier and more fool-proof, but for now I'm satisfied with just being able to do this at all.

One caveat I have found is that this doesn't seem to work when you are using property groups. When I tried to do something like value="<%=this.input1.bindTo || 'DataSource'%>" designer kept complaining that input1 is null.

Comments

Popular posts from this blog

Pass data between XPages and existing LS scripts

I'm working on modernizing a fairly hefty application with a lot of existing script libraries which we want to leverage within the XPages environment. Here is a technique that works very well. First, create an in-memory document in SSJS. We can set any input values needed for the back end. Then we pass that document to a LS Agent which can work it's magic using the values set in SSJS and use the same document to return values back to the XPage. Here is how it works in detail:

Fixing FontAwesome for Windows 10

I ran into an issue with FontAwesome a few months back, where a NoCache header was being injected at the server and FA was broken for any partial refresh. I convinced the admin to reverse that setting and all was well until last week... We had some users who were not getting any icons to appear. Ever. We tracked it down to a new Windows 10 setting for IE11 which disallows untrusted fonts. Since we do not set security protocols for our users, and there is no chance of ever convincing those admins to change this policy that they explicitly turned on, I had to find a new solution. I did some searching and it turned out to not be too difficult. First, here is the original implementation. The theme: <control> <name>Icon.Search</name> <property mode="override"> <name>tagName</name> <value>i</value> </property> <property mode="concat"> <name>styleClass</name> <value>fa fa-search...

XPages Application Framework (Part 2 of ?)

In my last post, I offered a very rough overview of the framework I've been building and adapting. Full credit where it's due, I've been borrowing and adapting from Jesse Gallagher's XPages Scaffolding - an awesome project that I've learned a great deal dissecting. This is one of those projects that, if you make the effort to truly understand it, will give you entirely new tools and approaches for problems. As usual, I've learned the most changin g things and breaking them. My project differ s f rom Jesse's mostly in that it supports 8.5.3 and doesn't require any relaxed security permissions - bec ause I'm on 8.5.3 and because the admins h ere will not grant any relaxed permissions.