Tip of the Iceberg

Category xpages
Last week, Jake called attention to the usability flaw in web forms that specify a default value for fields but clear that value on focus without checking first to see if the field's value has since been changed from the default. He included a code example demonstrating a way to perform such a check, ensuring that a user's input will not be programmatically deleted if they later return to the same field.

A couple readers proposed an alternate approach: using the "placeholder" attribute as described in the HTML5 specification. Browsers that support this attribute display the value of the attribute within the field when the field has no value - even if it used to - but at a lower opacity. Hence, the user is given a visual indication that this text provides a hint for what to enter in the field, not a value that is already assigned to the field. In other words, the behavior is quite similar to the way the Lotus Notes client renders the "Field Hint" property for a field on a Form element: the only significant difference is that, upon exiting a Notes field, the hint does not reappear, even if the field is still (or again) empty; as previously mentioned, browsers that support the placeholder attribute will again display its value when the focus leaves the field if that field has no value. Browsers that do not support this attribute simply ignore it, so users of those browsers will not see the hint, but will also not encounter errors. This is a great example of "progressive enhancement": users of older or less standards-compliant browsers can still use all of the site's functionality, but as those users upgrade / replace their browser, they have a richer experience without any additional effort on your part.

Yesterday, Tommy posted a demonstration of using hidden inputs to glean the values of "passthru" input tags, which allows him to specify HTML5 attributes on the passthru tags. He created a custom control that allows this technique to be reusable.

The remainder of this post will demonstrate how to create an extension to the native Edit Box component to add support for HTML5 attributes like placeholder.

The good news, for those of you who are currently unable to upgrade to 8.5.2 or to install component extension libraries (or both), is that this technique requires neither: this extension can be implemented in 8.5.1 (in all likelihood, even 8.5.0), and the instructions that follow assume you will be implementing them in "single-NSF" mode. If you'd rather deploy such an extension as part of a component library, IBM has included documentation for how to bundle the files you're about to see into such a library in the Extension Library project on OpenNTF.

Step 1: defining the component

Every extension component is defined by, at a minimum, one Java class that specifies the properties and methods of the component. Let's take a look at such a class:



As you can see, our class declaration states that we're extending XspInputText. This is the Java class associated with the native Edit Box component. Hence, by extending that class, we're declaring that we want something that inherits all of its functionality but will have certain additional characteristics of its own.

In this example, we're really just looking to add one additional attribute: placeholder. So we declare a private String to store it, and a "getter" and "setter" method to, respectively, retrieve and change the value for the attribute. The syntax of the getter may look a bit odd, but this follows the exact syntax IBM uses whenever they define a getter for a component attribute. What this syntax essentially does is allows the attribute to support both dynamic and static values; in the case of placeholder, this will allow the attribute to be evaluated correctly whether we use EL or just type in a value.

In addition to providing a getter and setter, we want the value of the attribute to be maintained across requests (for example, if a partial refresh event targets this component or one that contains it). We do this by overriding the saveState and restoreState methods of the parent class. In saveState, we create a generic Object array, call the saveState method as it is defined in the parent class and store the result in the first index of the array, and then store any additional properties we want to maintain in additional indices... since we're only adding one additional property, we only need one additional index. In restoreState, we reverse the process: we pass the first index of the restored array to the parent method, then retrieve the placeholder from the second index. In deep component hierarchies, then, the serialized version of each component becomes a nested array of arrays, which seems complicated to maintain, except that in each class we only have to worry about the properties defined at that level. This state serialization concept is what allows the XPage runtime (as of 8.5.2) flexibility regarding the performance priorities for each application: speed, scalability, or a "happy medium".

One last note about the component class: strictly speaking, the rendererType attribute should be handled in precisely the same way as the placeholder (i.e. private String, getter/setter, and state management), but as an explanation of providing support for multiple renderers is best left for another day, this example simply hardcodes a single renderer ID.

Step 2: defining a renderer

Now that we've defined what this component is, we'll define what it should look like.



This bit is even easier than defining the component itself. As before, there's already a class that does almost everything we want, so we just extend it to add the new functionality. In this case, we're extending InputTextRenderer, which already includes all of the logic for turning a standard Edit Box into HTML: writing out attributes, binding events, and so forth. Hence, all we need to do is override the writeTagHtmlAttributes method. We start by calling the parent method, which writes all of the standard attributes. Then we determine whether the placeholder attribute has a value and, if it does, write that value to the tag being rendered. That's it.

Step 3: telling Designer the component exists

Finally, we need to alert Designer (and the XPage runtime) to the existence of our new control. This is done by creating one XML file and modifying another.

Create a file with a .xsp-config extension. The actual filename is arbitrary; as long as the file extension is correct, the filename does not matter. Furthermore, you can theoretically place this file anywhere within the NSF folder structure and Designer will find it. However, I recommend placing these files in /WebContent/WEB-INF. Since the file we'll soon be modifying is already there, it just makes things easier to keep track of.

Since I'm bumping up against the 32KB summary limit, I've posted the example xsp-config file as a separate page. The namespace URI and prefix are, again, arbitrary, as long as the relationship between the two is maintained. For instance, you could actually add your own components to the xp or xc namespace, as long as you specify the same URI that IBM does, but please, please don't. That would ultimately just cause confusion. In this example, I'm defining "html5" as the prefix, so I thought it fitting to use the URL of the HTML5 spec as the namespace URI. Hopefully, most of the remaining contents of the file are self-explanatory, but I specifically want to call attention to the base-component-type tag. This tells Designer that this component supports all of the properties an Edit Box supports, in addition to the new property it defines. There are all manner of additional items that can be defined in this file, but, again... another day.

Once we've saved this file, Designer immediately knows this component exists, so we can add one to our page; once we do, and select it, the All Properties pane will allow us to set a value for the placeholder attribute. In the Source pane, it will look a little something like this:



Finally, open up the faces-config.xml file in /WebContent/WEB-INF, and add the following lines:



This associates any component with the rendererType we hardcoded in Step 1 with the renderer we defined in Step 2. Whenever the runtime needs to render the component we've defined, it now knows to use our renderer.

So that's all there is to it. I realize this probably seems like a lot of work just to get an XPage to add a few additional characters to the HTML output, but once you've gotten used to defining components, creating a new one only takes a few minutes. Furthermore, when you want to add properties to a component you've already defined, all you have to do is tweak the corresponding files. For instance, you could take this example component and add support for additional attributes with just a few lines of code. Given the alternatives, such as waiting for IBM to add the features you want in a subsequent release, or simply settling for what has already shipped, it's well worth the extra effort... especially when you start writing components that don't even exist out of the box.