Gallery2:How to use Captcha

Overview

The Captcha module helps prevent spammers from using automated scripts to submit forms. Other modules can make use of this captcha support as described below.

Setting

The first step is to allow captcha for your module to be configured. This can be to turn captcha on/off or pick a particular validation level. These levels are described on the Site Admin / Captcha page.

Edit your module.inc file and add code like this to function performFactoryRegistrations():

        $ret = GalleryCoreApi::registerFactoryImplementation(
            'CaptchaAdminOption', 'MyModuleCaptchaAdminOption', 'MyModuleCaptchaAdminOption',
            'modules/mymodule/classes/MyModuleCaptchaAdminOption.class', 'mymodule', null);
        if ($ret) {
            return $ret;
        }

Then create the MyModuleCaptchaAdminOption.class file; something like this:

class MyModuleCaptchaAdminOption extends CaptchaAdminOption {
    /**
     * @see CaptchaAdminOption::getOptionData
     */
    function getOptionData() {
        list ($ret, $module) = GalleryCoreApi::loadPlugin('module', 'mymodule');
        if ($ret) {
            return array($ret, null, null, null);
        }
        return array(null, $module->translate('Captcha for My Module'),
                     array('module', 'mymodule', 'validation.level'),
                     array('HIGH', 'OFF'));
    }
}

In this example only the HIGH and OFF selections are available for your module in the Site Admin / Captcha page. Also in your module's upgrade() function make sure to initialize the 'validation.level' parameter (to a value like OFF or HIGH).

View

The next step is to add the captcha form element. In your view's loadTemplate() function add code like this:

        $plugins = array();
        list ($ret, $captchaLevel) =
            GalleryCoreApi::getPluginParameter('module', 'mymodule', 'validation.level');
        if ($ret) {
            return array($ret, null);
        }
        if ($captchaLevel != 'OFF') {
            list ($ret, $allPluginIds) =
                GalleryCoreApi::getAllFactoryImplementationIds('GalleryValidationPlugin');
            if ( $ret) {
                return array($ret, null);
            }

            /* Let each plugin load its template data */
            foreach (array_keys($allPluginIds) as $pluginId) {
                list ($ret, $plugin) =
                    GalleryCoreApi::newFactoryInstanceById('GalleryValidationPlugin', $pluginId);
                if ($ret) {
                    return array($ret, null);
                }
                list ($ret, $data['file'], $data['l10Domain']) = $plugin->loadTemplate($form);
                if ($ret) {
                    return array($ret, null);
                } else if (isset($data['file'])) {
                    $plugins[] = $data;
                }
            }
        }
        $template->setVariable('validationPlugins', $plugins);

Then in the view's tpl file add:

 {* Include validation plugins *}
 {foreach from=$validationPlugins item=plugin}
    {include file="gallery:`$plugin.file`" l10Domain=$plugin.l10Domain}
 {/foreach}

Now your page will show captcha in the form when the setting is not "OFF".

Controller

The final step is to verify the captcha challenge is answered correctly, and abort processing if it is not. In your controller class add something like this:

        //..validate your form data, set $error values if applicable..
        list ($ret, $captchaLevel) =
            GalleryCoreApi::getPluginParameter('module', 'mymodule', 'validation.level');
        if ($ret) {
            return array($ret, null);
        }
        if (empty($error) && $captchaLevel != 'OFF') {
            list ($ret, $pluginInstances) =
                GalleryCoreApi::getAllFactoryImplementationIds('GalleryValidationPlugin');
            if ($ret) {
                return array($ret, null);
            }

            foreach (array_keys($pluginInstances) as $pluginId) {
                list ($ret, $pluginInstances[$pluginId]) =
                    GalleryCoreApi::newFactoryInstanceById('GalleryValidationPlugin', $pluginId);
                if ($ret) {
                    return array($ret, null);
                }
            }

            /* Let each plugin do its verification */
            foreach ($pluginInstances as $plugin) {
                list ($ret, $pluginErrors, $continue) = $plugin->performValidation($form);
                if ($ret) {
                    return array($ret, null);
                }

                $error = array_merge($error, $pluginErrors);
                if (!$continue) {
                    break;
                }
            }
        }
        if (empty($error)) {
            //..proceed with processing your form data..
        }

Medium/Low Validation Level

If your form already is a success/fail type of form (such as entering a password) then you may wish to support the LOW/MEDIUM validation levels in addition to HIGH/OFF. This requires some additional code in the view/controller to support counting failures. See example code in modules/core/UserLogin.inc to see how this is done.

Personal tools