Учимся писать userscript'ы

:

Доброго времени суток всем желающим приобщиться к миру пользовательских скриптов (они же userscript, userJS, юзерскрипты).

В этой статье я хочу поведать о том, что такое юзерскрипты, c чем их едят и, главное, как их готовят!

Внимание: предполагается минимальное знание javascript.
На практике доказано: юзерскрипты может писать человек, не знакомый с программированием, но обладающий усидчивостью и желанием изучить javascript!
О том, что такое javascript и как с ним обращаться, можно узнать на javascript.ru.

Что такое юзерскрипты?


Кратко: юзерскрипт — это программа, написанная на языке JavaScript, хранящаяся на компьютере пользователя и подключаемая браузером на определенных страницах. Юзерскрипт представляет собой файл с расширением .user.js (именно по расширению браузеры понимают, что файл является юзерскриптом), содержащий метаданные и непосредственно javascript-код.

При подключении к странице юзерскрипт выполняется так же, как и обычные javascript-сценарии.
У юзерскрипта есть доступ к DOM-дереву страницы, в контексте которой он выполняется.
В современных браузерах у юзерскрипта есть доступ к localStorage и прочим HTML5 API.

Юзерскрипты поддерживаются всеми основными современными браузерами (и даже кое-как поддерживаются IE7 и выше).

Самый известный портал юзерскриптов — userscripts.org. Тут можно найти хранилище скриптов, инструменты управления своими скриптами на портале и, что не маловажно, отзывчивый форум (всё на английском).

Немного общей теории


Самыми распространенными являются скрипты под расширение GreaseMonkey для браузера Firefox.
Подробную информацию по GreaseMonkey и написанию юзерскриптов под GreaseMonkey можно узнать на http://wiki.greasespot.net.
Так сложилось исторически, что данный браузер был (и остаётся по сей день) первым, в котором поддержка юзерскриптов была выполнена на высоком уровне.

Не все скрипты, написанные для GreaseMonkey, могут запускаться в других браузерах. Причина в криворукости том, что во многих скриптах используется GM API — набор javascript-функций, специфичных для GreaseMonkey.

Однако, проще всего писать юзерскрипты под браузер Google Chrome.
На это есть ряд причин:

  1. Простым скриптам не нужна поддержка GM API (библиотека, доступная в GreaseMonkey)
  2. Google Chrome, в отличие от Firefox+GreaseMonkey, имеет отличнейший дебаггер.
  3. Сообщения об ошибках юзерскрипта в Firefox ужасны! Если вы не обладаете даром телепатиитвердыми знаниями GreaseMonkey и javascript, написание юзерскрипта может превратится в муки!
  4. Google Chrome не требует расширений для поддержки юзерскриптов. Интерфейс для удаления/отключения юзерскриптов доступен «из коробки».

Очевидные минусы Google Chrome:
  1. Нет доступа к «родному» window.
  2. Не поддерживается директива @ include метаданных. Директива @ match глючит, можно сказать, что она тоже не поддерживается.

Особенности юзерскриптов


Код юзерскриптов может посмотреть любой желающий, вооруженный блокнотом.
Базовые знания javascript позволяют отсечь угрозу установки шпионских и вредоносных скриптов простым анализом кода скрипта (придётся задействовать мозг).

Важно: Если вы не доверяете автору скрипта, главное удостовериться, что скрипт не отсылает пользовательские данные (куки, вводимый текст) на сторонние сервисы!

Все юзерскрипты запускаются после того, как загрузились все основные элементы страницы, но ещё не загрузились картинки. Можно сказать, что юзерскрипты грузятся по событию DOMContentLoaded.
В любом случае, проверки на window.onload не нужны.

Каждый браузер накладывает свои ограничения на исполнение юзерскриптов, но в целом юзерскрипты могут делать почти всё, что могут скрипты на странице.
Чаще всего юзерскрипты используются для изменения интерфейса страницы или для добавления плюшек, блекджека и шлюх(юзерскрипты для социальных сетей).
Бывают и продвинутые юзерскрипты, которые представляют собой самостоятельные программы (аукционные и игровые боты, плагины-помощники и т.д).

Анатомия юзерскриптов


Юзерскрипт — это текстовый файл с расширением user.js. В начале файла располагается блок метаданных — описание самого скрипта. После блока метаданных следует javascript-код, который и будет исполняться браузером.

Рассмотрим тестовый скрипт, который показывает alert с текстом на определенной странице.

// ==UserScript==
// @name myUserJS
// @description Мой самый первый юзерскрипт 
// @author Vasya Pupkin
// @license MIT
// @version 1.0
// @include http://userscripts.org/*
// ==/UserScript==
// [1] Оборачиваем скрипт в замыкание, для кроссбраузерности (opera, ie)
(function (window, undefined) {  // [2] нормализуем window
    var w;
    if (typeof unsafeWindow != undefined) {
        w = unsafeWindow
    } else {
        w = window;
    }
    // В юзерскрипты можно вставлять практически любые javascript-библиотеки.
    // Код библиотеки копируется прямо в юзерскрипт.
    // При подключении библиотеки нужно передать w в качестве параметра окна window
    // Пример: подключение jquery.min.js
    // (function(a,b){function ci(a) ... a.jQuery=a.$=d})(w);

    // [3] не запускаем скрипт во фреймах
    // без этого условия скрипт будет запускаться несколько раз на странице с фреймами
    if (w.self != w.top) {
        return;
    }
    // [4] дополнительная проверка наряду с @include
    if (/http:\/\/userscripts.org/.test(w.location.href)) {
        //Ниже идёт непосредственно код скрипта
        alert("Userscripts приветствует вас навязчивым окном.");
    }
})(window);

Важно: данный скрипт представляет собой оболочку для кроссбраузерных юзерскриптов. Этот же скрипт, но с английскими комментариями, можно стянуть с pastebin.com и использовать безнаказанно.

В самом начале располагается блок метаданных (в виде комментария).

// ==UserScript==
// ...
// ==/UserScript==

Этот блок состоит из директив описания юзерскрипта. Ниже в таблице представлены основные директивы и их назначение.

Важно: Все директивы, как и сам блок метаданных, могут отсутствовать.

Директива Назначение
@ name Название юзерскрипта.
Это название будет отображаться в интерфейсе управления
юзерскриптами. Если директива отсутствует, то название
юзерскрипта будет таким же, как и название файла.
@ description Описание юзерскрипта.
Это описание будет отображаться в интерфейсе управления
юзерскриптами.
@ namespace Пространство имён.
Определяет уникальность набора скриптов.
Сюда можно вписать имя домена, принадлежащего вам. Или любую другую строку.
Считайте, что это второе название скрипта. Обязательная директива для Trixie!
@ author Имя автора.
@ license Название лицензии, по которой распространяется юзерскрипт.
@ version Номер версии юзерскрипта.
К сожалению, механизма автообновления нету ни в одном браузере,
поэтому номер версии — это просто цифры, которые отображаются в интерфейсе.
@ include Директива описания url страницы,
на которой нужно запускать юзерскрипт.
Поддерживает вайлдкард *(применимо в GreaseMoneky, Opera, IE).
Для каждого отдельного url нужно использовать отдельную директиву @ include.
@ exclude Директива описания url страницы,
на которой не нужно запускать юзерскрипт.
Поддерживает вайлдкард *(применимо в GreaseMonkey, Opera, IE).
Для каждого отдельного url нужно использовать отдельную директиву @ exclude.
@ match Аналогично @ include, но с более жесткими ограничениями
(применимо в GreaseMonkey старше 0.9.8, Google Chrome).
Подробнее об ограничениях и формате директивы можно
прочитать на этой странице.
Для каждого отдельного url нужно использовать отдельную директиву @ match.

Важно: Как показала практика, полагаться на директиву @ match в юзерскриптах не стоит.
Google Chrome периодически отказывается учитывать @ match
и запускает юзерскрипты на всех страницах.
Для предотвращения такой ситуации в юзерскрипты,
которые будут запускаться не только в Firefox,
нужно добавлять код проверки адреса страницы (см. ссылку [4] в коде юзерскрипта).

Важно: При отсутствии директив @ include или @ match, юзерскрипты будут запускаться на всех страницах.

В нашем юзерскрипте использован ряд хитростей:

  1. Для того, чтобы юзерскрипты имели одинаковое поведение и не загрязняли глобальную область видимости, код оборачивается в замыкание (см. [1] в коде скрипта).
  2. Для правильного подключения библиотек внутри юзерскрипта и для обхода некоторых хитрых особеннойстей GreaseMonkey, необходимо «нормализовать» ссылку на глобальную область видимости window (см. [2] в коде скрипта).
  3. Для того, чтобы юзерскрипт не запускался несколько раз на одной и той же странице, необходимо останавливать работу при запуске юзерскрипта во фреймах (см. [3] в коде скрипта).
  4. Для того, чтобы юзерскрипт запускался только на нужных нам страницах, необходимо явно проверять url страницы (см. [4] в коде скрипта).
  5. Благодаря такой структуре, юзерскрипт может быть относительно просто преобразован в букмарклет.

Результат


Наш юзерскрипт готов к использованию!
Нет, серьёзно, вы можете скопировать код юзерскрипта в файл, назвать его my.user.js, и закинуть полученный файл в браузер (используйте Chrome или Firefox с установленным GreaseMonkey).

Конечно, наш юзерскрипт не обладает серьезными функциями, код выглядит страшным и малопривлекательным (для непосвященного человека). Но в итоге мы получили заготовку для кроссбраузерных юзерскриптов.
Это значит, что юзерскрипт можно запустить практически в любом современном браузере!
И это замечательно!

Остаётся вопрос: как «раздать» наш скрипт пользователям (ведь мы писали скрипт не только для себя)?
Варианты:

  • Зарегестрироваться на портале userscripts.org и загружать скрипты туда.
  • Завести репозиторий на code.google.com или github.com.
  • Создать свой простой сервис/сайт/страничку.
    Важно:Если хотите, чтобы у пользователей GreaseMonkey автоматически открывался диалог установки юзерскрипта, отдавайте файл прямиком с файловой системы (url файла должен заканчиваться на .user.js). В противном случае пользователь увидит исходный код скрипта и панель с кнопкой «установить». Эта кнопка не работает!

Рецепт для непрограммистов (похожими методами пишется ~70% скриптов):
  1. Придумываем, что будет делать наш юзерскрипт (перекрашивать ссылки, например)
  2. Берём шаблон из статьи
  3. Сохраняем в файл my.user.js
  4. Удаляем строку с alert(...).
  5. Идём на форум (userscripts.org или любой форум по javascript).
  6. Спамим, флудим и достаём людей вопросами «как перекрашивать ссылки», «дайте код» и т.д.
  7. Изменяем метаданные и проверку url страницы на нужные нам.
  8. Вставляем полученный на форуме код в юзерскрипт.
  9. Сохраняем файл.
  10. ...
  11. PROFIT!!1!

Полезные ссылки:


Список статей:
  1. » Учимся писать userscript'ы
  2. Userscripts. Углубляемся.
  3. Userscripts. Упаковываем юзерскрипт для Chrome
  4. Usersctripts. Кроссдоменные запросы

P.S. Хотелось бы увидеть блог Userscripts на хабре. Ибо не одним GreaseMonkey едины.