MASHA

MASHA (short for Mark & Share) is a JavaScript utility allowing you to mark interesting parts of web page content and share it. Just select text (paragraphs, sentences, words) on MASHA powered page and copy generated URL from location bar. Opening of that url will open the page with same content and restored marks. Try it on this page!

This feature was developed for official site of President of Russia. After some months of active use it was published under MIT license.

MASHA-powered sites

The official site of the President of Russia

The site of TV-channel “NTV”

Web developers festival "404"

YOU?

Please contact us

INSTALLATION

MASHA is available by npm:

                        npm install --save masha

Or you can download package archive:

MASHA_ALL.ZIP
ver. 1.1.3 js + css + image MASHA_LOGO.ZIP (315Kb)
logo (eps, ai, psd) © Mikhail Zhashkov

USAGE

MASHA has been written in clean JavaScript and does not have any framework dependencies (except bundled ierange library that included to support Internet Explorer browser).

To enable MASHA on your page you need to add inside <head></head> tag that code:

                        <script type="text/javascript" src="masha.js"></script>
                        <link rel="stylesheet" type="text/css" href="masha.css">
                        <script type="text/javascript">
                        // if jQuery is not available
                        if(window.addEventListener){     
                            window.addEventListener('load', function(){
                                // can be called by domready
                                MaSha.instance = new MaSha();
                            }, false);
                        } else {
                            window.attachEvent('onload', function(){
                                // can be called by domready
                                MaSha.instance = new MaSha();
                            });
                        }
                        // if jQuery available:
                        $(document).ready(function() {
                            MaSha.instance = new MaSha();
                        });
                        </script>

For es2016/CommonJS import the class from the package:

                        import { MaSha } from "masha";
                        // or
                        var MaSha = require("masha").MaSha;

MASHA uses three elements on the page:

Element that contains selectable text (see also selectable option below), required.
Button that floats over selected text that acts as selection url getter (see also marker option).
Popup that floats when a text is selected and tells user that he can now share a link (see also selectMessage option).

All options are defined by default, but you can override any of them on Masha object instance creation.

                        new MaSha({  option: 'value' })

The default setting are:

                        {
                          'regexp': '[^\\s,;:–.!?<>…\\n\xA0\\*]+',
                          'selectable': 'selectable-content',
                          'marker': 'txtselect_marker',
                          'ignored': null,
                          'selectMessage': null,
                          'location': new LocationHandler(),
                          'validate': false,
                          'onMark': null,
                          'onUnmark': null,
                          'onHashRead': function(){ … }
                        }

where

'regexp' — regular expression that describes word (not compiled, as string).
'selectable' — HTMLElement or its id, that contains selectable text.
'marker' — HTMLElement or its id, that contains marker icon to be displayed on text selection. If element with given id is not found, an <a/> element is created.
'selectMessage' — HTMLElement or its id with popup that floats when text is selected. If closed once, popup will be never displayed again in this browser (localStorage or cookies are used). If no value provided, the popup is not shown.
'ignored' — Either function or string.
- Filter function, that allows to ignore specified HTMLElement as selection target. Should return true if element must be ignored; otherwise false.
- Comma-separated tag names, classes or ids of ignored elements. For example: 'ul, .ignored-cls, #ignored-id'.
'location' — an object used for get url hash from and write it to. The only significant methods are getHash, setHash and addHashchange. You can redefine, for example, to write URL not in address bar but into a custom popup, or for handle address bar URL manually.
'validate' — If true, the checksum of each selection is written in hash and they are validated on page load. Attention! There is no checksum algorithm provided by default and you should provide it to use validation! See 'Validation' section below.
'enableHaschange' — If true, hashchange event is handled.
'onMark' — Callback function that fired on text selection.
'onUnmark' — Callback function that fired on text deselection.
'onHashRead' — Function that called on loading of the page with selected fragments. Function that set by default will scroll page to the first selected fragment.

Internet Explorer support

MASHA uses custom bundled variant of ierange script to support Internet Explorer.

                    <!--[IF IE]> 
                        <script type="text/javascript" src="ierange.js"></script> 
                    <![ENDIF]-->

If you use mainstream ierange library instead of bundled one please add this line to end of root function:

                    window.DOMRange = DOMRange;

Validation

Some changes on the page (paragraph and words additions or deletions) may cause unwanted selection changes. To ensure that selection is not broken, use validation feature.

To use validation you should implement MaSha.prototype.getPositionChecksum method. This method accepts word sequence iterator (a function returning the next word of sequence on each call or null if finished) and returns a string checksum. The getPositionChecksum method is called twice for each range: one for start position and one for end position (with reversed iterator).

The checksum is included into hash and it is checked on page load. If calculated checksum doesn't one from url, the selection is not restored.

Checksum algorythm is not included in MaSha by default, because we didn't invent The Best Algorythm Ever yet. And we don't want to force users to use bad (draft) algorythms, but you can use our algorythm.

                    MaSha.prototype.getPositionChecksum = function(wordsIterator){
                        var word1 = wordsIterator();
                        var word2 = wordsIterator();
                        var sum = makeSomeCalculations(word1, word2);
                        return sum;
                    }

MaSha & forums

MaSha supports pages with multiple text blocks, including forum threads. In this case, for each text block own MaSha instance is created, and each text block has separate paragraph and text numeration. This behavior is implemented by MultiMasha, a constructor accepting two parameters:

'elements' — an array of html-elements corresponding text blocks;
'getPrefix' — function accepting html-element from the array and returning it's identifier to be used in URL. Return element's id by default.
'options' — options of MaSha object.

Example of usage:

                    var posts = document.querySelectorAll('.post-text');
                    new MultiMaSha(posts, function(element){
                        return element.id.split('-')[1];
                    });