npmjs_readme.markd

## BotDetect CAPTCHA AngularJS Module (JavaScript: Angular 1.x)

For a comprehensive step-by-step integration guide please see our [AngularJS Captcha Module Integration Guide](https://captcha.com/angular-captcha.html#angularjs-captcha).  
The guide covers the integration with the following backends:
- ASP.NET (Core): web API with MVC6
- ASP.NET (Legacy): Web-API2, MVC1-5, Generic Handler
- Java: Servlet, Spring, Struts
- PHP: the plain PHP

To give you a hint how AngularJS Captcha Module works we pasted a few, not necessary up-to-date (and mostly frontend related), excerpts from it bellow.

### Quick guide:

##### 1) AngularJS Captcha Module Installation

```sh
npm install angularjs-captcha --save
```

##### 2) Include AngularJS Captcha Module in Your App

```html
<script src="node_modules/angularjs-captcha/dist/angularjs-captcha.min.js"></script>
```

##### 3) Inject AngularJS Captcha Module to Your AngularJS App, and Configure Backend Captcha Endpoint

Endpoint configuration depends on which technology you use in the backend.

- ASP.NET-based captcha endpoint:
```javascript
var app = angular.module('app', ['BotDetectCaptcha']);

app.config(function(captchaSettingsProvider) {
  ...

  captchaSettingsProvider.setSettings({
    captchaEndpoint: 
      'https://your-app-backend-hostname.your-domain.com/simple-captcha-endpoint.ashx'
  });
});
```

- Java-based captcha endpoint:
```javascript
var app = angular.module('app', ['BotDetectCaptcha']);

app.config(function(captchaSettingsProvider) {
  ...

  captchaSettingsProvider.setSettings({
    captchaEndpoint: 
      'https://your-app-backend-hostname.your-domain.com/simple-captcha-endpoint'
  });
});
```

- PHP-based captcha endpoint:
```javascript
var app = angular.module('app', ['BotDetectCaptcha']);

app.config(function(captchaSettingsProvider) {
  ...

  captchaSettingsProvider.setSettings({
    captchaEndpoint: 
      'https://your-app-backend-hostname.your-domain.com/botdetect-captcha-lib/simple-botdetect.php'
  });
});
```

##### 4) Display Captcha In Your AngularJS Template

```html
<botdetect-captcha captchaStyleName="yourFirstCaptchaStyle"></botdetect-captcha>
<input id="userCaptchaInput"
  type="text" 
  name="userCaptchaInput"
  ng-model="userCaptchaInput" >
```

##### 5) Captcha Validation: Client-side Code

```javascript
app.controller('YourFormWithCaptchaController',
    function ($scope, $http, $window, Captcha) {

  // process the form on submit event
  $scope.validate = function () {

    // create new AngularJS Captcha instance
    var captcha = new Captcha();

    // get the user-entered captcha code value to be validated at the backend side        
    var userEnteredCaptchaCode = captcha.getUserEnteredCaptchaCode();

    // get the id of a captcha instance that the user tried to solve
    var captchaId = captcha.getCaptchaId();

    var postData = {
      // add the user-entered captcha code value to the post data
      userEnteredCaptchaCode: userEnteredCaptchaCode,
      // add the id of a captcha instance to the post data
      captchaId: captchaId
    };

    // post the captcha data to the /your-app-backend-path on your backend
    $http({
      headers: { 'Content-Type': 'application/json; charset=utf-8' }
      method: 'POST',
      url: 'https://your-app-backend-hostname.your-domain.com/your-app-backend-path',
      data: postData
    })
      .then(function (response) {
        if (response.data.success == false) {
          // captcha validation failed; reload image
          captcha.reloadImage();
          // TODO: maybe display an error message, too
        } else {
          // TODO: captcha validation succeeded; proceed with the workflow
        }
      }, function (error) {
        throw new Error(error.data);
      });
  };
});
```

##### 6) Captcha Validation: Server-side Code

The `userEnteredCaptchaCode` and `captchaId` values posted from the frontend are used to validate a captcha challenge on the backend.

The validation is performed by calling the: `Validate(userEnteredCaptchaCode, captchaId)`.

- Server-side Captcha validation with [ASP.NET Captcha](https://captcha.com/asp.net-captcha.html) looks in this way:
```csharp
// C#
SimpleCaptcha yourFirstCaptcha = new SimpleCaptcha();
bool isHuman = yourFirstCaptcha.Validate(captchaCode, captchaId);
```
```vbnet
' VB.NET
Dim yourFirstCaptcha As SimpleCaptcha = New SimpleCaptcha()
Dim isHuman As Boolean = yourFirstCaptcha.Validate(captchaCode, captchaId)
```

- Server-side Captcha validation with [Java Captcha](https://captcha.com/java-captcha.html) looks in this way:
```java
SimpleCaptcha yourFirstCaptcha = SimpleCaptcha.load(request);
boolean isHuman = yourFirstCaptcha.validate(captchaCode, captchaId);
```

- Server-side Captcha validation with [PHP Captcha](https://captcha.com/php-captcha.html) looks in this way:
```php
$yourFirstCaptcha = new SimpleCaptcha();
$isHuman = $yourFirstCaptcha->Validate($captchaCode, $captchaId);
```

### Documentation:

1. [AngularJS Captcha Module Step-by-step Integration Guide](https://captcha.com/angular-captcha.html#angularjs-captcha) -- read this one first

2. [AngularJS Captcha Module Basic Example](https://captcha.com/doc/angular/examples/angular-basic-captcha-example.html#angularjs-captcha) -- partial code walk-through

3. [AngularJS Captcha Module Form Example](https://captcha.com/doc/angular/examples/angular-form-captcha-example.html#angularjs-captcha) -- partial code walk-through

### Dependencies:

The current version of the AngularJS Captcha Module requires one of the following BotDetect CAPTCHA backends:
- [ASP.NET v4.4.1+](https://captcha.com/asp.net-captcha.html)
- [Java v4.0.Beta3.6+](https://captcha.com/java-captcha.html)
- [PHP v4.2.4+](https://captcha.com/php-captcha.html)

### Technical Support:

Through [contact form on captcha.com](https://captcha.com/contact.html).