Quick links: Content - sections - sub sections
EN FR
Developer manual
Jelix 1.8.1

Section: Captcha

^ Creating a jforms file HTML editor »
Switch to language: FR

− Table of content

To include a captcha into a jForms form, you have to use the <captcha> element:


 <captcha ref="antispam">
    <label>Are you an human?</label>
 </captcha>

Choosing the type of captcha

There are many kind of Captcha available in the web. Jelix provides two type of captcha, but you can use any other captcha if you create the plugin for jForms (see below). We can call it, a validator.

To indicate the type of captcha, you should indicate its name :

  • in a validator attribute on <captcha>
  • or in the configuration parameter captcha in the section [forms] of the Jelix configuration, so all captcha of your site will be of this type.

Example:


 <captcha ref="antispam" validator="simple">
    <label>Anti-spam</label>
 </captcha>

or


[forms]
captcha=simple

For the moment, only two captcha type are provided into Jelix: "simple" and ReCaptcha.

Simple captcha

This is the default captcha type. It shows a simple text field in which the user should give a response to a simple question asked by jForms.

Questions and answers are stored in a locale file, in the module jelix. For example, for english questions, this is lib/jelix/core-modules/jelix/locales/en_US/captcha.UTF-8.properties. This file contains a first locale, number, which contains the number of question. And it is followed by locales which contain the questions and the answers. You can redefine this file to add or modify questions/answers. See the chapter on the redefinition of files.

To use it, you don't have to set the configuration as it is the default captcha type. Or you can indicate "simple":


<captcha ref="antispam" validator="simple">
 <label>Anti-spam</label>
</captcha>

or 


[forms]
captcha=simple

ReCatpcha

This type of captcha displays the captcha solution of Google: ReCaptcha. You have to have a ReCaptcha account. See the web site of ReCaptcha.

When you have a ReCaptcha account, Google gives you a site key and a secret.

You need to indicate them into the Jelix configuration:


[recaptcha]
; sitekey and secret should be set only into localconfig.ini.php!
sitekey= here_the_public_key
secret= here_the_private_key
  • *Warning**: as the secret is a private information, you should not store it into your source code repository, so not into the mainconfig.ini.php file. So you must store the [recaptcha] section into the localconfig.ini.php file.

Other parameters are possible, to configure ReCaptcha, like the theme, the size or the type (see the ReCaptcha web site).


[recaptcha]
; sitekey and secret should be set only into localconfig.ini.php!
sitekey= here_the_public_key
secret= here_the_private_key

; see https://developers.google.com/recaptcha/docs/display to know the meaning
; of these configuration parameters.
theme=
type=
size=
tabindex=

When this setup is done, you can use ReCaptcha, by indicating "recaptcha" into the validator attribute or in the main configuration:


 <captcha ref="antispam" validator="recaptcha">
    <label>Anti-spam</label>
 </captcha>

or


[forms]
captcha=recaptcha

Configuring an other type of captcha

You can choose other type of captcha, but you have to develop two things:

  1. a widget for jForms, to display the captcha
  2. a class to validate the captcha

The first thing to do is to choose a name for your type. Let's say "mycap".

Create the widget

Create a widget into plugins/formwidget/mycap_html/mycap_html.formwidget.php.

In the class of the widget, you should implement:

  • outputMetaContent() to load JS and CSS resources
  • outputJs() to generate some inline JS code if needed
  • outputControl() to generate HTML

See simple and recaptcha. widgets as example.

Create the validation class

You should create a class in one of your module. Let's say \MyApp\MycapValidator. It should be auto-loadable.

The class must implements the interface jelix\forms\Captcha\CaptchaValidatorInterface, so it must implements these two methods:

  • initOnDisplay(): will be called during the widget display, if you do $this->ctrl->initCaptcha() in the outputControl() method of the widget. This method can returns some data needed by the widget or by the validator. These data are stored in the PHP session.
  • validate($value, $internalData), will be called by jForms to validate the response of the user ($value). $internalData is data returned by initOnDisplay().

See the validator for "simple" and the validator for recaptcha as examples.

Declare the new type of captcha

When the classes are created, you must declare them into the configuration, via two configuration parameters into the [forms] section:

  • captcha.<typecaptcha>.validator to indicate the validation class
  • captcha.<typecaptcha>.widgettype to indicate the widget name (without "_html")

With our example above:


captcha.mycap.validator = "\MyApp\MycapValidator"
captcha.mycap.widgettype = mycap

Then you can use your new captcha:


 <captcha ref="antispam" validator="mycap">
    <label>Anti-spam</label>
 </captcha>

ou


[forms]
captcha=mycap
^ Creating a jforms file HTML editor »
Switch to language: FR
This manual is distributed under the terms of licence Creative Commons by-nc-sa 3.0. Therefore you're allowed to copy, modify and distribute and transmit it publicly under the following conditions: Attribution, Noncommercial, Share Alike.