marklib

Circle CI Codacy Badge Coverage Status npm Join the chat at https://gitter.im/BowlingX/marklib

A simple and fast zero-dependencies-library to transform text-selections into serializable markings.

Demo

Demo-Gif

Install

marklib can be installed with npm or bower.

npm install --save-dev marklib

bower install marklib --save

Usage

Render by selection


// obtain a selection from document
var selection = document.getSelection();

// create a new rendering based on the current document
var renderer = new Marklib.Rendering(document, options, context)
renderer.setId('myRenderId') // if an ID is not provided, a autogenerated one will be used

// renders the given selection and returns a result (`RenderResult`).
var result = renderer.renderWithRange(selection.getRangeAt(0));

Important: After a Rendering has been used to render a selection/serialized result, it can't be used to render something again. You need to create a new Instance of Rendering.

Options

You can pass options to each rendering instance, the following shows the default options


var renderer = new Marklib.Rendering(document, {
            hoverClass: 'marklib--hover',
            treeClass: 'marklib--tree',
            // Supports arrays and/or strings
            className: ['marking']
});

Events

Marklib triggers events that can be listened to with instance.on('event-name'). Events are build with wolfy87-eventemitter (https://github.com/Olical/EventEmitter). The following Events are available:

Before you can actually receive events, you need to register the event handler with registerEvents

Event-Name Description Arguments
click triggered when clicked on a marking. (originalEvent, instanceHierarchy)
hover-enter triggered when a pointer-device starts hovering over a marking (originalEvent, instanceHierarchy)
hover-leave triggered when a pointer-device leaves a marking (originalEvent, instanceHierarchy)

Additionally, marklib will add hover classes to the current hovered marking.

Constructor Arguments

  • 1) HTMLDocument document -> the document instance used
  • 2) Object [options], optional -> an object containing setting for marklib (see Options)
  • 3) HTMLElement [context], optional -> the context used to serialize / deserialize the rendering, if not given the document instance.

Render by serialized result

A Serialized results consist of 2 strings (start end end) in the following form


'body>section;0;1'`
-▲------------▲-▲ 
  • ▲ The first part defines a css-selector (queryable with document.querySelector).
  • ▲ The second part defines the text-node inside the given selector
  • ▲ The third part defines the string-offset inside this text-node

Example


 // This is the result we get from `RenderResult#serialize()`

 var result = {
    startContainerPath: 'body>section;0',
    endContainerPath: 'body>section;1',
    startOffset: 2,
    endOffset: 5
 }

 var rendering = new Marklib.Rendering(document);

 rendering.renderWithResult(result);

Use-Cases

Develop

npm run develop or npm run tdd (to start karma in watch mode)

License

The MIT License (MIT)

Copyright (c) 2015 David Heidrich

Any contribution is welcome, just issue a pull-request or bug/feature if you found something :)


Top Contributors

BowlingX tanertopal gitter-badger

Releases

-   v0.10.0 zip tar
-   v0.9.0 zip tar
-   v0.8.0 zip tar
-   v0.7.3 zip tar
-   v0.7.2 zip tar
-   v0.7.1 zip tar
-   v0.7.0 zip tar
-   v0.6.6 zip tar
-   v0.6.5 zip tar
-   v0.6.4 zip tar
-   v0.6.3 zip tar
-   v0.6.2 zip tar
-   v.0.6.1 zip tar
-   v.0.6.0 zip tar
-   v.0.5.0 zip tar
-   v.0.4.7 zip tar
-   v.0.4.6 zip tar
-   v.0.4.5 zip tar
-   v.0.4.4 zip tar
-   v.0.4.3 zip tar
-   v.0.4.2 zip tar
-   v.0.4.1 zip tar
-   v0.4.0 zip tar