omnifaces

 - 

Available since OmniFaces 1.0

The omnifaces.RequiredCheckboxValidator is intented to solve a peculiar problem with required="true" attribute of UISelectBoolean components like <h:selectBooleanCheckbox>. If you want to require the user to tick the desired checkbox, you would expect that setting required="true" is sufficient. But it is not, the validation wil always pass.

As for every other UIInput component the default required="true" validator would only check if the value is actually filled and been sent to the server side, i.e. the value is not null nor empty. In case of a <h:selectBooleanCheckbox>, which accepts Boolean or boolean properties only, EL will coerce the unchecked value to Boolean.FALSE during apply request values phase right before validations phase. This value is not null nor empty! Thus, the required attribute of the <h:selectBooleanCheckbox> is fairly pointless. It would always pass the validation and thus never display the desired required message in case of an unticked checkbox.

Usage

This validator is available by validator ID omnifaces.RequiredCheckboxValidator. Just specify it as <f:validator> of the boolean selection component:

<h:selectBooleanCheckbox id="agree" value="#{bean.agree}" requiredMessage="You must agree!">
    <f:validator validatorId="omnifaces.RequiredCheckboxValidator" />
</h:selectBooleanCheckbox>

Since OmniFaces 4.5 it's also available by <o:requiredCheckboxValidator> tag.

<h:selectBooleanCheckbox id="agree" value="#{bean.agree}" requiredMessage="You must agree!">
    <o:requiredCheckboxValidator" />
</h:selectBooleanCheckbox>

The validator will use the message as specified in requiredMessage. If it's absent, then it will use the default required message as specified in custom <message-bundle> in faces-config.xml. If it's absent, then it will default to

{0}: a tick is required"
Demo

Form without RequiredCheckboxValidator

Form with RequiredCheckboxValidator
Demo source code
<h3>Form without <code>RequiredCheckboxValidator</code></h3>
<h:form>
    <h:panelGrid columns="3">
        <h:outputLabel for="agree" value="Do you agree?" />
        <h:selectBooleanCheckbox id="agree" required="true" requiredMessage="You must agree!" />
        <h:message for="agree" />

        <h:panelGroup />
        <h:commandButton value="Submit">
            <f:ajax execute="@form" render="@form" />
        </h:commandButton>
        <h:panelGroup>
            <h:outputText value="OK!" rendered="#{facesContext.postback and not facesContext.validationFailed}" />
        </h:panelGroup>
    </h:panelGrid>
</h:form>

<hr />

<h3>Form with <code>RequiredCheckboxValidator</code></h3>
<h:form>
    <h:panelGrid columns="3">
        <h:outputLabel for="agree" value="Do you agree?" />
        <h:selectBooleanCheckbox id="agree" requiredMessage="You must agree!">
            <f:validator validatorId="omnifaces.RequiredCheckboxValidator" />
        </h:selectBooleanCheckbox>
        <h:message for="agree" />

        <h:panelGroup />
        <h:commandButton value="Submit">
            <f:ajax execute="@form" render="@form" />
        </h:commandButton>
        <h:panelGroup>
            <h:outputText value="OK!" rendered="#{facesContext.postback and not facesContext.validationFailed}" />
        </h:panelGroup>
    </h:panelGrid>
</h:form>
Documentation & Sources

API documentation

Java source code