BotDetect PHP CAPTCHA Client-Side API Reference

BotDetect Client-Side Prototype
BotDetect Client-Side Object

BotDetect Client-Side Prototype Reference

The main client-side BotDetect prototype (accessible on the whole page using BotDetect.<member_name>) exposes several global functions and constants.

BotDetect Client-Side Prototype Reference
	Init captchaId instanceId inputId autoUppercaseInput autoFocusInput autoClearInput autoReloadExpiredImage autoReloadPeriod autoReloadTimeout soundStartDelay limitSoundRegeneration imageColorMode	The client-side BotDetect initialization function (used as a "constructor") takes the following arguments: `captchaId` is the unique Captcha identifier of the Captcha control on the page. It's a mandatory parameter for all Captcha scripts to run `instanceId` is the unique identifier of each Captcha instance (each Captcha identified by `captchaId` generates a new `instanceId` every time it generates its markup i.e. on each page load) `inputId` is the client-side identifier of the Captcha code user input field. It's needed for all scripts that process the user input `autoUppercaseInput` is a boolean value specifying if the user input should be automatically uppercased during typing `autoFocusInput` is a boolean value specifying if the user input should be automatically focused on Captcha Reload and Sound button clicks `autoClearInput` is a boolean value specifying if the user input should be automatically cleared on Captcha Reload button clicks `autoReloadExpiredImage` is a boolean value specifying if Captcha images displaying expired Captcha codes should be automatically reloaded `autoReloadPeriod` is the millisecond count equivalent of the Captcha code timeout value `autoReloadTimeout` is the upper bound millisecond count, after which automatic reloading will stop. This is used to save resources and stop generating Captchas if the user leaves the form open during the weekend and leaves town, for example `soundStartDelay` is the starting delay (in milliseconds) for JavaScript Captcha sound playback `limitSoundRegeneration` tells BotDetect to count sound icon clicks in browsers that don't support Html5 Wav audio, and reload the Captcha image before playing the Captcha audio on sound icon clicks after the first one. This is needed when using the "Limited" sound regeneration mode
	RegisterCustomHandler eventName userHandler	This function is used to register a user-defined handler function, which will be called by BotDetect any time the specified BotDetect event occurs. The first parameter is the name of the BotDetect event you want to handler, and the second is the (parameter-less) handler function that should be called
	ReloadTimerDelay = 250	The delay between each Captcha Reload animation "tick" (status update), in milliseconds.
	ReloadTimerMaxTicks = 100	The maximum number of "ticks" the Captcha Reload animation will go through before it stops (in case the Captcha image reloading Http request timeouts or fails to return a new image).
	MinSoundCooldown = 2000	The cooldown applied to Captcha sound icon clicks, in milliseconds. Used to reduce chances of the user accidentally starting multiple concurrent Captcha sound playbacks.
	AjaxTimeout = 10000	The maximum time (in milliseconds) spent waiting for server responses to asynchronous Http requests. After this period, an Ajax error is raised

[back to the top of the page]

BotDetect Client-Side Object Reference

BotDetect client-side object instances expose all Captcha workflow functions and values, as well as several Captcha life-cycle events. These objects can be accessed in your client-side scripts:

using this.<member_name> within member functions and custom event handlers.

E.g. if you register a function as a custom handler for the PreReloadImage BotDetect event, you can access the BotDetect client-side object within that function using this.
using <captchaId>.<member_name> on the page showing the Captcha.

E.g. if you added Captcha protection to a PHP form using $FormCaptcha = new Captcha("FormCaptcha"), you can also use FormCaptcha as the client-side Captcha object identifier.
using the Captcha custom property of the textbox DOM element registered as the Captcha code input.

E.g. if your server-side code specifies $FormCaptcha->UserInputID = "CaptchaCode", your client-side code can access Captcha functionality through the textbox element: document.getElementById("CaptchaCode").Captcha.

Or, if you're using jQuery and (for example) added a "captchaVal" CSS class to the Captcha code textbox, you can use: $(".captchaVal").get(0).Captcha.

BotDetect Client-Side Object Reference
	ReloadImage	Reloads the current Captcha client-side instance Captcha image
	PlaySound	Starts Captcha sound playback for the current Captcha client-side instance
	StartAjaxValidation	Starts Ajax validation of the user input for the current Captcha client-side instance
	Id	The Captcha Id for the current object (same as the server-side object)
	InstanceId	The Instance Id for the current object (same as the server-side object)
	Image	The <img> element containing the Captcha image
	InputId	The element identifier of the Captcha code user input field (usually a `<input type="text" ... />` element). Only set if the user input client-side ID was specified in the constructor
	GetInputElement	Related to the above, tries to get the input element by Id
	ProgressIndicator	The text element created during Captcha image reloading, and used as a Reload progress indicator
	AutoReloading	Flag indicating that the Captcha image is currently being reloaded because the automatic reloading timer has activated
	SoundPlaceholder	The invisible `<div>` element used as a container for sound objects created during Captcha sound playback
	SoundUrl	BotDetect Captcha Sound Url, used during sound playback
	ValidationUrl	The Url that can be used to send an Ajax Captcha validation request (with the user input of the Captcha code appended as an additional querystring parameter)
	ValidationResult	Set during Ajax Captcha validation
	PostInit	This event occurs after the BotDetect client-side object has been successfully initialized
	PreReloadImage	This event occurs after the user clicks the Captcha Reload button, but before image reloading starts. The default handler clears previous user input, and focuses the Captcha code input field (if auto-clearing and auto-focusing are enabled)
	PostReloadImage	This event occurs after the Captcha image has been successfully reloaded. The default handler updates the Captcha sound Url, and sets up automatic image reloading (if auto-reloading is enabled and we haven't reached the timeout threshold)
	PrePlaySound	This event occurs after the user clicks the Captcha Sound button, but before sound playing starts. Note that there is no matching `PostPlaySound` event, since the available client-side sound playback options don't notify calling functions when playback ends
	OnHelpLinkClick	This event occurs when the user clicks the Captcha image when it's also the Captcha help link (the `Image` help link mode). Captcha help page opening can be aborted in this handler by setting the BotDetect client-side object's `FollowHelpLink` property to `false`
	PreAjaxValidate	This event occurs after the BotDetect client-side `Validate()` function is called, but before any Ajax calls are made
	AjaxValidationFailed	This event occurs after BotDetect Ajax Captcha validation returns `false`. The default handler reloads the Captcha image, since Captcha validation has invalidated the currently displayed Captcha code on the server
	AjaxValidationPassed	This event occurs after BotDetect Ajax Captcha validation returns `true`
	AjaxValidationError	This event occurs if BotDetect Ajax Captcha validation throws errors or timeouts. The default handler aborts any Ajax operations left, and sets the AjaxError flag, which in turn temporarily sets the validation result to `true` to enable full page postback