1.0.1 • Published 8 years ago

jerboa v1.0.1

Weekly downloads
1
License
ISC
Repository
github
Last release
8 years ago

Jerboa.js

Build Status Code Climate Test Coverage

Annotate and provide feedback on any web page. View it in action. Jerboa.js is small (jerboa.min.js is ~6kb and jerboa.min.css is ~2kb) and has absolutely no dependencies so it's easy to use anywhere!

Usage

Include it:

<link rel="stylesheet" href="https://cdn.rawgit.com/camman3d/jerboa.js/master/dist/jerboa.min.css" />
<script src="https://cdn.rawgit.com/camman3d/jerboa.js/master/dist/jerboa.min.js"></script>

Initialize it:

jerboa.init();

Use it!

Configuration

jerboa.init({
    data: {},               // Custom data that is included in the annotation object,
    points: [],             // Pre-populates the page with this array of annotation objects
    user: 'John Perkins',   // Display name of current user
    positioning: 'percent', // Valid values are 'pixel' and 'percent' 
    strategy: jerboa.strategies.global 
});

The positioning configuration option determines how annotation locations are saved. The different values are:

ValueBehavior
percentLocations are saved as x/y percentages within the container. Works well when the container scales.
pixelLocations are saved as x/y pixel offsets within the container.

The strategy configuration option determines what elements is chosen to be the container. The value is a function with the following signature:

(element) => boolean

When the user clicks on the page, jerboa navigates up the DOM tree from the clicked element checking each element with the provided strategy. This function acts as filter; it returns true when the element qualifies as a container. If no element qualifies as the container then no annotation is created.

Jerboa.js comes with the following strategies:

ValueBehavior
jerboa.strategies.globalUses the body element as the container.
jerboa.strategies.byClass('some-class-name')Uses the first ancestor with the some-class-name class.

You can also provide your own strategy function:

jerboa.init({
    strategy: function (element) {
        return element.dataset.isContainer;
    }
});

Events

To handle saving, listen for the save event:

jerboa.addEventListener('save', function (annotation) {
    console.log(annotation);
});

Listenable events are:

  • preAnnotate - Fires when the user a spot to annotate
  • save - Fires when the user clicks the Save button
  • cancel - Fires when the user clicks the Cancel button
  • cancelReply - Fires when the user cancels a reply comment
  • saveReply - Fires when the user saves a reply comment

Developed with ❤️ by the folks at Experticity