API-Scriptish.

У нашего расширения, которое позволяет Тебе вставить твой личный сценарий на любую страницу - есть свое индивидуальное API, позволяющие програмно управлять настройками.
Основная направленость функций - расщиряет возможности стандартных скриптов браузера в части обмена и отладки твоего контента. Выше мы рассмотрели блок мета-данных, который описывает назначение каждого сценария. Чтобы получить информацию об его содержимом и оперативно использовать в самом сценарии, для этого нужно воспользоваться специальной функцией

GM_getMetadata

Возвращает значение каждого ключа по его названию. Так как могут в мета-блоке использоваться несколько ключей с одним именем, то результатом этой функции, будет либо массив либо объект, состоящий из значений конкретного ключа.

 GM_getMetadata(key,local)

Аргументами функции являются

string key

строка с названием ключа, причем ее можно указывать без специального знака ключа @ и в любом регистре

boolean local = true

Источник информации. по умолчанию - истина, т.е значение выбирается из текущего имени, и в случае его отсутствия выдается пустое значение , при установки значения в false браузер запросит это значение с домашней страницы и только после всего выдаст заключение о значении ключа. В настоящий момент не используется

Примеры

var myName = GM_getMetadata("name");
// получить описание
var myDescription = GM_getMetadata("description");
alert("Юзер Script: " + myName 
  + "\nОписание: " + myDescription);

// получить ключи мета-данных
var headers = GM_getMetadata();
for (var prop in headers)
  console.log("Имя @ключа: " + prop);

console

Через запись в консоль, появляется возможность вывода сообщения в журналы логов (log), отладки (debug), предупреждений (ware), ошибок (error), информаций (info) и трасировки (trace), в качестве методов к консоли. Эти журналы,как правило, есть в Firebug или Web-консоле.

Примеры

 var a = 23;
 console.log('a', '=', a+5);
// будет выведено в консоль - а=28

Так же с выводом на консоль связана еще одна конструкция, которая выводит не только в консоль браузеера, но и в консоль-ошибок браузера в группу "Сообщения", но ее разработчики советуют не применять. это функция

GM_log(список значений)

Переменные и константы

GM_setValue(name, value)

Создает переменную с именем name и назначает ей величину value, возвращая ее в качестве результата

GM_getValue(name)

Возвращает значение динамической переменной, позицируя ее по имени name. Если переменной с таким именем нет - то возвращается значение null

GM_deleteValue(name)

Удаляет динамическую переменную, позицируя ее по имени name

GM_listValue()

Возвращает в массиве имена всех динамических переменных
Пример

GM_setValue("a", true);
GM_setValue("b", "Yay!");
GM_setValue("c", 3);

var myPrefs = GM_listValues(); 
// myPrefs содержит  ["a", "b", "c"]

for (var i=0; i < myPrefs.length; i++) {
  GM_log(myPrefs[i] + " is: " + GM_getValue(myPrefs[i]));
GM_deleteValue(myPrefs[i]);
}

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

unsafeWindow

референтная ссылка на общее window

GM_updatingEnabled = true

Эта переменная всегда связана с ключем метадаты @updateURL.. Если этот ключ установлен и разрешены обновления, то переустановка этой переменной приводит к обновлению скрипта

Рессурсы и прочее

GM_getResourceText(name)

Возвращает содержимое ключа @resource при условие что его содержимое подходит под MIME-тип text/plain
Пример

// ==UserScript==
// @name         GM_getResourceText test
// @namespace    myCoolNamespace
// @include      *
// @resource     myDoc http://www.mywebsite.com/myDoc.txt
// ==/UserScript==

console.log("Содержимое документа: "
  + GM_getResourceText("myDoc"));

GM_getResourceURL(name)

Возвращает Base64-encoded данные. Этим способом можно закачивать извне изображения и другие объекты. Причем они сохраняются в фолдере скрипта на диске и так же со скрптом обновляются
Пример

// ==UserScript==
// @name         GM_getResourceText test
// @namespace    myCoolNamespace
// @include      *
// @resource     myImage http://www.mywebsite.com/myImage.png
// ==/UserScript==

var img = document.createElement("img");
img.src = GM_getResourceURL("myImage");
document.body.appendChild(img);

GM_notification(msg,title,icon,callback)

Функция выдает сообщение msg в всплывающей подсказке, с заголовком title, а при его отсутствии с именем скрипта, иконкой icon, и так же при отсутствии с иконой самого расширения.

Если указан callback, то перед тем как через некоторое время исчезнуть и получив клик от юзера - вызвывается эта функция, которой можно выполнить любые действие.

Эта функция по действию и использует тот же механизм функции подсказки загрузки контента

Примеры

GM_notification("Я типа сделал. 
  Что дальше  :)) ");

GM_notification("Анализ закончен!",
  "Компьютер", 
  null, function() {
  /* некоторые действия*/
});

GM_openInTab(url,load,res)

Функция открывает дополнительный таблоид браузера по ссылки url, и в зависимости от наличия следующих аргументов, которые по умолчанию == false, выполняет переключение или нет на это окно. По умолчанию происходит переключение

Результат - возвращается референтная переменная на открытое по ссылке окно.

GM_addStyle

Есть еще группа команд которая также входит в основное API расширения, но рассказ о них мы сейчас опустим, так как они имеют спецефичное назначение. О них мы поговорим в следующей заметке.

XML GM_safeHTMLParser( HTML)

Функция парсит HTML, возвращая XMLDocument. Так же из HTML удаляются все опасные теги, такие как <script>, <style>, <head>, <body>, <title> и <iframe>, а также все JavaScript (включая атрибуты элементов, содержащие JavaScript)

node GM_xpath({obj})

GM_xpath - простой интерфейс для выбора DOM-узлов с XPath.
Аргументы функции представляют собой части объекта. Возвращаемое значение либо null - ничего не найдено, либо node - узел DOM или массив узлов {

string path:

строка запроса в формате Xpath

[string] paths:

мвссив строк разных запросов в формате Xpath, которые необходимо провести

DOMNode node:[*document]

(*необязательно) ссылка на узел, в котором нужно произвести поиск. По умолчанию этот параметр определяется как document

Boolean all:[*false]

При установке параметра значения true выдается массив всех возможных объектов, в противном случае только первый из всех всех критериев поиска.

mix resolver: [*]

Определяет пространство имен в узлах при запросе. Пo умолчанию подразумевается текущее

}
Пример

  var anchor = GM_xpath({
    path: "//a",
    all: true
  });
GM_log(anchor.slice(0,6)) ; 

выдает в логер первые шесть ссылок в документе