Skip to content

Latest commit

 

History

History
106 lines (78 loc) · 3.97 KB

README.md

File metadata and controls

106 lines (78 loc) · 3.97 KB
Raw

Jerboa.js

Build Status Code Climate Test Coverage

jerboa.js

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({
    active:           false             //Start with feedback toggle engaged, or disengaged
    data:             {},               // Custom data that is included in the annotation object
    points:           [],               // Pre-populates the page with this array of annotation objects
    currentUser:      'John Perkins',   // Display name of current user
    currentUserId:    '259837',         // User's Id
    isAdmin:          'false',          // true or false, determines auth for changing status and owner of annotations
    positioning:      'PERCENT',        // Valid values are 'PIXEL' and 'PERCENT'
    strategy:         jerboa.strategies.global // Determines what element(s) is chosen to be the container
});

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

Value Behavior
percent Locations are saved as x/y percentages within the container. Works well when the container scales.
pixel Locations 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:

Value Behavior
jerboa.strategies.global Uses 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, to save a new annotation
  • cancel - Fires when the user clicks the Cancel button
  • saveComment - Fires when the user saves a reply comment
  • cancelComment - Fires when the user cancels a reply comment
  • saveEdittedComment - Fires when the user saves an edit to a comment comment
  • deleteComment - Fires when the user deletes a reply comment
  • changeOwner - Fires when the user changes the owner of an annotation
  • changeStatus - Fires when the user changes the status of an annotation
  • active - Fires when feedback toggle is changed. The value of the event indicates the state.

Developed with ❤️ by the folks at Experticity