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.

[back to the top of the page]

`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.

[back to the top of the page]

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.

[back to the top of the page]

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
id	Captcha id (required)
binding	`JsfCaptcha` only: managed bean's property binded with Captcha
userInputClientId	Id of (usually) text input control containing answer to Captcha challenge. Default is `captchaCodeTextBox`.
omitStylesheet	do not render code for including BotDetect Captcha stylesheet. Use with multiple Captchas in form. Default is `false`. This attribute has no effect with Facelets.
omitClientScript	do 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
codeLength	Captcha code length. Default is [4-6].
codeStyle	Whether Captcha code consists of `alpha` or `numeric` or `alphanumeric` characters. Default is `alphanumeric`.

Captcha Image Settings
imageStyles	Although 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
imageFormat	Set format of the generated image. Options are `jpg`, `png`, `gif` and `bmp`. Default is `jpg`.
imageWidth	Captcha image width in pixels
imageHeight	Captcha image height in pixels

Captcha Sound Settings
soundEnabled	Enable Captcha sound with `true` or `false` value. Disabling sound also hides sound icon of Captcha custom component. Default is `true`.

Captcha Reloading Settings
reloadEnabled	Enables or disables reloading Captcha code without validation. Also affects visibility of the reload icon of custom component. Default is `true`.

Captcha Help Link
helpLinkEnabled	Disable or enable BotDetect Captcha Help link. Has no effect in free version. Default is `true`.
helpLinkMode	Select 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.

[back to the top of the page]

Please Note

BotDetect Java Captcha Library v4.0.Beta3.7 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.