HOWTO: Add Field Validation - JSF UI

When you create your own document type, you may need to impose a structure for some fields (phone number, zip code, ...) to your user. The Nuxeo Layout system is based on JSF that implements the notion of validator. Here we will explain how to do that with Nuxeo Studio and Nuxeo IDE.

For a pure JSF fragment, see How to validate fields of document at creation or update.

Let's take the example of the validation of a phone number field in creation and edit mode.

Before You Start

Make sure that the Nuxeo JSF UI target package is checked in your project's Application Definition to get all the needed features in Nuxeo Studio.

Nuxeo Studio: Parametrization

1. Go to the Creation Layout tab on your document type definition in Nuxeo Studio.
2. Click on the icon  of the field widget you want to add a validation to.
3. Expand the Custom Properties Configuration section.

4. Add a property named validator with value: #{myValidatorBean.validatePhoneNumber}.

   The bean is identified by the @Name annotation of your bean class, not the actual class name.

Here we ask JSF to ask the myValidatorBean SEAM Component to execute the method validatePhoneNumber upon the creation form validation.

If you want to expose the same field with the same validator on the Edit layout, just repeat that or copy directly the layout.

Nuxeo IDE: Seam Component Creation

Nuxeo IDE provides an easy way to create you own Seam Component:

1. First you need to install Nuxeo IDE and a new plugin project. See the Getting Started with Nuxeo IDE page.
2. In Nuxeo IDE, create your Seam Component.
3. Call this component myValidatorBean.

4. Add the method that will call JSF to validate your field:

   public void validatePhoneNumber(FacesContext context, UIComponent component, Object value)
   
   

   This method will manage the validation of the field.

   • The context will be used to send message into the client (kind of error);
   • The component parameter represents the field you are validating;
   • The value is the value filled by the user into the given field.

Nuxeo IDE: Validation Method Implementation

Here, we show a quick implementation of a JSF validation method. JSF is a huge framework, so if you want to learn more, check the JSF documentation.

According the type of your widget the type of the value object will be:

• for text and textArea widgets, the type is String;
• for date widget, the type is java.util.Date;
• etc...

So, in the validation method, you just need to do what is required to validate the value, ex:

            String phoneNumber = (String) value;
            if (... valid the string here...) {
                 // do nothing as the given string is well-formed
                 return;
            } else {
                // display an error in the input form
                FacesMessage message = new FacesMessage(
                    FacesMessage.SEVERITY_ERROR, "Bad boy, you fill a wrong number format!",
                    null);
                throw new ValidatorException(message);
            }

Exception will be catched by JSF and JSF will present again the form to the user. The error message will be exposed next to the field.

You can internationalize your message by replacing the given String by:

ComponentUtils.translate(context, "label.error.bad.phone.format")