Author: jaredmorgs Date: 2012-07-04 00:54:12 -0400 (Wed, 04 Jul 2012) New Revision: 8767 Added: epp/docs/branches/5.2/Installation_Guide/en-US/ValidatorConfiguration.xml Log: BZ#803152 - Added user name validator configuration information to the guide, based on community source as reference info. Added: epp/docs/branches/5.2/Installation_Guide/en-US/ValidatorConfiguration.xml =================================================================== --- epp/docs/branches/5.2/Installation_Guide/en-US/ValidatorConfiguration.xml (rev 0) +++ epp/docs/branches/5.2/Installation_Guide/en-US/ValidatorConfiguration.xml 2012-07-04 04:54:12 UTC (rev 8767) @@ -0,0 +1,141 @@ +<?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><remark>BZ#803152 </remark>User name mask configuration</title> + <para>A user-configurable validator can be applied to +user name fields in the user account, user registration, and group membership portlets. </para> + <para>The validator enforces the validation mask for user name formats in these portlets, which results in consistent and valid user names. </para> + <para>The architecture does allow for configurable validation to be used in different contexts if needed, however this feature is not officially supported in Enterprise Portal Platform. + </para> + <section id="sect-Reference_Guide-Validator_Configuration-Configuration"> + <title>Validator configuration</title> + <para> The validator is configured through properties set in the <filename><replaceable>EPP_HOME</replaceable>/server/<replaceable>PROFILE</replaceable>/conf/gatein/configuration.properties</filename> file. + </para> + <important> + <para> + Some components used in the portal depend on user names being all lowercase. Consider only accepting lowercase user names to maintain cross-compatibility. + </para> + </important> + <para>The default validator behavior ensures a user name meets the following requirements: + + </para> + <itemizedlist> + <listitem> + <para>Length must be between 3 and 30 characters.</para> + </listitem> + <listitem> + <para>Must start with a letter.</para> + </listitem> + <listitem> + <para>Must end with a letter or number.</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> + </itemizedlist> + <para>To alter this default behavior, the user-configurable validator supports four aspects: + </para> + <itemizedlist> + <listitem> + <para><parameter>gatein.validators.<replaceable>[username|groupmembership]</replaceable>.length.min</parameter> + + </para> + <para>Mininum length of the validated + field. </para> + </listitem> + <listitem> + <para><parameter>gatein.validators.<replaceable>[username|groupmembership]</replaceable>.length.max</parameter></para> + <para>Maximum length of the validated + field. + </para> + </listitem> + <listitem> + <para><parameter>gatein.validators.<replaceable>[username|groupmembership]</replaceable>.regexp</parameter></para> + <para>Regular expression to which values of + the validated field must conform. </para> + </listitem> + <listitem> + <para><parameter>gatein.validators.<replaceable>[username|groupmembership]</replaceable>.format.message</parameter> </para> + <para>Information message that displays + when the value of the validated field does not conform to the + specified regular expression. </para> + </listitem> + </itemizedlist> + <para>Within each aspect, + <literal> + <replaceable>[username|groupmembership]</replaceable> + </literal> + refers to the configuration type. </para> + <para>The + <literal>username</literal> configuration type sets how user names are validated when created by the user registration portlet, or modified by the user account portlet. </para> + <para>The + <literal>groupmembership</literal> configuration type sets how user names are validated when created or modified by the group membership portlet. + </para> + <example> + <title>Email as user name mask</title> + <para>Use the following configuration to ensure users configure an email address as their user name. </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> + </example> + <example> + <title>Letter and number combination</title> + <para>Use the following configuration to ensure users configure a user name starting with the letter &quot;u&quot;, followed by four to nine digits. </para> + <programlisting># validators + +gatein.validators.username.length.min=5 + +gatein.validators.username.length.max=10 + +gatein.validators.username.regexp=^u\d{4,9}$ + +gatein.validators.username.format.message=Username must start with &apos;&apos;u&apos;&apos; and be followed by 4 to 9 digits. </programlisting> + </example> + </section> +<!--BZ#803152 - Commented out the Developer info, because it contains unsupported configuration. Did steal the extra code sample and added that into the main section as a user example though. --><!--<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 &apos;&apos;u&apos;&apos; 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>