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 © 2015 David Heidrich

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

Related Repositories

marklib

marklib

A small library to wrap serializable TextSelections. ...


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