How To Configure BotDetect Java CAPTCHA Options

BotDetect Java Captcha allows detailed customization of many Captcha properties either via web.xml config file or by setting Captcha object instance properties.

Besides, BotDetect Captcha custom tags (Captcha and JsfCaptcha) has equivalent attributes to allow Captcha customization through presentation layer code (.jsp and .xhtml pages).

Binding JsfCaptcha tag with managed bean's property allows BotDetect Captcha customization within JavaServer Faces managed beans.

web.xml

To customize BotDetect Captcha for whole application you set attribute as <context-param> in web.xml config file. Since these params are global for application you have to prepend a prefix "LBD_" to attribute name.

Example

<context-param>
    <param-name>LBD_imageStyles</param-name>
    <param-value>ancientMosaic, overlap2</param-value>
</context-param>

Values override default Captcha values.

Captcha Object Instance Properties

After creating a new Captcha object you can set it's properties using appropriate setter method. These methods are named after attribute names with added prefix set.

Example

Captcha captcha = Captcha.load(request, "exampleCaptcha");
captcha.setCodeLength(8);
captcha.setImageFormat(ImageFormat.GIF);
captcha.renderCaptchaMarkup(pageContext.getServletContext(), 
    pageContext.getOut());

Instance property settings override application-wide values specified in web.xml file.

Custom Tags

When adding BotDetect Captcha custom tag to your web form you can set various attributes.

Example

<botDetect:captcha id="exampleCaptcha" imageHeight="75" 
    imageWidth="300"
    imageStyles="ancientMosaic, overlap2"
    reloadEnabled="false"
    binding="#{exampleBean.captcha}"/>

Values override values specified in web.xml file.

JavaServer Faces Managed Bean

When application logic requires changing Captcha attributes during execution you can set values within managed bean using JsfCaptcha methods. Methods used to set attribute values are named after attribute names with prefix set.

Example

@ManagedBean
@RequestScoped
public class CaptchaBean {

    private JsfCaptcha captcha;  
    public CaptchaBean() {
        captcha = new JsfCaptcha();
        captcha.setCodeLength(4);
        captcha.setImageStyles("ancientMosaic, overlap2");
        // to set single image style you can use enum value:
        // captcha.setImageStyle(ImageStyle.Darts);
        captcha.setSoundEnabled(false);
    }
}

Values override values specified in custom tag's attributes.

BotDetect Captcha Custom Tags

To use BotDetect Captcha custom Tags on your JavaServer Page put the following taglib directive at the top of your page:

<%@taglib prefix="botDetect" uri="botDetect"%>

Facelets requires adding a xmlns:botDetect="botDetectFacelets" attribute to opening <html> tag on the page instead of declaring a taglib.

Captcha and JsfCaptcha

Render BotDetect Captcha Html Markup code.

While Captcha Tag is intended for general use, JsfCaptcha Tag is for use with JavaServer Faces so it has additional binding attribute and added functionality for positioning BotDetect stylesheet and clientScript within the page when used with Facelets.

Attributes

Captcha
idCaptcha id (required)
bindingJsfCaptcha only: managed bean's property binded with Captcha
userInputClientIdId of (usually) text input control containing answer to Captcha challenge. Default is captchaCodeTextBox.
omitStylesheetdo not render code for including BotDetect Captcha stylesheet. Use with multiple Captchas in form. Default is false. This attribute has no effect with Facelets.
omitClientScriptdo not render code for including BotDetect Captcha Client Script. Use with multiple Captchas in form. Default is false. This attribute has no effect with Facelets.
Captcha Code Settings
codeLengthCaptcha code length. Default is [4-6].
codeStyleWhether Captcha code consists of alpha or numeric or alphanumeric characters. Default is alphanumeric.
 
Captcha Image Settings
imageStylesAlthough is the best to randomize the BotDetect Captcha image style using all possible styles, you can specify which styles will be randomly used. Styles should be delimited with comma. Misspelled or unknown styles will be ignored. Default is all styles
imageFormatSet format of the generated image. Options are jpg, png, gif and bmp. Default is jpg.
imageWidthCaptcha image width in pixels
imageHeightCaptcha image height in pixels
 
Captcha Sound Settings
soundEnabledEnable Captcha sound with true or false value. Disabling sound also hides sound icon of Captcha custom component. Default is true.
 
Captcha Reloading Settings
reloadEnabledEnables or disables reloading Captcha code without validation. Also affects visibility of the reload icon of custom component. Default is true.
 
Captcha Help Link
helpLinkEnabledDisable or enable BotDetect Captcha Help link. Has no effect in free version. Default is true.
helpLinkModeSelect whether help link will be Captcha image (image) or text under Captcha image (text). Default is text.

stylesheet

Renders Html markup for stylesheet used by BotDetect Captcha markup. Use with omitStylesheet attribute.

clientScript

Renders Html markup for BotDetect Captcha Client script. If omitClientScript attribute is set to true client script must be included before any Captcha custom Tag.

Please Note

BotDetect Java Captcha Library v4.0.Beta3 is an in-progress port of BotDetect 4 Captcha, and we need you to guide our efforts towards a polished product. Please let us know if you encounter any bugs, implementation issues, or a usage scenario you would like to discuss.