Создание расширения FireFox для начинающих

В данной статье представлена пошаговая инструкция по разработке простейшего расширения для FireFox.
Это частичный перевод оригинальной статьи.

Это не моя статья, а моего друга (его мыльце: templar8@gmail.com). Он очень хочет попасть на Хабр. У меня самого не хватает кармы для инвайта.

Вступление

Это руководство — пошаговая инструкция по созданию простейшего расширения. Мы попробуем добавить в строку состояния еще одну небольшую панельку с фразой «Hello, World!».

Подготовка окружения

Расширения упаковываются и распространяются в виде zip-файлов или пакетов с расширением XPI.

Вот пример типичной внутренней структуры XPI-файла:

exampleExt.xpi:
        /install.rdf
        /components/*
        /components/cmdline.js
        /defaults/
        /defaults/preferences/*.js
        /plugins/*
        /chrome.manifest
        /chrome/icons/default/*
        /chrome/
        /chrome/content/

Нам нужно создать структуру каталогов, похожую на эту. Для начала создайте корневую директорию расширения (например, C:\extensions\my_extension\ или ~/extensions/my_extension/). Внутри этого каталога создайте каталог chrome, в котором создайте каталог content.

В корневом каталоге расширения создайте два пустых текстовых файла с именами chrome.manifest и install.rdf. В итоге должна получиться структура каталогов следующего вида:

<ext path>\
        install.rdf
        chrome.manifest
        chrome\
            content\

Дополнительная информация о настройке окружения находится по этой ссылке.

Сценарий установки

Откройте файл install.rdf и добавьте в него следующий текст:

1. <?xml version="1.0"?>
2.  
3. <RDF xmlns="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
4.      xmlns:em="http://www.mozilla.org/2004/em-rdf#">
5.  
6.  <Description about="urn:mozilla:install-manifest">
7.     <em:id>sample@example.net</em:id>
8.     <em:version>1.0</em:version>
9.     <em:type>2</em:type>
10.  
11.     <!-- Target Application this extension can install into,
12.          with minimum and maximum supported versions. -->
13.     <em:targetApplication>
14.      <Description>
15.         <em:id>{ec8030f7-c20a-464f-9b0e-13a3a9e97384}</em:id>
16.         <em:minVersion>1.5</em:minVersion>
17.         <em:maxVersion>3.0.*</em:maxVersion>
18.      </Description>
19.     </em:targetApplication>
20.  
21.     <!-- Front End MetaData -->
22.     <em:name>sample</em:name>
23.     <em:description>A test extension</em:description>
24.     <em:creator>Your Name Here</em:creator>
25.     <em:homepageURL>www.example.com</em:homepageURL>
26.  </Description>     
27. </RDF>

* This source code was highlighted with Source Code Highlighter.

• sample@example.net — ID расширения. Это значение записывается формате email-адреса и необходимо для идентификации расширения (оно не должно быть вашим email-адресом). Сделайте его уникальным. Вы также можете использовать GUID. ПРИМЕЧАНИЕ: Хотя этот параметр и записывается в формате email-адреса, он не обязательно должен быть валидным. (example.example.example)
  
• Параметр <em:type>2</em:type> — 2 указывает на то, что это будет расширение. Допустим, для тем оформления это значение должно быть установлено в 4 (все коды типов можно посмотреть тут).
  
• {ec8030f7-c20a-464f-9b0e-13a3a9e97384} — ID Firefox’а (прим. пер. – видимо, для Thunderbird будет другое значение).
  
• 1.5 — номер минимально необходимой для работы расширения версии Firefox. Никогда не используйте символ * для указания minVersion, это может привести к неожиданным результатам.
  
• 3.0.* — максимальный номер версии Firefox с которой будет работать расширение. Это значение должно быть не новее самой последней на данный момент версии браузера! В данном случае «3.0.*» указывает на то, что расширение будет работать с Firefox 3.0 и версиями 3.0.x.
  

(Если вы получили сообщение, что install.rdf неверен, полезным будет загрузить этот файл в Firefox (Файл->Открыть файл…), после чего браузер покажет вам xml ошибки. В моем случае был пробел перед «<?xml»)

Расширениям, созданным для работы с Firefox 2.0.0.x, нужно указать в качестве максимальной версию «2.0.0.*». Для расширений, созданных для работы с Firefox 1.5.0.x — «1.5.0.*».

Список обязательных и опциональных параметров сценария установки можно посмотреть тут.

Сохраните файл.

Расширение браузера с использованием XUL

Пользовательский интерфейс Firefox написан с использованием XUL и JavaScript. XUL — это подвид XML, позволяющий создавать элементы пользовательского интерфейса, такие как кнопки, меню, панели управления, деревья и т.п. Все действия пользователя обрабатываются с помощью JavaScript.

Чтобы «расширить» браузер, мы изменяем отдельные части интерфейса пользователя Firefox, добавляя или модифицируя виджеты (элементы управления). Мы добавляем виджеты путем добавления новых XUL DOM-элементов в окно браузера и управляем их поведением с помощью скриптов и обработки событий.

Интерфейс браузера определен в файле browser.xul ($FIREFOX_INSTALL_DIR/chrome/browser.jar содержит content/browser/browser.xul) В browser.xul мы можем найти описание строки состояния, которое выглядит приблизительно так:

1. <statusbar id="status-bar">
2. ... <statusbarpanel> ...
3. </statusbar>

* This source code was highlighted with Source Code Highlighter.

<statusbar id="status-bar"> — это «связующая точка» XUL-слоя.

XUL-слои

XUL-слои — это способ добавления виджетов в XUL-документ. XUL-слой — это .xul-файл, который определяет XUL-фрагменты, описывающие связующие точки в «основном» документе. Эти фрагменты могут указывать на виджеты, которые будут добавлены, удалены или изменены.

Пример документа XUL-слоя

1. <?xml version="1.0"?>
2. <overlay id="sample"
3.          xmlns="http://www.mozilla.org/keymaster/gatekeeper/there.is.only.xul">
4. <statusbar id="status-bar">
5.  <statusbarpanel id="my-panel" label="Hello, World" />
6. </statusbar>
7. </overlay>

* This source code was highlighted with Source Code Highlighter.

Тег <statusbar> с id, равным «status-bar» указывает на виджет браузера в который мы хотим добавить наш элемент.

Тег <statusbarpanel> — это новый виджет, который мы хотим добавить.

Сохраните этот код в файле sample.xul каталога chrome/content.

Chrome URIs

XUL-файлы – это часть т.н. «Chrome Packages» — пакетов элементов пользовательского интерфейса, загружаемых через URI вида chrome://. Вместо того, чтобы загружать интерфейс, используя URI вида file:// (тем более, расположение Firefox может быть различным в зависимости от платформы и систем), разработчики Mozilla пришли к решению создать новый вид URI, используя который все установленные приложения будут иметь доступ к содержимому XUL.

URI для окна браузера – это chrome://browser/content/browser.xul. Попробуйте ввести этот URL в адресной строке Firefox.

Chrome URI состоит из нескольких частей:

• 1-я — протокол (chrome), которая сообщает сетевой библиотеке Firefox, что это Chrome URI.
  
• 2-я — название пакета (в данном примере, browser), который указывает на набор компонентов пользовательского интерфейса. Для вашего приложения эта часть должна быть уникальной, во избежание конфликтов с другими расширениями.
  
• 3-я — тип запрашиваемых данных. Бывает трех типов: content (XUL, JavaScript, XBL связи и другие составляющие пользовательского интерфейса приложения), locale (DTD, файлы .properties, в которых могут быть и другие файлы, содержащие строки локализации пользовательского интерфейса) и skin (CSS и изображения темы).
  
• Последняя часть – путь к загружаемому файлу.
  

Например, chrome://foo/skin/bar.png загружает файл bar.png из раздела skin темы foo.

Когда вы загружаете что-либо, оперируя Chrome URI, Firefox использует реестр Chrome (Chrome Registry) для преобразования этого URI в реальный путь к файлу на диске (или в JAR архивах).

Создание Chrome Manifest

Для получения большей информации о Chrome Manifest и всех его свойствах можно обратиться к справочному руководству.

Откройте файл chrome.manifest, который был создан в корневом каталоге вашего расширения. Добавьте следующий код:

content     sample     chrome/content/

(Не забудьте о закрывающем слеше, «/»! Без него пакет не будет зарегистрирован.)

Разберем каждый элемент:

1. тип пакета chrome
2. название пакета chrome (должно быть написано в нижнем регистре, потому что Firefox/Thunderbird в версии 2 и более ранних не поддерживают названия со смешанным регистром — баг 132183)
   
3. размещение файлов пакетов chrome

Это означает, что файлы пакета sample расположены в каталоге chrome/content относительно места расположения файла chrome.manifest.

Обратите внимание, что файлы контента, локализаций и скинов должны находиться внутри каталога content, locale и skin подкаталога chrome соответственно.

Сохраните файл. Теперь, когда вы запустите Firefox с вашим расширением (как это сделать, будет описано ниже), пакет chrome будет зарегистрирован.

Регистрация слоя

Теперь необходимо связать ваш слой с окном браузера. Для этого добавьте следующие строки в файл chrome.manifest:

overlay chrome://browser/content/browser.xul chrome://sample/content/sample.xul

Эти две строки указывают Firefox’у связать sample.xul и browser.xul во время загрузки browser.xul.

Тестирование

Во-первых, мы должны сообщить Firefox о нашем расширении. На стадии разработки для Firefox версии 2 и выше, вы можете указать откуда брать новое расширение, и браузер будет его загружать после каждого перезапуска.

1. Перейдите в домашний каталог, а после в каталог, содержащий профиль Firefox, с которым вы собираетесь работать (например, Firefox/Profiles/<profile_id>.default/).
   
2. Перейдите в каталог extensions/, если его не существует, то создайте.
   
3. Создайте текстовый файл и поместите в него полный путь к каталогу с вашим расширением (например, C:\extensions\my_extension\ или ~/extensions/my_extension/). Пользователи Windows должны помнить о направлении слешей, обязательно добавьте закрывающий слеш и удалите все замыкающие пробелы.
   
4. Сохраните файл с id расширения в качестве его имени (например, sample@example.net). Без расширения файла.
   

Теперь все готово к тестированию.

Запустите Firefox. Firefox по текстовой ссылке сам найдет каталог с вашим расширением и установит его. После запуска браузера вы увидите надпись «Hello, World!» в правой части строки состояния.

Вы можете сделать некоторые изменения в .xul-файле, перезапустить Firefox, и сразу же увидите результат.

Создание пакета

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

Запакуйте архиватором zip содержимое каталога с вашим расширением (не сам каталог расширения) и измените расширение архива с .zip на .xpi.

Если вы являетесь счастливым обладателем 'Extension Builder'-а, то он может сам сделать за вас всю грязную работу (Tools -> Extension Developer -> Extension Builder). Просто перейдите в каталог с вашим расширением и нажмите кнопку Build Extension. Это расширение имеет очень много инструментов облегчающих разработку.

Теперь загрузите получившийся .xpi-файл на ваш сервер и удостоверьтесь, что его тип установлен в application/x-xpinstall. После этого можно скачать и установить расширение.