Email Address Validator for XPages

by camerongregor · February 11, 2015

Update: 13 Feb 2015 – The instructions for installing into an NSF were ambiguous because I referred to ‘the <validator> section’ when there is in fact 2 different ‘<validator>’ sections (one in faces-config and one in the xsp-config’ I have made this section clearer!

I wanted to implement a custom validator for validating the input of an email address.

There are several ways this could be done, and a normal person would just use some sort of regular expression and a xp:validateConstraint validator, you could also do it in a xp:validateExpression.

But I like things to be even simpler, even if it means going through some pain to get there! I was curious to see how can I make my own custom validator that can be reused project to project, served up through a plugin.

I also wanted to be able to select it from this validators list in the control properties box.

To get me started I found a blog post from Jeremy Hodge a few years back.
Jeremy’s post was just what I needed to get started. Jeremy describes 3 methods to use a custom validator’s. I’ll let you read the full article regarding the methods because there is a bit of detail, but I decided to go with the method where you create your own class that implements javax.faces.validator.Validator and register it through the faces config file.

Create the Validator

Here is the validator I created, my EmailAddressValidator! It is pretty simple, it just has to implement the validate function. The parameter ‘Object o’ is the value that is being validated, we turn it into a string and validate it using a regex pattern.
The validate function should throw a ValidatorException if validation has failed.

package com.gregorbyte.xsp.validator;

import java.util.regex.Matcher;
import java.util.regex.Pattern;

import javax.faces.application.FacesMessage;
import javax.faces.component.UIComponent;
import javax.faces.context.FacesContext;
import javax.faces.validator.Validator;
import javax.faces.validator.ValidatorException;

import com.ibm.commons.util.StringUtil;

public class EmailAddressValidator implements Validator {

 private final static String EMAIL_PATTERN = "[^\s@]+@[^\s@]+\.[^\s@]+";
 private final static Pattern EMAIL_COMPILED_PATTERN = Pattern
   .compile(EMAIL_PATTERN);

 public void validate(FacesContext context, UIComponent component, Object o)
   throws ValidatorException {
  if (o == null || StringUtil.isEmpty((String) o)) {
   return;
  }
  String trimmed = ((String) o).trim();
  Matcher matcher = EMAIL_COMPILED_PATTERN.matcher(trimmed);
  if (!matcher.matches()) {
   FacesMessage msg = new FacesMessage("Invalid email value!",
     "Supplied Email address is not in a valid format");
   msg.setSeverity(FacesMessage.SEVERITY_ERROR);
   throw new ValidatorException(msg);
  }
 }

}

package com.gregorbyte.xsp.validator;

import java.util.regex.Matcher;

import java.util.regex.Pattern;

import javax.faces.application.FacesMessage;

import javax.faces.component.UIComponent;

import javax.faces.context.FacesContext;

import javax.faces.validator.Validator;

import javax.faces.validator.ValidatorException;

import com.ibm.commons.util.StringUtil;

public class EmailAddressValidator implements Validator {

private final static String EMAIL_PATTERN = "[^\s@]+@[^\s@]+\.[^\s@]+";

private final static Pattern EMAIL_COMPILED_PATTERN = Pattern

.compile(EMAIL_PATTERN);

public void validate(FacesContext context, UIComponent component, Object o)

throws ValidatorException {

if (o == null || StringUtil.isEmpty((String) o)) {

return;

}

String trimmed = ((String) o).trim();

Matcher matcher = EMAIL_COMPILED_PATTERN.matcher(trimmed);

if (!matcher.matches()) {

FacesMessage msg = new FacesMessage("Invalid email value!",

"Supplied Email address is not in a valid format");

msg.setSeverity(FacesMessage.SEVERITY_ERROR);

throw new ValidatorException(msg);

}

So now we can have and endless discussion about which regex pattern should be used but the one I am using basically is anythingbutwhitespace@anythingbutwhitespace.anythingbutwhitespace (any can have extra (.anythingbutwhitespace)’s as needed. You could replace it with whatever you like but this is good enough for me.

Faces Config vs Xsp Config

Before we get into the next section I just want to point out the 2 different types of configuration that we will use for configuring the validator, Faces Configuration and Xsp Configuration.
Faces Config files and Xsp-Config files both look very similar but they are not the same thing and it is important to put the correct configuration in the correct type of config file.

Faces Config is used at runtime (when your application starts up) to configure your application, Faces Config files use the extension ‘.xml‘
Xsp Config is used at design time by Domino Designer to configure Domino Designer to understand what controls / components are available and how they can be edited. Xsp Config files use the file extension ‘.xsp-config‘

Register the Validator with Faces Config

So at this point I can use the validator using the <xp:validator> tag and reference the validator using a validator id that I register with faces config.

Here is the part where I register it with faces-config

emailValidator-faces-config.xml

<?xml version="1.0" encoding="UTF-8"?>
<faces-config>
   <validator>
    <validator-id>gregorbyte.EmailAddressValidator</validator-id>
    <validator-class>com.gregorbyte.xsp.validator.EmailAddressValidator</validator-class>
   </validator>   
</faces-config>

<?xml version="1.0" encoding="UTF-8"?>

<faces-config>

<validator-id>gregorbyte.EmailAddressValidator</validator-id>

<validator-class>com.gregorbyte.xsp.validator.EmailAddressValidator</validator-class>

</validator>

</faces-config>

So now that the validator is registered through faces config with a validatorId, I can use it on an XPage with the xp:validator tag, here is an example XPage:

<?xml version="1.0" encoding="UTF-8"?>
<xp:view xmlns:xp="http://www.ibm.com/xsp/core">

 <xp:inputText id="inputText1">
  <xp:this.validators>
   <xp:validator validatorId="gregorbyte.EmailAddressValidator"></xp:validator>
  </xp:this.validators>
 </xp:inputText>

 <xp:message id="message1" for="inputText1"></xp:message>

 <xp:button value="Submit" id="button1">
  <xp:eventHandler event="onclick" submit="true"
   refreshMode="complete">
  </xp:eventHandler>
 </xp:button>

</xp:view>

<?xml version="1.0" encoding="UTF-8"?>

<xp:view xmlns:xp="http://www.ibm.com/xsp/core">

<xp:inputText id="inputText1">

<xp:this.validators>

<xp:validator validatorId="gregorbyte.EmailAddressValidator"></xp:validator>

</xp:this.validators>

</xp:inputText>

<xp:message id="message1" for="inputText1"></xp:message>

<xp:button value="Submit" id="button1">

<xp:eventHandler event="onclick" submit="true"

refreshMode="complete">

</xp:eventHandler>

</xp:button>

</xp:view>

And here is the result:

Not good enough for me! I hate typing the Validator Id

Ok great! But now I am still not satisfied, I want to be able to select the validator from the previously mentioned validators box. The secret here is to create an xsp-config file to describe this extension so that Domino Designer knows that it is available.
All the details for this can be found on the domino developer wiki under the Xpages Configuration File Format section. Here is the section for a validator

My validator doesn’t have any properties at the moment. So I’ll leave out the <property> elements and just fill out the other parts:

Register the validator via Xsp-Config

Here is my xsp-config file, notice the prefix / uri section at the top as well. The default-prefix combined with the validator-extension > tag-name will be what my validator will show up as by default. e.g. <gb:emailAddressValidator>

emailValidator.xsp-config

<?xml version="1.0" encoding="UTF-8"?>
<faces-config>

  <faces-config-extension>
    <namespace-uri>http://www.gregorbyte.com/xsp/</namespace-uri>
    <default-prefix>gb</default-prefix>
  </faces-config-extension>
  
  <validator>
    <description>Validates that input is in the format of an Email Address</description>
    <display-name>Email Address Validator</display-name>
    <validator-id>gregorbyte.EmailAddressValidator</validator-id>
    <validator-class>com.gregorbyte.xsp.validator.EmailAddressValidator</validator-class>
    <group-type-ref>com.ibm.xsp.validator.group.Validator</group-type-ref>
    <validator-extension>
      <tag-name>emailAddressValidator</tag-name>
    </validator-extension>
  </validator>
  
</faces-config>

<?xml version="1.0" encoding="UTF-8"?>

<faces-config>

<faces-config-extension>

<namespace-uri>http://www.gregorbyte.com/xsp/</namespace-uri>

<default-prefix>gb</default-prefix>

</faces-config-extension>

<description>Validates that input is in the format of an Email Address</description>

<display-name>Email Address Validator</display-name>

<validator-id>gregorbyte.EmailAddressValidator</validator-id>

<validator-class>com.gregorbyte.xsp.validator.EmailAddressValidator</validator-class>

<group-type-ref>com.ibm.xsp.validator.group.Validator</group-type-ref>

<validator-extension>

<tag-name>emailAddressValidator</tag-name>

</validator-extension>

</validator>

</faces-config>

Ok great now lets check the validators picklist:

And now here is a new example Xpage that uses the gb:emailAddressValidator tag:

<?xml version="1.0" encoding="UTF-8"?>
<xp:view xmlns:xp="http://www.ibm.com/xsp/core" xmlns:gb="http://www.gregorbyte.com/xsp/">

 <xp:label value="Using gb:emailAddressValidator" id="label1"
  for="inputText1">
 </xp:label>

 <xp:inputText id="inputText1">
  <xp:this.validators>
   <gb:emailAddressValidator></gb:emailAddressValidator>
  </xp:this.validators>
 </xp:inputText>

 <xp:message id="message1" for="inputText1"></xp:message>

 <xp:button value="Submit" id="button1">
  <xp:eventHandler event="onclick" submit="true"
   refreshMode="complete">
  </xp:eventHandler>
 </xp:button>

</xp:view>

<?xml version="1.0" encoding="UTF-8"?>

<xp:view xmlns:xp="http://www.ibm.com/xsp/core" xmlns:gb="http://www.gregorbyte.com/xsp/">

<xp:label value="Using gb:emailAddressValidator" id="label1"

for="inputText1">

</xp:label>

<xp:inputText id="inputText1">

<xp:this.validators>

<gb:emailAddressValidator></gb:emailAddressValidator>

</xp:this.validators>

</xp:inputText>

<xp:message id="message1" for="inputText1"></xp:message>

<xp:button value="Submit" id="button1">

<xp:eventHandler event="onclick" submit="true"

refreshMode="complete">

</xp:eventHandler>

</xp:button>

</xp:view>

And here is the validator in action:

Where do you put all the files? How do you deploy it?

Ok so here you have 2 options, you can just put the necessary files in the NSF that you want to use it with, or you can put it in an OSGi plugin to be installed to Domino Designer, and to any Domino Server that uses it

Putting necessary files in the same NSF

This is the easiest method, but you would need to do it for every NSF that you want to use the validator.

Put the Java class EmailAddressValidator in the Code -> Java section of the NSF
Update your faces config to include the <validator>…</validator> section of the above code sample titled ’emailValidator-faces.config.xml’. You can do this by going to ‘Application Configuration’ -> faces-config section of the NSF.
Using the ‘Package Explorer’ window in Designer, create a file called emailValidator.xsp-config in the WebContentWEB-INF directory of the NSF, and put the contents as shown in the code sample titled ’emailValidator.xsp-config’. (it can be named anything e.g. foo.xsp-config but it should have the extension .xsp-config)

Deploying via a Plugin

This is a whole article in itself! Here are the broad ‘checklist’ items (from the top of my head), it won’t be enough detail for you to do it yourself so I created the plugin and put it on github under camac/XPagesEmailValidatorPlugin. Go to the releases section and download! Let me know via github issues if any problems!

Create a plugin project
Put the emailValidator.xsp-config file somewhere
create emailValidator-faces-config.xml file somewhere
Put the EmailValidator class somewhere
Add com.ibm.commons and com.ibm.xsp.core to required bundles
Create an ‘EmailValidatorXspLibrary’ that extends AbstractXspLibrary
Configure the new EmailValidatorXspLibrary to serve up the xsp config and faces config files (via overriding getFacesConfigFiles and getXspConfigFiles methods)
Configure the other details of the library such as the plugin name, library id, and whether it is global scope (all NSF use automatically) or not global (must select to use library for each nsf)
Create a new extension that extends ‘com.ibm.commons.Extension’ with the type ‘com.ibm.xsp.Library’ and select the class ‘EmailValidatorXspLibrary’
Make sure the plugin is configured (via Manifest.MF) to export whatever packages that the EmailValidatorXspLibrary and EmailValidator are contained in (this is common oversight!)
Create a feature project that includes this plugin
Create an update site project that includes the feature
Build the Update site
Deploy to Domino Designer
Deploy to Domino Server via UpdateSite.nsf or similar!

Conclusion

So I am very happy with the result, I have my EmailValidator in a plugin, I can select the EmailValidator from the validators drop down. If I get into an argument about the best Regex to use to validate emails, and I end up losing the argument, I can update the regex in one spot, redeploy and all NSF’s on the server will use the new Regex! I can even add properties to choose between different strictness of predefined regex’s if I went down that path.

I hope you enjoyed this post and got something out of it, let me know if you have any questions!

Email Address Validator for XPages

Create the Validator

Faces Config vs Xsp Config

Register the Validator with Faces Config

Not good enough for me! I hate typing the Validator Id

Register the validator via Xsp-Config

Where do you put all the files? How do you deploy it?

Putting necessary files in the same NSF

Deploying via a Plugin

Conclusion

You may also like...

Leave a Reply Cancel reply

Categories

Archives

Meta

Email Address Validator for XPages

Create the Validator

Faces Config vs Xsp Config

Register the Validator with Faces Config

Not good enough for me! I hate typing the Validator Id

Register the validator via Xsp-Config

Where do you put all the files? How do you deploy it?

Putting necessary files in the same NSF

Deploying via a Plugin

Conclusion

You may also like...

BuildXPages Deployment Automation Tools – v1.0.0

Extended Messages Control available as an XspLibrary

Our current Deployment setup: Github + Jenkins + BuildXPages

Leave a Reply Cancel reply

Categories

Archives

Meta