Guides

These pages have a draft status.

Captcha


MyCaptcha1 is a CAPTCHA implementation for Drupal 5.x. A CAPTCHA is a test that tries to determine whether a user is human (learn more).
The combination of MyCaptcha and Form Store enables you to add captchas to arbitrary forms2 on your site without modifying a single line of code.
While MyCaptcha provides much of the same functionality, it is not related to the Captcha and TextImage modules by Fabiano Sant'Ana that can be downloaded from Drupal.org.

1Yes, a lousy name.
2Due to the way the Drupal login form has been coded, it cannot be protected by MyCaptcha.

» Download MyCaptcha

Bugs & Support

When you find a bug, please check whether it is a known issue or already present in the existing queue. If your bug is new, please file a bug report. If you require support, you may want to post a support request. Please understand that support requests are answered on a 'best effort' basis.

Donations

If you like MyCaptcha and wish to do something in return, consider a small donation via PayPal that will enable me to shorten my wishlist.

FAQ

Why is this module not on Drupal.org?
There's already a CAPTCHA module on Drupal.org. Functionality should not be duplicated in the Drupal.org repository.
OMG! The image is unreadable!!!!
Visit the settings page on Administer » Site configuration » Captcha (admin/settings/mycaptcha/image) and disable some of the noise options (Double vision, Dots, Lines). See the page Image captcha settings for more information.

Requirements

Before installation, ensure your system meets the requirements.

While MyCaptcha supports PostgreSQL, Form Store doesn't (yet; there's an untested patch in the Form store issue queue).

MyCaptcha cannot be used alongside the modules TextImage and Captcha from Drupal.org.

Installation

Download and install

  1. Download Form Store.
  2. Extract the folder form_store into sites/all/modules/ using a decompression utility (7-zip).
  3. Download MyCaptcha.
  4. Extract the folder mycap into sites/all/modules/ using a decompression utility (7-zip).

Enable the modules

Visit Administer » Site building » Modules (admin/build/modules) and check the modules:

  • Form Store
  • Form Collect
  • MyCaptcha

Save the configuration. Both Form Store and MyCaptcha will apply all necessary changes to the database.

Basic configuration


The first tab of Administer » Site configuration » Captcha (admin/settings/mycaptcha) enables you to select the captcha type (math or image) that will be used site-wide. It also contains the clickable sentence "Captcha settings for ..." for each role defined on your site.

When you click on such a sentence, for example, "Captcha settings for anonymous user", a box will open as in the image on the right. This box lists the various forms you can use a captcha on. Simply check the relevant forms and repeat for the other roles on your site (if necessary). Click Save and you're done.


Example

Suppose you wish to enable image captchas for the user registration page. First, select Image captcha for the captcha type. Then, open the "Captcha settings for anonymous user" setting box by clicking on the title. Check the box in front of "register a user account" and click save. If you now logout and visit user/register you'll see an image captcha on the registration form.

Further reading

Settings for both captcha types are available via tabs on Administer » Site configuration » Captcha (admin/settings/mycaptcha). See for more information:

Visit the Advanced configuration guide to learn how to add a captcha to forms not listed on the Captcha settings page.


Image captcha settings


The tab 'Images' on Administer » Site configuration » Captcha (admin/settings/mycaptcha/image) gives access to a few settings to influence image captcha generation.

Characters to appear in the image
Only characters in this textfield will be used in an image captcha. Those that can be easily mistaken for one-another in the font you are useing (eg i and l) can be removed.
Font
Relative path to a TrueType font you wish to use. MyCaptcha comes with a number of Bitstream fonts in the font subfolder.
Minimum captcha length
The minimum amount of characters that appears in the captcha.
Maximum captcha length
The maximum amount of characters that appears in the captcha.

Next come a number of settings that add noise to the picture to make solving the captcha more difficult. As you can see in the examples below, those settings can be combined. Overdoing it might lead to a high percentage of captchas that aren't solvable by your visitors.

Be aware that some settings make it more time consuming, not impossible for a program to solve a CAPTCHA; most despeckle algorithms can clean up the dot noise, but they cost time.

CAPTCHA Settings
No additional noise
Double vision
Add dots as noise
Add lines as noise
Double vision, add dots as noise
Add dots as noise, add lines as noise

Math captcha settings

The tab 'Math' on Administer » Site configuration » Captcha (admin/settings/mycaptcha/math) doesn't contain a whole lot of settings. The only configurable option right now is the maximum answer of the math captcha. This is a measure of the difficulty of the captcha for humans (at least for those who can't find Calculator in their Start menu). The higher the maximum answer, the lower the chance that a bot guesses the right answer.

Note: It would be fairly easy to write a bot that could solve this kind of captcha.

Advanced configuration

Suppose you want to add a CAPTCHA to the site-wide contact form. As you enable the Contact module and configure the various contact settings, you realize you're out of luck; The Captcha settings page on Administer » Site configuration » Captcha (adminster/settings/mycaptcha) doesn't list the contact form!

Now what?

This is the part where a bit of work is required. In order to add a CAPTCHA to arbitrary forms, MyCaptcha utilizes the helper modules Form store and Form Collect. The module Form store provides MyCaptcha with its list of forms, whereas Form Collect is an ultrasmall helper that can add any form to the Form Store.

Adding forms to the Form Store


As you can see in the image above, the contact form isn't listed in the Form Store. So, check whether the module Form Collect is enabled (admin/build/modules) and do as the help text says; Visit Administer » Site configuration » Form Store, tab Collect forms (admin/settings/form-store/collect).


Simply check "Collect forms while browsing the site" and save the configuration. Now, all you have to do is visit the forms you want to add to the Form Store, in our case the form on the path contact. The moment you, or another visitor views the form, it is added to the Store. Return to Administer » Site configuration » Form Store, tab Collect forms (admin/settings/form-store/collect) to disable the collection.

You will now see that the contact form, with the cryptic name contact_mail_page has been added to the Form Store.

You can use the Description field to provide a more friendly description. This description will, when available, be used by MyCaptcha. To edit or remove a form, click edit, then choose the appropriate action.

In our case, we will add the description "contact form" to the form with the internal name contact_mail_page, so we'll have a less confusing Captcha settings page.

Add a Captcha


After all this, you can visit Administer » Site configuration » Captcha (adminster/settings/mycaptcha) once more. The contact form is now listed on the page and a CAPTCHA (here in the most unreadable variant) can be added to it.

Notes

While the example just adds one form to the Form Store, you can add multiple forms in one sitting.
When you finish Form collection, visit Administer » Site configuration » Form Store, tab Collect forms (admin/settings/form-store/collect) to disable collection. You can now disable the module Form collect (on admin/build/modules).

Known issues

  • MyCaptcha can not be used with the login (user block & /user)or poll voting form.
    This is due to the design of Drupal core.
  • MyCaptcha does not generate a new challenge when a form submission results in an error (other than in the CAPTCHA answer itself). While this is desireable behaviour for the large majority of forms, it does diminish its value on certain forms. Take the request new password form (user/password) for example; a bot can be 'primed' with the right captcha response, after which it can continue guessing for up to two hours (as the CAPTCHA expires in 7200 seconds).
    This will change in the future, allowing per form settings.
  • MyCaptcha interacts with page caching (admin/settings/performance). A captcha prevents caching of pages on which it appears. You need to make sure forms with a captcha do not appear on too many pages, or cache will be effectively off. The comment submission form is the cause for most concern. Make sure you set the "Location of comment submission form" to "Display on separate page" on Administer » Content management » Comments, tab Settings (admin/content/comment/settings) or your content will no longer be cached.
    This is by design.
  • When a user has more roles then just the "authenticated user" role, the captcha setting for "authenticated user" will not take effect for that user.
    This is by design.
  • When you are user 1 you will never see a captcha.
    This is by design.
  • When you remove a form from the Form store while a captcha is enabled for it, you can no longer disable the captcha for the form. Add the form back to the Form store, then disable the captcha.
    This is unfortunate.
  • If a certain (broken) form performs a drupal_goto() in its form submit function, MyCaptcha will not be able to clean up. This undermines the use of MyCaptcha for this form as the seed will be reuseable.
    File a bug against the affected module.

Other known issues may be found in the MyCaptcha forum.

Thanks & Credits

MyCaptcha uses fonts by Bitstream and a wave distortion function from KCAPTCHA by Kruglov Sergei.

  • Thanks to Xamox for testing.
  • Thanks to Sepeck for testing.
  • Special thanks to Tjeerd Zwaga.

MyCaptcha is Copyright © 2007 by Heine Deelstra. Please see the files LICENSE.TXT and fonts/LICENSE.txt in the download for licensing terms.

The most up to date credits can be found in the Thanks & Credits section of README.txt.

Drupal's Forms API

Under construction.

From the Forms API quickstart guide:

The Drupal forms API is a powerful leap forward. It also allows for almost unlimited possibilities for custom theming, validation, and execution of forms. Even better, ANY form (even those in core) can be altered in almost any way imaginable--elements can be removed, added, and rearranged.

Forms API goes by the moniker FAPI.

Example scaffolding

Before we dive into the details of the Forms API, we need a little scaffolding code to enable you to test the examples on a site. Here we map the URL example/page to the function call example_page(). We'll later fill this function with relevant code.

  1. function example_menu($may_cache) {
  2.   if ($may_cache) {
  3.     $items = array();
  4.     $items[] = array(
  5.       'path' => 'example/page',
  6.       'title' => 'Example',
  7.       'callback' => 'example_page',
  8.       'access' => user_access('access example'),
  9.       'type' => MENU_CALLBACK,
  10.     );
  11.     return $items;
  12.   }
  13. }
  14.  
  15. function example_perm() {
  16.   return array('access example');
  17. }
  18.  
  19. /**
  20.   * This function will be called upon a visit to example/page.
  21.   */
  22. function example_page() {
  23.  
  24. }

The example implements the following hooks:

hook_menu
Maps URLs to callback functions in addition to providing a way to define actual entries in the navigation menu.
hook_perm
Supplies permissions that can be assigned on the admin/users/access page and checked with user_access().

To use the example code on your site, you can save it in sites/all/modules/example/example.module together with example.info:

  1. name = Example
  2. description = Toy with FAPI examples.

FAPI stages

This is in progress.

The pivotal FAPI function is drupal_get_form(); it retrieves a form from a builder function, passes it on for processing, and renders the form or redirects to its destination as appropriate.

One can distinguish three stages in the life of a form:

  1. Stage I - Building.
  2. Stage II - Validation.
  3. Stage III - Submission.

Stage I - Building

The building stage starts when you call drupal_get_form('form_id'), with the function scurrying away to find the builder function of the appropriate form. To keep it simple for now; drupal_get_form checks if the function form_id() exists, then calls it, expecting a proper FAPI array in return. Alternatives to this approach will be discussed in future chapters.

In the code below, we fetch a form with the identifier myform, build by the function myform(), specifying a select box, a textfield and a button.

  1. function example_page() {
  2.   // Forms are identified by their form id, in this case 'myform'.
  3.   // drupal_get_form will fetch the form from the builder function myform().
  4.   return drupal_get_form('myform');
  5. }
  6.  
  7. /**
  8.   * Builder function for the form with the form_id myform.
  9.   * Returns a form array.
  10.   */
  11. function myform() {
  12.   $form = array();
  13.  
  14.   // A combo box with three options.
  15.   $form['gender'] = array(
  16.     '#type' => 'select',
  17.     '#title' => t('Gender'),
  18.     '#options' => array('male' => t('Male'), 'female' => t('Female'), 'unknown' => t('Not sure')),
  19.   );
  20.  
  21.   // A textfield to provide the number of siblings. We have to ensure numeric input.
  22.   $form['siblings'] = array(
  23.     '#type' => 'textfield',
  24.     '#title' => t('How many siblings do you have?'),
  25.   );
  26.  
  27.   // Submission button with the text 'Save'.
  28.   $form['save'] = array(
  29.     '#type' => 'submit',
  30.     '#value' => t('Save'),
  31.   );
  32.   return $form;
  33. }

This builder function supplies a number of fields defined by keys of the nested forms array. The '#key' => 'value' pairs are properties of the field. We'll deal with those later, but you can take a look at the FAPI reference to get a feel for the available properties.

Stage II - Validation

When the user clicks a button on the form, data is send back to the server. Drupal reruns the form builder function and then starts the validation stage. A few properties are automatically validated. Required fields, maximum input length (textfields), whether selected options are valid options and the internal form token (to protect against cross site request forgeries).

There are multiple ways to do some validation yourself, but the easiest is to provide a [form_id]_validate function. This takes two arguments: the form id and an array of values. In the example we use a custom validation function to make sure that the number of siblings is numeric. By setting an error on the field 'siblings' we ensure that the form is redisplayed to the user with the error message "Please enter a number".

  1. /**
  2.   * Input validation takes place in [form_id]_validate().
  3.   */
  4. function myform_validate($form_id, $form_values) {
  5.   // If the input received in the siblings field is not numeric, set an error on that field.
  6.   // This will prevent progression to [form_id]_submit() and redisplay the form to the user.
  7.   if (!is_numeric($form_values['siblings'])) {
  8.     form_set_error('siblings', t('Please enter a number.'));
  9.   }
  10. }

When the form validation is successful, the next stage starts: submission.

Stage III - Submission

  1. /**
  2.   * With validation passed [form_id]_submit() acts on the submission.
  3.   */
  4. function myform_submit($form_id, $form_values) {
  5.   $query = "INSERT INTO {example} (gender, siblings) VALUES ('%s', %d)";
  6.   db_query($query, $form_values['gender'], $form_values['siblings']);
  7. }

Elements

If you are familiar with the Drupal forms API you know the concept of form elements as the basic building blocks of any form. Drupal provides several types of elements, some rather straightforward (#type textfield), some more advanced (#type password_confirm).

It is also possible to define custom form elements that enable you to implement complex widgets with ease.

At the moment, the focus of Elements is the tableselect widget. It provides a clean, easy way to create tables with one checkbox per row, multi-row selection and a select all checkbox, without making your code a complicated mess.

Example scaffolding

You can use the following code to create an example.module which you can use to experiment with the examples in this guide.

  1. // example.module
  2. function example_menu($maycache) {
  3.   if ($maycache) {
  4.     $items[] = array(
  5.       'path' => 'scratch/elements',
  6.       'access' => user_access('administer site configuration'),
  7.       'type' => MENU_NORMAL_ITEM,
  8.       'title' => t('Elements'),
  9.       'callback' => 'drupal_get_form',
  10.       'callback arguments' => array('example_elements_form'),
  11.     );
  12.     return $items;
  13.   }
  14. }

  1. ; example.info
  2. name = "Example"
  3. description = "Quick scratch module."

Comboselect element

The comboselect element has not yet been included in Elements. You can follow its development at #268424.

The comboselect written by John Morahan gives you a select type element with an 'Other' option. When the user chooses this option; a textfield appears.

Create a simple comboselect element

  1. function example_elements_form() {
  2.   $form = array();
  3.  
  4.   $options = array(
  5.     'one' => t('First Option'),
  6.     'two' => t('Second Option'),
  7.   );
  8.  
  9.   $form['choice'] = array(
  10.     '#type' => 'comboselect',    
  11.     '#title' => t('Example'),
  12.     '#default_options' => $options,
  13.   );
  14.  
  15.   $form['submit'] = array(
  16.     '#type' => 'submit',
  17.     '#value' => t('Submit'),
  18.   );
  19.  
  20.   return $form;
  21. }


Change the 'Other' option

  1. function example_elements_form() {
  2.   $form = array();
  3.  
  4.   $options = array(
  5.     'one' => t('First Option'),
  6.     'two' => t('Second Option'),
  7.   );
  8.  
  9.   $form['test'] = array(
  10.     '#type' => 'comboselect',    
  11.     '#title' => t('Example'),
  12.     '#required' => TRUE,
  13.     '#default_options' => $options,
  14.     '#other' => t('None of the above, but'),
  15.   );
  16.  
  17.   $form['submit'] = array(
  18.     '#type' => 'submit',
  19.     '#value' => t('Submit'),
  20.   );
  21.  
  22.   return $form;
  23. }

Tableselect element

The form element tableselect provides a clean, easy way to create tables with one checkbox per row, multi-row selection and a select all checkbox, without making your code a complicated mess:

A simple table

The basic properties of the tableselect element are #header which accepts an array of key => value pairs to generate the header from and #options, which receives an array of rows.

The basic structure looks like the following:

$header = array(
  'field1' => 'Title of field 1',
  'field2' => 'Title of field 2',
);

$options['some_unique_id'] = array(
  'field1' => 'Value of field 1',
  'field2' => 'Value of field 2',
);

The tableselect element relies on the keys to match columns with the appropriate header. The element will behave like the #checkboxes type. You'll get an array of values in your submit function, with the checked ones set to nonzero so you can array_filter them to get the checked rows.

function example_elements_form() {
  $form = array();

  $header = array(
    'title' => t('Title'),
    'author' => t('Author'),
  );

  $query = "SELECT n.nid, n.title, u.name FROM {node} n INNER JOIN {users} u ON n.uid = u.uid";
  $result = pager_query(db_rewrite_sql($query));

  while($partial_node = db_fetch_object($result)) {
    $options[$partial_node->nid] = array(
      'title' => check_plain($partial_node->title),
      'author' => check_plain($partial_node->name),
    );
  }

  if (!empty($options)) {
    $form['nodes'] = array(
      '#type' => 'tableselect',
      '#header' => $header,
      '#options' => $options,
    );

    $form['pager'] = array('#value' => theme('pager'));

    $form['submit'] = array(
      '#type' => 'submit',
      '#value' => t('Submit'),
    );

  }
  return $form;
}

Which results in:

Example table

Support for sortable tables

The tableselect element supports use with tablesort_sql. Simply modify the header to the format described in theme_table.

function example_elements_form() {
  $form = array();

  $header = array(
    'title' => array('field' => 'n.title', 'data' => t('Title')),
    'author' => array('field' => 'u.name', 'data' => t('Author')),
  );

  $query = "SELECT n.nid, n.title, u.name FROM {node} n INNER JOIN {users} u ON n.uid = u.uid". tablesort_sql($header);

  $result = pager_query(db_rewrite_sql($query));

  while($partial_node = db_fetch_object($result)) {
    $options[$partial_node->nid] = array(
      'title' => check_plain($partial_node->title),
      'author' => theme('username', $partial_node),
    );
  }

  if (!empty($options)) {
    $form['nodes'] = array(
      '#type' => 'tableselect',
      '#header' => $header,
      '#options' => $options,
    );

    $form['pager'] = array('#value' => theme('pager'));

    $form['submit'] = array(
      '#type' => 'submit',
      '#value' => t('Submit'),
    );

  }

  return $form;
}

Properties

#header
The table header, an array of field_key => title pairs or the format described for theme_table.
#options
The data displayed in the table. Nested array of id => array pairs where the array is an array of field_key => value pairs.
#multiple
Determines whether multiple values can be selected. Displays checkboxes when TRUE, radios when FALSE.
Default: TRUE
#advanced_select
Whether to provide advanced selection behaviour (SELECT ALL checkbox, SHIFT-select).
Default: TRUE - when #multiple is TRUE.
When #multiple is FALSE, always FALSE.
#default_value
Provide an array of id => x pairs for the ids that should be selected by default when #multiple is TRUE.
Provide the id as a scalar for the id that should be selected by default when #multiple is FALSE.