Author: chris.laprun(a)jboss.com Date: 2012-02-10 09:43:12 -0500 (Fri, 10 Feb 2012) New Revision: 8419 Added: portal/trunk/docs/reference-guide/en-US/modules/Configuration/ValidatorConfiguration.xml Modified: portal/trunk/docs/reference-guide/en-US/modules/Configuration.xml portal/trunk/webui/core/src/main/java/org/exoplatform/webui/form/validator/UserConfigurableValidator.java Log: - GTNPORTAL-1673: Added documentation. Added: portal/trunk/docs/reference-guide/en-US/modules/Configuration/ValidatorConfiguration.xml =================================================================== --- portal/trunk/docs/reference-guide/en-US/modules/Configuration/ValidatorConfiguration.xml (rev 0) +++ portal/trunk/docs/reference-guide/en-US/modules/Configuration/ValidatorConfiguration.xml 2012-02-10 14:43:12 UTC (rev 8419) @@ -0,0 +1,164 @@ +<?xml version="1.0" encoding="utf-8"?> +<!DOCTYPE section PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" + "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [ + <!ENTITY % BOOK_ENTITIES SYSTEM "../../Reference_Guide.ent"> + %BOOK_ENTITIES; + ]> +<section id="sect-Reference_Guide-Validator_Configuration"> + <title>Configuration of custom data validators</title> + + <section id="sect-Reference_Guide-Validator_Configuration-Overview"> + <title>Overview</title> + + <para>&PRODUCT; includes a user-configurable validator that can be applied to + input fields of different bundled portlets. Currently, this validator is only used to configure the + validation of user name formats in the user account, user registration and group membership portlets, though + the architecture allows for configurable validation to be used in different contexts if needed. + </para> + <para> + The validator can be configured via properties in the + <filename>configuration.properties</filename> + file found in the &PRODUCT_NAME; configuration directory. By default, this directory is found at + <filename>$JBOSS_HOME/server/default/conf/gatein/</filename> + if you are using JBoss Application Server or + <filename>$TOMCAT_HOME/gatein/conf/</filename> + if you are using Tomcat. + </para> + + <para> + The architecture supports several configurations that can be activated and associated to specific instances of + the user-configurable validator when they are created and assigned to fields in portlets. We will only concern + ourselves with the currently supported use cases, which are creation/modification of a user name during + registration/modification of a user and group membership assignments. + </para> + + </section> + + <section id="sect-Reference_Guide-Validator_Configuration-Configuration"> + <title>Validator configuration</title> + + <para> + A configuration is created by adding an entry in + <filename>configuration.properties</filename> + using the + <literal>gatein.validators.</literal> + prefix followed by the name of the configuration, a period '.' and the name of the validation aspect you want + to configure. The user-configurable validator currently supports four different aspects per configuration, as + follows, where + <literal>{configuration}</literal> + refers to the configuration name: + <itemizedlist> + <listitem> + <para><literal>gatein.validators.{configuration}.length.min</literal>: minimal length of the validated + field + </para> + </listitem> + <listitem> + <para><literal>gatein.validators.{configuration}.length.max</literal>: maximal length of the validated + field + </para> + </listitem> + <listitem> + <para><literal>gatein.validators.{configuration}.regexp</literal>: regular expression to which values of + the validated field must conform + </para> + </listitem> + <listitem> + <para><literal>gatein.validators.{configuration}.format.message</literal>: information message to display + when the value of the validated field doesn't conform to the + specified regular expression + </para> + </listitem> + </itemizedlist> + </para> + + <para> + Only two configurations are currently supported by &PRODUCT_NAME;, one, named + <literal>username</literal>, to configure validation of user names when they are created/modified and the + other, named + <literal>groupmembership</literal>, + to configure validation of user names in the context of group memberships. + </para> + + <para> + For example, if you want to make sure that your users use an email address as their user name, you could use + the following configuration: + </para> + <example> + <para> + <programlisting> + # validators + gatein.validators.username.regexp=^[A-Za-z0-9._%+-]+(a)[A-Za-z0-9.-]+\.[A-za-z]{2,4}$ + gatein.validators.username.format.message=Username must be a valid email address. + </programlisting> + </para> + </example> + + <note> + <para> + If you don't change the configuration of the validator, user names will be validated as follows: + <itemizedlist> + <listitem> + <para>Length must be between 3 and 30 characters.</para> + </listitem> + <listitem> + <para>Only lowercase letters, numbers, undescores (_) and period (.) can be used.</para> + </listitem> + <listitem> + <para>No consecutive undescores (_) or period (.) can be used.</para> + </listitem> + <listitem> + <para>Must start with a letter.</para> + </listitem> + <listitem> + <para>Must end with a letter or number.</para> + </listitem> + </itemizedlist> + </para> + </note> + </section> + + <section id="sect-Reference_Guide-Validator_Developer-Configuration"> + <title>Developer information</title> + + <para> + The user-configurable validator is implemented by the + <literal>org.exoplatform.webui.form.validator.UserConfigurableValidator</literal> + class. Please refer to its documentation for more details. + </para> + + <para> + To use a specific validator configuration to validate a given field value, add the validator to the field as + follows, where + <literal>configurationName</literal> + is a + <literal>String</literal> + representing the name of the configuration to use: + <programlisting> + addValidator(UserConfigurableValidator.class, configurationName)) + </programlisting> + </para> + <para> + The validator instance can then be configured by adding the relevant information in <filename>configuration.properties</filename>, for example: + <programlisting> + # validators + gatein.validators.configurationName.length.min=5 + gatein.validators.configurationName.length.max=10 + gatein.validators.configurationName.regexp=^u\d{4,9}$ + gatein.validators.configurationName.format.message=Username must start with ''u'' and be followed by 4 to 9 digits. + </programlisting> + </para> + + <para> + Alternatively, a resource key can also be passed to the + <literal>addValidator</literal> + method to specify which localized message should be used in case a validation error occurs, for example as + follows: + <literal>configurationName</literal> + <programlisting> + addValidator(UserConfigurableValidator.class, UserConfigurableValidator.GROUPMEMBERSHIP, + UserConfigurableValidator.GROUP_MEMBERSHIP_LOCALIZATION_KEY); + </programlisting> + </para> + </section> +</section> Modified: portal/trunk/docs/reference-guide/en-US/modules/Configuration.xml =================================================================== --- portal/trunk/docs/reference-guide/en-US/modules/Configuration.xml 2012-02-09 23:49:41 UTC (rev 8418) +++ portal/trunk/docs/reference-guide/en-US/modules/Configuration.xml 2012-02-10 14:43:12 UTC (rev 8419) @@ -8,4 +8,5 @@ <xi:include href="Configuration/DatabaseConfiguration.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> <xi:include href="Configuration/EMailServiceConfiguration.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> <xi:include href="Configuration/HTTPSConfiguration.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> + <xi:include href="Configuration/ValidatorConfiguration.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> </chapter> Modified: portal/trunk/webui/core/src/main/java/org/exoplatform/webui/form/validator/UserConfigurableValidator.java =================================================================== --- portal/trunk/webui/core/src/main/java/org/exoplatform/webui/form/validator/UserConfigurableValidator.java 2012-02-09 23:49:41 UTC (rev 8418) +++ portal/trunk/webui/core/src/main/java/org/exoplatform/webui/form/validator/UserConfigurableValidator.java 2012-02-10 14:43:12 UTC (rev 8419) @@ -40,7 +40,7 @@ /** * A user-configurable validator. Several aspects of this validator can be configured via properties in the - * configuration.properties file found in the GateIn configuration directory (${gatein.conf.dir}. The validator + * configuration.properties file found in the GateIn configuration directory (${gatein.conf.dir}). The validator * supports several configurations that can be activated when a validator instance is created by passing it the name of * the configuration to be activated. A configuration is created by adding an entry in configuration.properties using * the {@link #KEY_PREFIX} prefix followed by the name of the configuration, a period '.' and the name of the