API Manual

TCaptcha displays a CAPTCHA that can be used to determine if the input is entered by a real user instead of some program. TCaptcha displays a token (a string consisting of alphanumeric characters) as an image and the user is expected to repeat the token in a text box. The token image is generated in a way such that it can be recognized by a human being, but not a program.

To use TCaptcha, you must enable the PHP GD2 extension with TrueType font support. Unlike other CAPTCHA scripts, TCaptcha does not need session or cookie.

The token generated by TCaptcha can be configured in several ways. To specify the length of characters in the token, set MinTokenLength and MaxTokenLength. To use case-insensitive token comparison and generate upper-case-only token, set CaseSensitive to false. More advanced users can try to set TokenAlphabet to specify which characters may appear in the generated tokens.

The validation of the token is related with two properties: TestLimit (defaults to 5 times) and TokenExpiry (defaults to 600 seconds). The former specifies how many times a token can be tested with on the server side, and the latter says when a generated token will expire. If the validation fails in any of the two scenarios, a new token will be automatically generated.

To specify the appearance of the generated token image, set TokenImageTheme to be an integer between 0 and 63. You may try the following example to see how this value affects the generated token image. The size of the generated token image is determined by TokenFontSize. In particular, the image width is proportional to the font size. You may also set Width to scale the generated image to your desired size, but the scaled image may not look good. By setting ChangingTokenBackground to true, the image background of the token will be variating even though the token is the same during postbacks.

Upon postback, user input can be validated by calling the method TCaptcha.validate(). More easily, you can use a TCaptchaValidator to automate the validation work for you. The TCaptchaValidator has the additional benefit of being able to validate the user input on the client-side. By default, a generated token will remain unchanged during postbacks. A new token can be generated by calling TCaptcha.regenerateToken() manually.

The following template shows a typical use of the TCaptcha control:

<com:TCaptcha ID="Captcha" />
<com:TTextBox ID="Input" />
<com:TCaptchaValidator CaptchaControl="Captcha"
                          ErrorMessage="You are challenged!" />