The recaptcha element produces a recaptcha element. For more information about recaptchas you may refer to https://developers.google.com/recaptcha/
The element is rendered and evaluated by an external library.
The captcha is processed as follows:
- The user solves the captcha.
- If the solution is wrong the captcha gets refreshed until the user
gives up or the solution is correct, and a
Page:recaptcha_event
is called with aResult
oferror
. - If the solution is correct the
Page:recaptcha_event
callback is called with aResult
ofok
. - The return value of the
Page:recaptcha_event
callback is evaluated as follows: - If the value is
ok
nothing is done. - If the return value is
error
, the captcha gets refreshed. - If the return value is
{error, Msg}
, the captcha gets refreshed and the Msg is shown as the error message.
Before you can use the the recaptcha element, you have to register at https://www.google.com/recaptcha/admin/create.
After that, you have to either specify the following values in your
app.config or specify them as attributes to the #recaptcha{}
element
itself.
[
{nitrogen, [
{recaptcha,
[{public_key, "recaptcha_public_key"},
{private_key, "recaptcha_private_key"},
{challenge_url, "http://www.google.com/recaptcha/api/challenge"},
{verify_url, "http://www.google.com/recaptcha/api/verify"}]}
...
]},
...
].
#recaptcha {
public_key="some_public_key",
private_key="some_private_key"
}
The following attributes are required unless they are defined as nitrogen environment variables above.
public_key
(string) - Public key provided by the Recaptcha service.private_key
(string) - Private key provided by the Recaptcha service.
tag
(term) - The "tag" for the recaptcha element to be passed to therecaptcha_event/2
functionbutton_id
(atom) - The button's idbutton_label
(string) - The button's labelbutton_class
(string, atom, or list of atoms) - The button's HTML class.captcha_opts
(proplist) - The captcha's options. For more information see the official Recaptcha Documentationcustom_theme_widget
is not supported- delegate (Module) :: The module where the event callback gets called
- fail_body (List) :: The fail message. It can be a simple string or an array of Nitrogen elements. It will be displayed below the recaptcha if the user fails to enter the correct recaptcha.
challenge_url
(string) - The challenge URL as specified in the Recaptcha Documentation (default: https://www.google.com/recaptcha/api/challenge")verify_url
(string) - The verification URL as specified in the Recaptcha Documentation (default: https://www.google.com/recaptcha/api/verify")
When a recaptcha succeeds or fails, the recaptcha_event/2
function
is called on your page module. Tag
will be from the tag
attribute above,
and Result
will be a status atom, either ok
if successful, or
{error, ErrorMessage}
if the recaptcha fails.
recaptcha_event/2
can return any of the following:
ok
- Everything is okay.error
- There was something that failed (maybe you did some data validation in theevent_recaptcha/2
function and something failed so let's just return an error.{error, ErrorMessage}
- Something went wrong, and let's set the error message to the contents ofErrorMessage
(which, likefail_body
above, can be either text or Nitrogen elements).
recaptcha_event(_Tag, ok) ->
wf:wire(#alert{text="Congrats, you're human"}),
ok;
recaptcha_event(_Tag, {error, ErrorReason}) ->
wf:wire(#alert{text="WE THINK YOU'RE A ROBOT! YOU MUST PROVE OTHERWISE!"}),
{error, "Please Try again!"}.
If you wish to trigger validators before the Recaptcha gets used, you'll
need to wire the validators to the Recaptcha's button_id
attribute.
You can see this in use in the example below:
Code in a page module may look like this:
inner_body() ->
%% Wire a validator to be triggered by `recaptcha_button`, and target `name`
wf:wire(recaptcha_button, name, #validate{ validators=[
#is_required{}
]}),
[
#label{text="Enter your name"},
#textbox{id=name},
#recaptcha{
button_id=recaptcha_button,
id=recaptcha,
tag=my_recaptcha,
captcha_opts=[{theme,white}]
}
].
event_recaptcha(my_recaptcha, ok) ->
case check_user_input() of
ok -> wf:remove(recaptcha),
ok;
error -> {error, "FAIL!"}
end.
check_user_input() ->
%% your check routine