Scratchcard NPM

Scratchcard.js

Mimic a scratchcard with HTML5.

Bower version

Installation

The scratchcard package can be installed through Bower or npm.

Alternatively, the following bundles are available in the dist directory:

scratchcard[.min].js wraps the scratchcard module, including its dependencies.
scratchcard-standalone[.min].js wraps the scratchcard module, including its dependencies and the animation-frame shim for a maximal compatibility (see below).

Get started

CommonJS (Browserify)

var Scratchcard = require('scratchcard');

var scratchcard = new Scratchcard(document.getElementById('hidden-content'));

scratchcard.on('progress', function onProgress(progress) {
    console.log('Progress: ' + Math.floor(progress * 100) + '%');
});

AMD (RequireJS)

require.config({
    paths: {
        scratchcard: 'path/to/scratchcard',
    }
});

define(['scratchcard'], function (Scratchcard) {
    var scratchcard = new Scratchcard(document.getElementById('hidden-content'));

    scratchcard.on('progress', function onProgress(progress) {
        console.log('Progress: ' + Math.floor(progress * 100) + '%');
    });
});

Browser

<script src="path/to/scratchcard.js"></script>
<script>
    var scratchcard = new Scratchcard(document.getElementById('hidden-content'));

    scratchcard.on('progress', function onProgress(progress) {
        console.log('Progress: ' + Math.floor(progress * 100) + '%');
    });
</script>

API

TL;DR: for a working example, see the example directory (live demo).

Scratchcard class

The scratchcard module exposes the Scratchcard class as its single entry point:

var scratchcard = new Scratchcard(element, options);

The given DOM element is immediately covered with an HTML5 canvas, and its visibility is set to visible. In order to prevent your content from being revealed too early, ensure that the visibility of the DOM element is set to hidden by default.

The options parameter is optional. It can be either a raw object (see below) or a Painter instance.

Scratchcard options

Name	Type	Description	Default
`threshold`	Integer between 0 and 255	The minimal alpha value for considering a pixel as revealed.	`255` (only fully transparent pixels are considrered as revealed)
`realtime`	Boolean	Whether to report the `progress` events during the user interaction (dynamically), or only when when the user releases the scratchcard. Enabling this option may affect performances on some devices.	`false` (fastest interaction)
`layers`	Positive integer	The number of layers to be inserted below the scratchcard.	`0`
`painter`	A `Painter` instance or a raw object	The painter to be used, or a set of options to be passed to the default `Painter` constructor.	`{}` (default painter)
`animationFrame`	An object defining a `request` method	An alternative implementation for the native `requestAnimationFrame` API. An instance of the `animation-frame` module fits perfectly here, but feel free to provide the implementation of your choice.	`null` (native implementation)

Scratchcard methods

Signature	Description
`getElement`	Retrieve the attached DOM element.
`setElement(element)`	Attach this scratchcard to another DOM element. Pass `null` to detach this scratchcard from the DOM.
`getPainter`	Retrieve the current painter.
`setPainter(painter\|options)`	Replace the current painter by the given one. If the given parameter is not a `Painter` instance, it is passed as options to the default `Painter` constructor.
`getWrapper`	Retrieve the wrapper element.
`getCanvas`	Retrieve the canvas element.
`reset`	Reset this scratchcard.
`complete`	Reveal the content of this scratchcard.
`getProgress`	Compute the current scratching progress.

Painter class

A Painter instance allow to control how things are drawn on the canvas element. A default implementation is accessible through Scratchcard.Painter:

var painter = new Scratchcard.Painter(options);

You can either:

use the default implementation (eventually with custom options)
patch an instance of the default implementation (on the fly) to add some custom behavior
subclass the default implementation to define your very own drawing logic

Default painter options

Name	Type	Description	Default
`color`	Color	The inital color of the scratchcard	`'silver'`
`thickness`	Positive integer	The thickness of a scratching path	`50`

Painter methods

Signature	Description
`reset(ctx, width, height)`	(Re)set the scratchcard to its initial state.
`drawPoint(ctx, point)`	Draw the initial point of a scratching path.
`drawLine(ctx, start, end)`	Draw a segment between two points of a scratching path.
`complete(ctx, width, height)`	Force the scrathcard to its final state.
`drawLayer(ctx, width, height, index)`	Draw the given layer.

Compatibility

Scratchcard.js is intended to work on all major browsers (desktop & mobile), except Internet Explorer prior to version 9.

However, Scratchcard.js heavily relies on the requestAnimationFrame API, which is not always available, especially on mobile browsers. Thus, although optional, using a strong shim like animation-frame is recommended to reach a maximal compatibility level.

For convenience, the scratchcard-standalone[.min].js bundle does include the animation-frame shim by default.