// $Id: captcha_api.txt,v 1.8 2009-06-13 22:12:53 soxofaan Exp $

This documentation is for developers that want to implement their own
challenge type and integrate it with the base CAPTCHA module.


=== Required: hook_captcha($op, $captcha_type='') ===

The hook_captcha() hook is the only required function if you want to integrate
with the base CAPTCHA module.
Functionality depends on the first argument $op:
  * 'list': you should return an array of possible challenge types
    that your module implements.
  * 'generate': generate a challenge.
    You should return an array that offers form elements and the solution
    of your challenge, defined by the second argument $captcha_type.
    The returned array $captcha should have the following items:
    $captcha['solution']: this is the solution of your challenge
    $captcha['form']: an array of the form elements you want to add to the form.
      There should be a key 'captcha_response' in this array, which points to
      the form element where the user enters his answer.

Let's give a simple example to make this more clear.
We create the challenge 'Foo CAPTCHA', which requires the user to
enter "foo" in a textfield.

"""
/**
 * Implementation of hook_captcha().
 */
function foo_captcha_captcha($op, $captcha_type='') {
  switch ($op) {
    case 'list':
      return array('Foo CAPTCHA');
    case 'generate':
      if ($captcha_type == 'Foo CAPTCHA') {
        $captcha = array();
        $captcha['solution'] = 'foo';
        $captcha['form']['captcha_response'] = array(
          '#type' => 'textfield',
          '#title' => t('Enter "foo"'),
          '#required' => TRUE,
        );
        return $captcha;
      }
      break;
  }
}
"""

Validation of the answer against the solution and other stuff is done by the
base CAPTCHA module.




=== Required: the .info file ===

You should specify that your module depends on the base CAPTCHA module.
Optionally you could put your module in the "Spam control" package.

For our simple foo CAPTCHA module this would mean the following lines in the
file foo_captcha.info:

"""
name = "Foo CAPTCHA"
description = "The foo CAPTCHA requires the user to enter the word 'foo'."
package = "Spam control"
dependencies = captcha
core = 6.x
"""




=== Recommended: hook_menu($may_cache) ===

More advanced CAPTCHA modules probably want some configuration page.
To integrate nicely with the base CAPTCHA module you should offer your
configuration page as a MENU_LOCAL_TASK menu entry under 'admin/user/captcha/'.

For our simple foo CAPTCHA module this would mean:

"""
/**
 * Implementation of hook_menu().
 */
function foo_captcha_menu($may_cache) {
  $items = array();
  if ($may_cache) {
    $items['admin/user/captcha/foo_captcha'] = array(
      'title' => t('Foo CAPTCHA'),
      'page callback' => 'drupal_get_form',
      'page arguments' => array('foo_captcha_settings_form'),
      'type' => MENU_LOCAL_TASK,
    );
  }
  return $items;
}
"""

You should of course implement a function foo_captcha_settings_form() which
returns the form of your configuration page.




=== Optional: hook_help($section) ===
To offer a description/explanation of your challenge, you can use the
normal hook_help() system.

For our simple foo CAPTCHA module this would mean:

"""
/**
 * Implementation of hook_help().
 */
function foo_captcha_help($path, $arg) {
  switch ($path) {
    case 'admin/user/captcha/foo_captcha':
      return '<p>'. t('This is a very simple challenge, which requires users to enter "foo" in a textfield.') .'</p>';
  }
}
"""


=== Optional: (pre)process the response ===
In some situations it could be necessary to preprocess the response before
letting the CAPTCHA module validate it. For example: remove spaces from the
response or merge the value of different widgets into one widget value.
The previous version of the CAPTCHA API (5.x-3.x and 6.x-1.x) contained some
custom tricks to make this possible, but since version 6.x-2.x it is recommended
to use the standard Drupal Form API functionality, like the '#process' property.


The following example shows how to add a '#process' callback to the captcha_response
form element, and how that callback can process the response with a fictional
remove_spaces() function.

"""
/**
 * Implementation of hook_captcha().
 */
function foo_captcha_captcha($op, $captcha_type='') {
  switch ($op) {
...
    case 'generate':
      if ($captcha_type == 'Foo CAPTCHA') {
...
        $captcha['form']['captcha_response'] = array(
          '#type' => 'textfield',
          '#title' => t('Enter "foo"'),
          '#required' => TRUE,
          '#process' => array('foo_captcha_process'),
        );
...
}

/**
 * Process the response to the foo CAPTCHA before validation.
 */
function foo_captcha_process($element, $edit, &$form_state, $complete_form) {
  $element['#value'] = remove_spaces($element['#value']);
  return $element;
}
"""