Usage

You can use this component to show users a captcha, like the one shown in the following screen shot:

1. First, you need to sign up with reCAPTCHA to get your own public/private key pair.
   
2. Store your public and private keys in an instance:
   
   
   <xforms:instance id="config">
    <config>
        <public-key>6Lesx...</public-key>
        <private-key>6Lesx...</private-key>
    </config>
</xforms:instance>
   
   If you are using a captcha in multiple forms, you might want to store your public and private key in a separate "config" file which you include into your form.
   
   
3. Add the reCAPTCHA component to your form:
   
   
   <fr:recaptcha id="recaptcha">
    <fr:public-key ref="instance('config')/public-key"/>
    <fr:private-key ref="instance('config')/private-key"/>
    <xforms:send ev:event="fr-verify-done" submission="save-submission"/>
    <xforms:action ev:event="fr-verify-error">
        <xforms:toggle case="failure-case"/>
        <xforms:dispatch target="recaptcha" name="fr-reload"/>
    </xforms:action>
</fr:recaptcha>
   
   
• Provide the value of the public and private keys with a <fr:public-key ref="..."/> and <fr:private-key ref="..."/>.
• When the verification succeeds, you get the fr-verify-done event. The example above listens to that event to run a submission.
• When the verification fails, you get the fr-verify-error event. The example above listens to that event to show a case id failure-case (which might tell users the verification failed). As part of the context information for this event, you can access with event('fr-error-code') the error code returned by the reCAPTCHA API. The error code is a string. Its value can either be:
• empty — this tells you users didn't provide any answer. When that happens, you could notify users and keep the same challenge.
  
• One of the values listed in the reCAPTCHA API documentation (look for the table under Error Code Reference). When this happens, you could notify users, and need to change the challenge by dispatching fr-reload to the reCAPTCHA.
  
  
4. Add way for users to trigger the verification of the text typed, for instance:
   
   
   <xforms:trigger>
    <xforms:label>Verify</xforms:label>
    <xforms:dispatch ev:event="DOMActivate" target="recaptcha" name="fr-verify"/>
</xforms:trigger>
   
   The verification happens when the component receives the fr-verify event. You can dispatch this even to the component in any way you want, but most cases will do so when the user activates a trigger.

Configuration

You can configure:

• The theme, with the theme property.
• The language, with the lang property.
  

See the reCAPTCHA documentation, under Look & Feel Customizations for more information on the possible values for the theme and lang properties. Just as with other properties, you can provide a static value using attributes:


Or you can use nested elements if the values come from an instance: