Scratchcard.js

Mimic a scratchcard with HTML5.

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

Scratchcard methods

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

Painter methods

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.

Limitations

Currently, Scratchcard.js does not work as expected when attached to elements with borders and/or margins (padding is OK).

Dependencies

Scratchcard.js depends on lodash.defaults.

The animation-frame dependency is only used for the scratchcard-standalone bundle.

Contributors

• Cédric Connes: original author
• Unitag: various contributions, especially tests

License

MIT