ng2-recaptcha-fallback
Version:
Angular 2 component for Google reCAPTCHA
195 lines (146 loc) • 6.28 kB
Markdown
# Angular 2 component for Google reCAPTCHA
## ng2-recaptcha [](http://badge.fury.io/js/ng2-recaptcha)
[](https://raw.githubusercontent.com/dethariel/ng2-recaptcha/master/LICENSE)
[](https://travis-ci.org/DethAriel/ng2-recaptcha)
[](https://david-dm.org/dethariel/ng2-recaptcha?type=dev)
A simple, configurable, easy-to-start component for handling reCAPTCHA.
## Installation
The easiest way is to install trough [npm](https://www.npmjs.com/package/ng2-recaptcha):
```
npm i ng2-recaptcha --save
```
In order to take advantage of type-checking system you should also install `grecaptcha` typings:
```
typings install dt~grecaptcha --save --global
```
Or, if you're using TypeScript 2 or `angular-cli`:
```
npm install @types/grecaptcha --save-dev
```
## <a name="example-basic"></a>Usage [(see in action)](https://dethariel.github.io/ng2-recaptcha/basic)
To start with, you need to add one of the `Recaptcha` modules (more on that [later](#modules)):
```typescript
import { RecaptchaModule } from 'ng2-recaptcha';
import { BrowserModule } from '@angular/platform-browser';
@NgModule({
bootstrap: [MyApp],
declarations: [MyApp],
imports: [
BrowserModule,
RecaptchaModule.forRoot(), // Keep in mind the "forRoot"-magic nuances!
],
})
export class MyAppModule { }
```
Once you have done that, the rest is simple:
```typescript
import { platformBrowserDynamic } from '@angular/platform-browser-dynamic';
import { Component } from '@angular/core';
@Component({
selector: 'my-app',
template: `<recaptcha (resolved)="resolved($event)" siteKey="YOUR_SITE_KEY"></recaptcha>`,
}) export class MyApp {
resolved(captchaResponse: string) {
console.log(`Resolved captcha with response ${captchaResponse}:`);
}
}
platformBrowserDynamic().bootstrapModule(MyAppModule);
```
## <a name="modules"></a>Modules: "Forms"-ready and "No-forms"
There are two modules available for you:
```typescript
import { RecaptchaModule } from 'ng2-recaptcha';
import { RecaptchaNoFormsModule } from 'ng2-recaptcha/ng2-recaptcha.noforms';
```
The difference between them consists in dependencies - `RecaptchaModule` depends on
`@angular/forms`, while `RecaptchaNoFormsModule` does not. If you do not rely on
Angular 2 forms in your project, you should use the "no-forms" module version, as
it does not require the `@angular/forms` package to be bundled with your code.
## Options
The component supports this options:
* `siteKey`
* `theme`
* `type`
* `size`
* `tabIndex`
They are all pretty well described in the [reCAPTCHA docs](https://developers.google.com/recaptcha/docs/display),
so I won't duplicate it here.
## Events
* `resolved(response: string)`. Occurs when the captcha resolution value changed.
When user resolves captcha, use `response` parameter to send to the server for verification.
This parameter is equivalent to calling [`grecaptcha.getResponse`](https://developers.google.com/recaptcha/docs/display#js_api).
If the captcha has expired prior to submitting its value to the server, the component
will reset the captcha, and trigger the `resolved` event with `response === null`.
## Methods
* `reset`. Performs a manual captcha reset. This method might be useful if your form
validation failed, and you need the user to re-enter the captcha.
## <a name="example-language"></a>Specifying a different language [(see in action)](https://dethariel.github.io/ng2-recaptcha/language)
`<recaptcha>` supports various languages. But this settings is global, and cannot be set
on a per-captcha basis. This can be overridden by providing your own instance of
`RecaptchaLoaderService` for a particular module:
```typescript
import { RecaptchaLoaderService } from 'ng2-recaptcha';
@NgModule({
providers: [
{
provide: RecaptchaLoaderService,
useValue: new RecaptchaLoaderService("fr"), // use French language
},
],
}) export class MyModule { }
```
You can find the list of supported languages in [reCAPTCHA docs](https://developers.google.com/recaptcha/docs/language).
## <a name="example-preload-api"></a>Loading the reCAPTCHA API by yourself [(see in action)](https://dethariel.github.io/ng2-recaptcha/preload-api)
By default, the component assumes that the reCAPTCHA API loading will be handled
by the `RecaptchaLoaderService`. However, you can override that by providing your
instance of this service to the Angular DI.
The below code snippet is an example of how such a provider can be implemented.
**TL;DR**: there should be an `Observable` that eventually resolves to a
`grecaptcha`-compatible object (e.g. `grecaptcha` itself).
```html
<script src="https://www.google.com/recaptcha/api.js?render=explicit&onload=onloadCallback"></script>
<script>
// bootstrap the application once the reCAPTCHA api has loaded
function onloadCallback() {
System.import('app').catch(function(err) { console.error(err); });
}
</script>
```
```typescript
import { RecaptchaLoaderService } from 'ng2-recaptcha';
@Injectable()
export class PreloadedRecaptchaAPIService {
public ready: Observable<ReCaptchaV2.ReCaptcha>;
constructor() {
let readySubject = new BehaviorSubject<ReCaptchaV2.ReCaptcha>(grecaptcha);
this.ready = readySubject.asObservable();
}
}
@NgModule({
providers: [
{
provide: RecaptchaLoaderService,
useValue: new PreloadedRecaptchaAPIService(),
},
],
}) export class MyModule { }
```
## <a name="example-forms"></a>Usage with `required` in forms [(see in action)](https://dethariel.github.io/ng2-recaptcha/forms)
It's very easy to put `recaptcha` in an Angular2 form and have it `require`d - just
add the `required` attribute to the `<recaptcha>` element
```typescript
@Component({
selector: 'my-form',
template: `
<form>
<recaptcha
[(ngModel)]="formModel.captcha"
name="captcha"
required
siteKey="YOUR_SITE_KEY"
></recaptcha>
</form>`,
}) export class MyForm {
formModel = new MyFormModel();
}
```