Tuesday, 21 December 2010

Required field indication with ExtVal - Part 2

Introduction

The previous time, there was an explanation how you could have some
indication on the input field itself when it is required. As said then, a
custom renderer that changes the appearance of the label which is in front
of the required input field is no longer possible. During the rendering of
the label, the input component has not yet set the required attribute. So
you need another solution if you need that kind of requirement in your
application.


Into ExtVal

The required label add-on is developed to have that functionality.
It does his trick by implementing the RendererInterceptor
interface. The RendererInterceptor is probably the most important concept
in ExtVal. It defines the extensions points that are added to the renderer
methods. It allows that some logic is performed before and after the
default decode and encode methods is executed. The new class intercepts
the rendering for the labels and performs 2 main tasks. When the 'for'
attribute of the label defines an input component, the initialization of
the input component is already performed. The value of the required
attribute can then be used to have an indication on the label.

Configuration

The configuration of the add-on is very easy. By default, if you
specify the add-on as dependency within Maven or another build management
tool, the asterisk character is added in front of the label and the CSS
class ExtValRequiredLabel is also added to the label. And
to make it easy for the developer, the indication is implemented in a
generic way. It can be customized by some configuration parameters. The
character(s) and the location (before or after the label) can be specified
and also the additional CSS class which is placed on the label to show it
for instance in a red text color.

The configuration can be done in 2 ways

  1. In a declarative way by using initialization parameter
    specified in the web.xml
  2. In a type safe way using a Java API.

Here are the names of the initialization parameters that
can be specified within the web.xml file and the explanation of what can
be achieved by the parameter.

  • org.os890.extval.addon.label.REQUIRED_MARKER

    This parameter specifies the marker that needs to be added to
    the label when the field is required. Some examples could be 'X ' or
    '* '. Remark the space after the character, it is intended. When the
    characters are placed in front of the label, the default placing,
    see also the next parameter, we, mostly, like some additional
    character between the marker and the label. It is also allowed to
    specify some HTML marker here, something like <span
    class="red">* </span> is also
    allowed. See the remark further on if you will use HTML.

  • org.os890.extval.addon.label.PLACE_MARKER

    Defines the location of the marker characters defined by the
    previous parameter. The supported values are BEFORE, AFTER and
    BEFORE_COLON, and for the Type safe JAVA configuration, the values
    are defines in the enum MarkerPlace. The first 2
    values are quite obvious, the third one might need some explanation.
    It is a common way to have label with a colon at the end, like
    'label : ' before the inputfield. By just specifying AFTER as the
    location, the character, like an asterisk, is shown after the colon,
    like this 'label : *'. With that option BEFORE_COLON, it places the
    marker before the colon so that we have a result like 'label * :'.
    In case there is no colon found in the text, it is just placed after
    the label.

  • org.os890.extval.addon.label.REQUIRED_STYLE_CLASS

    Another common way of indicating a required field is by giving
    the label a certain CSS style, like the label is shown in a red text
    color. By default, the style class
    ExtValRequiredLabel is added to the label when the
    field is required. But this style class name can be customized by
    using this parameter

For the custom implementation, you can only use the Type safe Java
API configuration option. It is made for those cases where you have the
requirement to indicate a required field which can't be met by using the
configuration parameters specified above. One needs to implement their own
logic in the configureLabel method of the
RequiredLabelInitializer interface. The classname can
then specified only through the Java API as shown in the example in the
next section.

When you use HTML in the marker, you need an adjusted label renderer
if you are using Myfaces 1.2.9 or lower. The renderer fully qualified
class name is
org.os890.extval.pv.requiredlabel.renderer.EscapeHtmlLabelRenderer which
you can use in the faces configuration file. The HTML must also be
escaped, otherwise the characters aren't correctly read by the application
servers.

Typesafe configuration using a Java API

The type safe Java API is using a newly introduced concept of ExtVal
in version 4. The configuration options of the framework, or an add-on as
we have it here, is defined in an abstract class. For the required label
add-on the class is named RequiredLabelAddonConfiguration
and the default implementation, that reads from the web.xml file, is
called DefaultRequiredLabelAddonConfiguration. By
extending the default implementation and specifying the class in an
startup listener, we can configure the add-on in a type safe way.

public class JavaLabelAddonConfiguration extends DefaultRequiredLabelAddonConfiguration
{
    @Override
    public RequiredLabelInitializer getRequiredLabelInitializer()
    {
        return new StupidRequiredLabelInitializer();
    }

}

public class RequiredLabelExampleStartupListener extends AbstractStartupListener
{

    @Override
    protected void init()
    {
        RequiredLabelAddonConfiguration.use(new JavaLabelAddonConfiguration(), true);

    }
}

This startup listener must be defined as JSF phaseListener in
the Faces configuration file. The example above, defines a custom
implementation of the RequiredLabelInitializer. But the class
DefaultRequiredLabelAddonConfiguration has other methods where you can
specify the other configuration options like the required marker, the
position and the CSS class.

Versions

There are 2 versions created of the add-on. Since the
property-validation and the bean-validation modules are quite different in
their internal functionality, there is a version of the add-on compatible
with each of these 2 validation modules. So when your project has the
property validation module as one of his dependencies, you can take the
add-on which can be found in the directory property_validation_module of
the mercurial repository (http://bitbucket.org/os890/extval-addons). In
the bean_validation_module directory, you can find a version which is
compatible with the bean validation module.

The add-on is compiled against the 1.2.4 version of ExtVal. But it
can be used with any version of JSF and ExtVal, so also with ExtVal 1.1.4
and 2.0.4. There is an example made with Myfaces 2.0. and ExtVal 2.0.4
which can also be found in the mercurial repository.

Conclusion

With the required label add-on you can configure almost every
possible way of having an indication of the required field on the label
that is in front of it. And, if you have some very exotic requirement, you
can always write your own implementation of the interface
RequiredLabelInitializer. The usage of your
implementation can then be specified through the type safe Java API
configuration option which is made available from the latest version 4 of
ExtVal.