/ 
Konstrukt-0.5-beta7
River stage zero No dependents
/ Konstrukt::Plugin::captcha

NAME

Konstrukt::Plugin::captcha - Put captchas in your forms easily.

SYNOPSIS

Tag interface

Usage:

<!-- the easy way -->
<& captcha / &>

or

<!-- defining your own settings that may differ from the defaults -->
<& captcha type="text" template="/templates/captcha/text.template" / &>

Result: (Something like this)

<script type="text/javascript">
	var enctext = "%50%0A%3A%21%44%38%4C%0C%0D%0E%31%6C%13%2F%0D%12%18%00%3C%30%6E%2D%02%11%1B%06%26%73%11%38%15%12%09%5E%76%39%58%28%08%07%02%41%74%32%5D%2D%1F%11%51%41%2C%29%5D%6E%4C%14%0D%0F%21%34%0C%6E%5D%16%06%01%23%73%11%63%52%68";
	var key = "lcTQ1Llb";
	function xor_enc(text, key) {
		var result = '';
		for(i = 0; i < text.length; i++)
			result += String.fromCharCode(key.charCodeAt(i % key.length) ^ text.charCodeAt(i));
		return result;
	}
	document.write(xor_enc(unescape(enctext), key));
</script>

<noscript>
	<label>Antispam:</label>
	<div>
	<p>Please type the text '1tjbw' into this field:</p>
	<input name="captcha_answer" />
	</div>
</noscript>

<input name="captcha_hash" type="hidden" value="3452c4fb13505c5ffa256f2352851ed2b9286af70c3f9ed65e3e888690e1ee69" />

The captcha tag will usually be embedded in an existing <form>. It will only generate the question (using a template) and two <input> HTML-tags that will accept the answer and pass a hash of the correct answer to the server.

Perl interface

It's very easy to add a captcha-check to your plugins:

my $template = use_plugin 'template';

if ((use_plugin 'captcha')->check()) {
	#captcha solved!
	#your code...
} else {
	#captcha not solved!
	#e.g. put error message and ask again:
	$self->add_node($template->node('error_message.template'));
	$self->add_node($template->node('template_with_input_form_and_captcha_tag.template'));
}

DESCRIPTION

This plugin will put a captcha on your website and allows you to check it easily.

There may be several implementation types, although currently only text captchas are implemented.

If the session management is activated, the user won't be asked to answer a captcha again, if (s)he already answered one correctly. This behaviour can be disabled in the setting captcha/ask_once.

Also a user, which has logged on, won't be asked to enter a captcha. This behaviour can be disabled in the setting captcha/dont_ask_users.

CREATING OWN CAPTCHA IMPLEMENTATIONS

To create an captcha implementation, you must create plugin module Konstrukt::Plugin::captcha::your_type.

This plugin needs to have a method display, which will be called to display the captcha part of the input dialogue (i.e. the captcha question and the input fields for the answer (name="captcha_answer")and the hash checksum (name="captcha_hash")).

This will be done like every (simple) plugin does via print or $self-add_node()> (see "add_node" in Konstrukt::Plugin).

You might want to take an existing implementation as a template.

Parameters:

  • $answer - The correct answer for the captcha

  • $hash - The hash of the correct answer

  • $templ - Path to the template to display the captcha

CONFIGURATION

You may control the behaviour of this plugin with some settings. Defaults:

captcha/type           text
captcha/template_path  /templates/captcha/
captcha/ask_once       1
captcha/dont_ask_users 1

METHODS

init

Inititalization of this class

check

Checks if the user answer matches the captcha question. This is done by hashing the user answer and comparing it to the hashed correct answer.

Returns true, if the answer is correct.

Parameters: none

install

Installs the templates.

Parameters:

none

default :Action

Default (and only) action for this plugin. Will display the captcha according to the attributes set in the <& captcha / &> tag.

The attributes are optional. Their value defaults are defined in the settings.

Tag attributes:

  • type - Optional: The type of the captcha. Currently only "text" captchas are implemented. Defaults to the setting captcha/type).

  • template - Optional: The path to the template to display the captcha. Defaults to "captcha/template_path $type .template". The variables answer and hash will be passed to your template.

Parameters:

  • $tag - Reference to the tag (and its children) that shall be handled.

  • $content - The content below/inside the tag as a flat string.

  • $params - Reference to a hash of the passed CGI parameters.

solve :Action

This is a demo/debug action, which allows you to test your captcha.

Just put this code on a web page:

<form action="" method="post">
	<input type="hidden" name="captcha_action" value="solve" />
	<& captcha / &>
	<input type="submit" value="Check" />
</form>

Okay, this is some kind of a dirty hack, but it should work for test purposed.

AUTHOR

Copyright 2006 Thomas Wittek (mail at gedankenkonstrukt dot de). All rights reserved.

This document is free software. It is distributed under the same terms as Perl itself.

SEE ALSO

Konstrukt::SimplePlugin, Konstrukt