MASHA
MASHA (сокращение от Mark & Share) – утилита, позволяющая отметить интересные вам фрагменты текста на странице и получить уникальный url с размеченными фрагментами. Таким образом, любой желающий может, выделив в тексте нужные части (параграфы, предложения или слова), поделиться с кем-либо сгенерированной уникальной ссылкой. При переходе по такой ссылке пользователь попадет на страницу с исходным текстом и восстановленной маркировкой.
Попробуйте выделить любой текст и нажать иконку маркера на этой странице. Каждое выделение будет менять текущий url, добавляя к нему служебную информацию для восстановления маркировки.
Данная функция была разработана для официального сайта Президента (доступна на kremlin.ru с июля 2011 года). Но поскольку многие спрашивали, как утилита работает и можно ли забрать ее себе, она получила имя и этот сайт.
Уже работает
УСТАНОВКА
MASHA доступна в пакетном менеджере npm:
npm install --save masha
Или вы можете скачать архив пакета:
MASHA_ALL.ZIPver. 1.1.3 js + css + image MASHA_LOGO.ZIP (315Kb)
логотип (eps, ai, psd) © Михаил Жашков
ИНСТРУКЦИИ
MASHA написана на чистом javascript и не требует для своей работы каких-либо дополнительных библиотек (кроме ierange, поставляющегося вместе с MASHA для поддержки Internet Explorer). Чтобы подключить MASHA, необходимо внутри тега <head></head> добавить:
<script type="text/javascript" src="masha.js"></script>
<link rel="stylesheet" type="text/css" href="masha.css">
<script type="text/javascript">
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();
});
}
</script>
Для es2016/CommonJS импортируйте класс из пакета:
import { MaSha } from "masha";
// или
var MaSha = require("masha").MaSha;
Для работы MASHA может потребоваться наличие в HTML следующих элементов:
- Элемент, содержащий текст, который можно выделять (cм. настройку selectable ниже), обязательно.
- Кнопка, появляющаяся при выделении текста мышкой, при нажатии на которую подсвечивается текст и меняется адресная строка браузера (cм. настройку marker ниже).
- Всплывающий элемент с пояснительным текстом (см. настройку selectMessage).
При активации MASHA вы можете воспользоваться настройками по умолчанию или переопределить их по своему усмотрению:
new MaSha({ option: 'value' })
Настройки передаются в виде словаря и по умолчанию имеют следующие значения:
{
'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(){ … }
}
где
- 'regexp' — регулярное выражение, соответствующее слову (не компилированное, в виде строки);
- 'selectable' — html-элемент или id элемента, содержащего текст, который можно выделять;
- 'marker' — html-элемент или id элемента с иконкой маркера, который появляется при выделении текста. Если элемент не найден, то создается элемент <a/>;
- 'selectMessage' — html-элемент или id элемента с пояснительным текстом, всплывающего при выделении текста. После закрытия элемент никогда не будет показан на сайте в текущем браузере (флаг хранится в localStorage или cookies). По-умолчанию, отключено;
- 'ignored' — функция или строка:
- Функция, принимающая html-элемент и указывающая, должны ли игнорироваться выделения текста в нём. Возвращает true, если выделение игнорируется, иначе – false.
- Разделённые запятыми названия html-тегов, классов или id. Например: 'ul, .ignored-cls, #ignored-id'.
- 'location' — объект, используемый для получения URL из адресной строки. Должен реализовывать методы getHash, setHash и addHashchange. Может быть переопределён, например, для того, чтобы выводить URL не в адресной строке, а во всплывающем элементе или чтобы управлять изменением адресной строки вручную (для совместимости с другими компонентами);
- 'validate' — если true, в адресную строку включается проверочная сумма для каждого выделения, которая проверяется при загрузке страницы. Внимание! По-умолчанию, функция вычисления контрольной суммы не включена в MaSha. См. раздел «Валидация».
- 'enableHaschange' — если true, включается обработчик события hashchange;
- 'onMark' — callback, вызывается при выделении текста;
- 'onUnmark' — callback, вызывается при снятии выделения;
- 'onHashRead' — функция, вызывающаяся при загрузке страницы с метками, по умолчанию задана функция, проскроливающая страницу до первого выделенного фрагмента;
Поддержка Internet Explorer
Для поддержки Internet Explorer используется библиотека ierange, немного отличающаяся от оригинала.
<!--[IF IE]>
<script type="text/javascript" src="ierange.js"></script>
<![ENDIF]-->
Вы можете использовать поставляющуюся вместе с MASHA, либо добавить в конец корневой функции строку:
window.DOMRange = DOMRange;
Валидация
В некоторых случаях изменения на странице (удаление или добавление слов или параграфов) могут вызвать нежелательное изменение выделенного фрагмента. Чтобы избежать этого можно воспользоваться механизмом валидации.
Чтобы воспользоваться валидацией, необходимо реализовать метод MaSha.prototype.getPositionChecksum. Этот метод принимает итератор последовательности слов выделения (функция, при каждом вызове возвращающая следующее слово или null, если слов больше нет) и возвращает строковое значение проверочной суммы. Метод getPositionChecksum вызывается дважды для каждого выделения: в прямом и обратном порядке.
Алгоритм вычисления проверочной суммы не включен в MaSha по-умолчанию, потому что разработчики пока не смогли придумать Лучший Алгоритм На Свете и решили не навязывать пользователям свой несовершенный вариант. Если Вас не смущает несовершенство алгоритма, можете использовать наш:
MaSha.prototype.getPositionChecksum = function(wordsIterator){
var word1 = wordsIterator();
var word2 = wordsIterator();
var sum = makeSomeCalculations(word1, word2);
return sum;
}
MaSha и форумные движки
MaSha поддерживает работу со страницами с несколькими текстовыми блоками, такими как форумные движки. В этом случае для каждого блока текста создается собственный экземпляр MaSha, отдельно ведется нумерация параграфов и строк. Подобное поведение реализуется с помощью объекта MultiMasha, конструктор которого принимает два параметра:
- 'elements' — массив html-элементов — блоков текста;
- 'getPrefix' — функция, принимающая в качестве аргумента html-элемент — блок текста, возвращающая идентификатор этого элемента, который будет использоваться для ссылки на него в URL. По-умолчанию, возвращает id элемента.
- 'options' — параметры для объектов MaSha.
Пример использования:
var posts = document.querySelectorAll('.post-text');
new MultiMaSha(posts, function(element){
return element.id.split('-')[1];
});
РАЗРАБОТКА
Разработка проекта ведётся на сервисе github, где вы можете сообщить об ошибке и предложить реализовать новые возможности или самостоятельно внести изменения и предложить их включить в основную ветку.
АВТОРЫ
Идею мы почерпнули из похожих начинаний NYTimes (проект Emphasis), где слишком сложная механика побудила нас сделать приложение, для работы с которым не требуется чтение документации.
ЛИЦЕНЗИЯ
MASHA распространяется по лицензии MIT (группа лицензий для свободного программного обеспечения). Данная лицензия позволяет безвозмездно использовать, изменять, распространять утилиту почти без ограничений.
