BotDetect PHP CAPTCHA Client-Side API Reference

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
BotDetect client-side prototype public function init
  • captchaStyleName
  • captchaId
  • userInputID
  • autoUppercaseInput
  • autoFocusInput
  • autoClearInput
  • autoReloadExpiredImage
  • autoReloadPeriod
  • autoReloadTimeout
  • soundStartDelay
  • limitSoundRegeneration
  • imageColorMode
  • javaScriptRequired

The client-side BotDetect initialization function (used as a "constructor") takes the following arguments:

  • captchaStyleName is the unique Captcha identifier of the Captcha control on the page. It's a mandatory parameter for all Captcha scripts to run
  • captchaId 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)
  • userInputID 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
BotDetect client-side prototype public function 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

BotDetect client-side prototype public function getInstanceByStyleName
  • captchaStyleName

This function is used to get BotDetect client-side object, it accepts a Captcha style name as an argument

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 BotDetect.getInstanceByStyleName("yourCaptchaStyleName") to get BotDetect client-side object.

    E.g.

    var captcha = BotDetect.getInstanceByStyleName("FormCaptcha");
    

BotDetect Client-Side Object Reference
BotDetect client-side object function reloadImage Reloads the current Captcha client-side instance Captcha image
BotDetect client-side object function playSound Starts Captcha sound playback for the current Captcha client-side instance
BotDetect client-side object value captchaStyleName The Captcha style name for the current object (same as the server-side object)
BotDetect client-side object value captchaId The Captcha Id for the current object (same as the server-side object)
BotDetect client-side object value image The <img> element containing the Captcha image
BotDetect client-side object value progressIndicator The text element created during Captcha image reloading, and used as a Reload progress indicator
BotDetect client-side object value autoReloading Flag indicating that the Captcha image is currently being reloaded because the automatic reloading timer has activated
BotDetect client-side object value soundPlaceholder The invisible <div> element used as a container for sound objects created during Captcha sound playback
BotDetect client-side object value soundUrl BotDetect Captcha Sound Url, used during sound playback
BotDetect client-side object value validationUrl The Url that can be used to send an Ajax Captcha validation request
BotDetect client-side custom event postInit This event occurs after the BotDetect client-side object has been successfully initialized
BotDetect client-side custom event 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)

BotDetect client-side custom event 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)

BotDetect client-side custom event 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

BotDetect client-side custom event 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