diff --git a/docs/api.md b/captcha.api.php similarity index 56% rename from docs/api.md rename to captcha.api.php index 64dcf4b..cdaf21f 100644 --- a/docs/api.md +++ b/captcha.api.php @@ -1,4 +1,11 @@ -This documentation is for developers that want to implement their own + t('Enter "foo"'), '#required' => TRUE, ]; + // The CAPTCHA module provides an option for case sensitive and case + // insensitve validation of the responses. If this is not sufficient, + // you can provide your own validation function with the + // 'captcha_validate' field, illustrated by the following example: + $captcha['captcha_validate'] = 'foo_captcha_custom_validation'; return $captcha; } break; } } -""" -Validation of the answer against the solution and other stuff is done by the +/* 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. @@ -81,11 +71,10 @@ To integrate nicely with the base CAPTCHA module you should offer your configuration page as a MENU_LOCAL_TASK menu entry under 'admin/config/people/captcha/'. -For our simple foo CAPTCHA module this would mean: +For our simple foo CAPTCHA module this would mean: */ -""" /** - * Implementation of hook_menu(). + * Implements hook_menu(). */ function foo_captcha_menu($may_cache) { $items = []; @@ -99,89 +88,71 @@ function foo_captcha_menu($may_cache) { } return $items; } -""" -You should of course implement a function foo_captcha_settings_form() which +/* 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: +For our simple foo CAPTCHA module this would mean: */ -""" /** - * Implementation of hook_help(). + * Implements hook_help(). */ function foo_captcha_help($route_name, RouteMatchInterface $route_match) { switch ($route_name) { case 'foo_captcha.settings': - return '

'. t('This is a very simple challenge, which requires users to - enter "foo" in a textfield.') .'

'; - } -} -""" - - - -=== Optional: custom response validation === -The CAPTCHA module provides an option for case sensitive and case insensitve -validation of the responses. If this is not sufficient, you can provide -your own validation function with the 'captcha_validate' field, illustrated -by the following example: - -""" -/** - * Implementation of hook_captcha(). - */ -function foo_captcha_captcha($op, $captcha_type='') { - switch ($op) { - ... - case 'generate': - if ($captcha_type == 'Foo CAPTCHA') { - $captcha = []; - $captcha['solution'] = ... - $captcha['form'] = ... - $captcha['captcha_validate'] = 'foo_captcha_custom_validation'; - return $captcha; - } - break; + return '

' . t('This is a very simple challenge, which requires users to + enter "foo" in a textfield.') . '

'; } } /** * Custom CAPTCHA validation function. * - * @param solution the solution for the challenge as reported by - hook_captcha('generate', ...). - * @param response the answer given by the user. - * @return TRUE on succes and FALSE on failure. + * @param $solution + * the solution for the challenge as reported by hook_captcha('generate',...). + * @param $response + * the answer given by the user. + * + * @return true + * on succes and FALSE on failure. */ function foo_captcha_custom_validation($solution, $response) { return $response == "foo" || $response == "bar"; } -""" -Previous example shows the basic usage for custom validation with only a +/* Previous example shows the basic usage for custom validation with only a $solution and $response argument, which should be sufficient for most CAPTCHA modules. More advanced CAPTCHA modules can also use extra provided arguments $element and $form_state: -""" -function foo_captcha_custom_validation($solution, $response, $element, - $form_state) { + */ + +/** + * Custom Advance CAPTCHA validation function. + * + * @param $solution + * the solution for the challenge as reported by hook_captcha('generate',...). + * @param $response + * the answer given by the user. + * @param $element + * element argument. + * @param $form_state + * form_state argument. + * + * @return true + * on succes and FALSE on failure. + */ +function foo_captcha_custom_advance_validation($solution, $response, $element, $form_state) { return $form_state['foo']['#bar'] = 'baz'; } -""" -These extra arguments are the $element and $form_state arguments of the + +/* These extra arguments are the $element and $form_state arguments of the validation function of the #captcha element. See captcha_validate() in captcha.module for more info about this. - - === Hook into CAPTCHA placement === The CAPTCHA module attempts to place the CAPTCHA element in an appropriate spot at the bottom of the targeted form, but this automatic detection may be @@ -189,19 +160,20 @@ insufficient for complex forms. The hook_captcha_placement_map hook allows to define the placement of the CAPTCHA element as desired. The hook should return an array, mapping form IDs to placement arrays, which are associative arrays with the following fields: - - 'path': path (array of path items) of the form's container element in which - the CAPTCHA element should be inserted. - - 'key': the key of the element before which the CAPTCHA element - should be inserted. If the field 'key' is undefined or NULL, the CAPTCHA - will just be appended in the container. - - 'weight': if 'key' is not NULL: should be the weight of the element defined - by 'key'. If 'key' is NULL and weight is not NULL/unset: set the weight - property of the CAPTCHA element to this value. +- 'path': path (array of path items) of the form's container element in which +the CAPTCHA element should be inserted. +- 'key': the key of the element before which the CAPTCHA element +should be inserted. If the field 'key' is undefined or NULL, the CAPTCHA +will just be appended in the container. +- 'weight': if 'key' is not NULL: should be the weight of the element defined +by 'key'. If 'key' is NULL and weight is not NULL/unset: set the weight +property of the CAPTCHA element to this value. For example: -""" + */ + /** - * Implementation of hook_captcha_placement_map + * Implements hook_captcha_placement_map(). */ function hook_captcha_placement_map() { return [ @@ -215,8 +187,9 @@ function hook_captcha_placement_map() { ], ]; } -""" -This will place the CAPTCHA element - - in the 'my_fancy_form' form inside the container $form['items']['buttons'], - just before the element $form['items']['buttons']['sacebutton']. - - in the 'another_form' form at the toplevel of the form, with a weight 34. + +/* This will place the CAPTCHA element +- in the 'my_fancy_form' form inside the container $form['items']['buttons'], +just before the element $form['items']['buttons']['sacebutton']. +- in the 'another_form' form at the toplevel of the form, with a weight 34. + */