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.
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
- In a declarative way by using initialization parameter
specified in the web.xml
- 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.
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.
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.
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.
No comments:
Post a Comment