Создание расширения

Введение

Этот урок по шагам покажет Вам как создать простое Расширение – сутью которого является добавление в панель статуса Firefox блока со строкой "Hello, World!"

Отметьте Данный урок о создании Расширений для Firefox 1.5 и более поздних версий. Другие существующие уроки для создания Расширений, предназначены для более ранних версий.

Если Вас интересует урок по созданию Расширения для Thunderbird, смотрите Создание Расширения для Thunderbird

Настройка окружения

Начнём с того, что Расширение распространяется в виде 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/). Создайте в этой директории новую директорию c именем chrome, и создайте в директории chrome директорию с именем code>content.

В корне директории вашего Расширения создайте два пустых файла, один назовите chrome.manifest, а другой install.rdf.

В итоге у вас должна получиться вот такая структура:

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

<pre> #!/bin/sh h=$HOME/moExt mkdir -p $h/my_extension/chrome/content touch $h/my_extension/chrome.manifest $h/my_extension/install.rdf </pre> Более подробную информацию по настройке окружения читайте в статье Setting up extension development environment.

Создание файла инсталяции

Откройте файл install.rdf который Вы создали на предыдущем этапе и вставьте эти строки:

<?xml version="1.0"?>

<RDF xmlns="https://www.w3.org/1999/02/22-rdf-syntax-ns#"
     xmlns:em="https://www.mozilla.org/2004/em-rdf#">

  <Description about="urn:mozilla:install-manifest">
    <em:id>[email protected]</em:id>
    <em:version>1.0</em:version>
    <em:type>2</em:type>
   
    <!-- Указывается приложение для которого может
            быть установлено Расширение, его максимальная
            и минимальная поддерживаемая версия. --> 
    <em:targetApplication>
      <Description>
        <em:id>{ec8030f7-c20a-464f-9b0e-13a3a9e97384}</em:id>
        <em:minVersion>1.5</em:minVersion>
        <em:maxVersion>3.0.*</em:maxVersion>
      </Description>
    </em:targetApplication>
   
    <!-- Front End MetaData -->
    <em:name>sample</em:name>
    <em:description>A test extension</em:description>
    <em:creator>Your Name Here</em:creator>
    <em:homepageURL>https://www.example.com/</em:homepageURL>
  </Description>      
</RDF>

[email protected] - идентификатор вашего Расширения. Это - значение, которое Вы должны придумать сами, чтобы идентифицировать Ваше Расширение, в данном случае оно в формате адреса электронной почты (это не обязательно должна быть Ваша электронная почта). Этот идентификатор должен быть уникальным. Вы можете также использовать GUID. ЗАМЕТКА: Хотя этот параметр и ДОЛЖЕН быть в формате адреса электронной почты, но не обязательно должен быть действительным адресом электронной почты. (example.example.example)
Определение <em:type>2</em:type> -- объявляет, что устанавливается именно расширение. Если бы Вы устанавливали тему, то это было бы 4 ( Install Manifests#type for other type codes).
{ec8030f7-c20a-464f-9b0e-13a3a9e97384} - Идентификатор приложения Firefox.
1.5 - минимальная версия Firefox, с которой будет работать Ваше Расширение. Укажите здесь минимальную версию, для которой будет выполняться все необходимые тесты.
3.0.* - - максимальня версия Firefox, с которой будет работать Ваше Расширение. Укажите здесь, самую свежую, доступную в данный момент версию. В этом случае, "3.0.*" указывает на то, что расширение работает с Firefox 3.0 и любыми последующими 3.0.x версиями.

(В Firefox версии 3.0.1, вы не сможете установить для em:minVersion и em:maxVersion значение "3.0.*". Если Вы попытаетесь установить Расширение, то получите ошибку "Not compatible with Firefox 3.0.1". Мне не ясны причины этого, так что я оставлю объяснение тому, кто имеет больше информации по этому поводу. Установка em:minVersion равным "3" и em:maxVersion равным "3.0.*" решило проблему для меня.)

Расширения разработанные для работы только с последними версиями Firefox 2.0.0.x, должны иметь установленным максимальную версию в "2.0.0. *". Расширения, разработанные для работы с только с последними версиями Firefox 1.5.0.x, должны иметь установленным максимальную версию "1.5.0. *".

Более подробно См. Install Manifests с полным перечнем основных и дополнительных свойств.

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

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

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

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

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

<statusbar id="status-bar">
 ... <statusbarpanel>s ...
</statusbar>

<statusbar id="status-bar"> это “точка слияния" для XUL Оверлея.

XUL Оверлеи

XUL Оверлей - это способ внедрить другие “виджеты” пользовательского интерфейса в основной документ XUL. XUL Оверлей – это .xul файл, в котором определены фрагменты XUL для вставки в определённых “точках слияния” в основном документе. Эти фрагменты, могут определять “виджеты” которые должны быть вставлены, удалены, или изменены.

Пример документа XUL Оверлея:

<?xml version="1.0"?>
<overlay id="sample" 
         xmlns="https://www.mozilla.org/keymaster/gatekeeper/there.is.only.xul">
 <statusbar id="status-bar">
  <statusbarpanel id="my-panel" label="Hello, World"/>
 </statusbar>
</overlay>

<statusbar> название status-bar определяет "точку слияния" в пределах окна браузера, к которой мы хотим присоединить.

<statusbarpanel> новый “виджет” который мы хотели бы вставить в пределах точки слияния.

Возьмите этот простой код и сохраните в новом файле с именем sample.xul и поместите его в директорию chrome/content.

Для получения дополнительной информации о присоединении “виджетов” и изменении пользовательского интерфейса, используя Оверлеи, см. далее.

Chrome URIs

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

В окне браузера: chrome://browser/content/browser.xul. Напечатайте этот URL в адресной строке Firefox!

Chrome URIs состоит из нескольких составляющих:

Во-первых, URI scheme схема (chrome), которая говорит сетевой библиотеке Firefox, что это Chrome URI. Указывает, что информационное наполнение URI, должно быть обработано как (chrome). В отличии от (chrome), (http) говорит Firefox обрабатывать URI как web-страницу.
Во-вторых, название пакета (browser, в примере выше), который идентифицирует пакет компонентов пользовательского интерфейса. Оно должно быть уникальным , чтобы избежать конфликтов между расширениями.
В-третьих, тип запрошенных данных. Есть три типа: content (XUL, JavaScript, связывания XBL, и т.д. которые формируют структуру и поведение приложения UI), locale (DTD.properties файлы и т.д, которые содержат строки для локализации UI), и skin (CSS и изображения, которые формируют тему UI)
Путь файла, для загрузки.

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

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

Создание установок Chrome

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

Откройте файл с названием chrome.manifest который Вы создали рядом с каталогом chrome в корне исходной иерархии директории Вашего Расширения.

Добавьте в него код:

content     sample    chrome/content/

(Не забывайте, косую черту "/"! Без этого пакет не будет зарегистрирован.)

Здесь определяется:

тип материала в пределах chrome пакета
название chrome пакета (удостоверьтесь, что Вы используете все символы в нижнем регистре для имени пакета ("sample"), так как во 2-й версии не поддерживается смешанные регистры и вы получите ошибку bug 132183
местоположение файлов chrome пакета

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

Заметьте, что content, locale и skin должны быть сохранены как каталоги, с соответствующими именами content, locale и skin в подкаталоге chrome.

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

Регистрация Оверлея

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

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

Эта строка говорит браузеру, присоединить sample.xul к browser.xul во время загрузки browser.xul.

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

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

Перейдите в папку вашего профиля по умолчанию. Папка вашего профиля по умолчанию, должна, находится где-то в папке профилей, например в Firefox/Profiles/<profile_id>.default/.
Откройте папку extensions. Если ранее вы уже устанавливали, какие либо расширения, то она должна уже существовать.
Создайте там, новый текстовый файл и запишите в него путь к папке с вашим расширением, например C:\extensions\my_extension\ или ~/extensions/my_extension/. Сохраните файл, указав в качестве имени идентификатор вашего Расширения, в нашем примере это[email protected].

(Не забывайте, косую черту, "/"! Без этого ваше расширение не будет зарегистрировано.)

(my_extension может не работать! Если имя папки содержит символы подчеркивания.)

Теперь всё готово для испытания вашего расширения!

Запустите Firefox. Firefox обнаружит ссылку на каталог вашего расширения и установит его. Когда появится окно браузера вы должны увидеть текст "Hello, World!" на правой стороне в панели статуса.

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

Упаковка

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

За "зипуйте" папку contents вашего Расширения (не саму папку расширения), и переименуйте получившийся zip файл, так чтобы он имел расширение .xpi. В Windows XP, вы можете сделать это очень просто, выбрав все файлы и вложенные папки в папке вашего расширения, и щелкнув правой кнопкой мыши и выбрав "Send To -> Compressed (Zipped) Folder". Zip файл будет создан. Просто переименуйте его, и готово!

В Mac OS X, вы можете нажать правой кнопкой мыши на папке contents вашего Расширения и выбрать "Создать архив ..." для создания архива. Однако, Mac OS X добавляет скрытые файлы в папку. Поэтому следует использовать Terminal, для удаления скрытых файлов (чьи имена начинаются с периода), а затем ввести в командной строке zip команду для создания архива.

В Linux, вы аналогичным образом можете использовать в командной строке Zip инструменты.

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

Теперь загрузите ваш .XPI файл на сервер, и сделайте, так чтобы он определялся как application/x-xpinstall. Вы можете давать ссылку на него и позволить людям скачивать и установить его. Для тестирования нашего. XPI файла можно просто перетащить его в окно менеджера расширений, открыв его через меню Tools -> Extensions в Firefox 1.5.0.x, или Tools -> Add-ons в более поздних версиях.

Установка с web-страниц

Существует множество путей, которыми вы можете устанавливать ваши расширения прямо с web-страниц, в том числе использование прямых ссылок на файлы XPI и использование InstallTrigger method объекта. Разработчикам расширений и веб разработчикам, рекомендуется использовать для установки XPI методы InstallTrigger, которые дают больше возможностей их пользователям.

Использование addons.mozilla.org

С помощью сайта Mozilla Add-ons вы может распространять ваше Расширение для бесплатного пользования. Вше расширение будет иметь зеркала на Mozilla, что обеспечит доступность вашего расширения, если оно станет очень популярным. Сайт Mozilla также упрощает установку расширений для пользователей , и автоматически сделает доступными ваши новые версии для пользователей вашей текущей версии, после того как вы загрузите их. Кроме того Mozilla Add-ons позволяет пользователям оставлять комментарии и тем самым обеспечивает обратную связь с Вашим Расширением. Настоятельно рекомендуется использовать Mozilla Add-ons для распространения ваших расширений!

Зайдите на https://addons.mozilla.org/developers/ создайте учётную запись и начинайте распространение ваших расширений!

Примечание:Ваше Расширение будет скачиваться быстрее и чаще, если у вас будет хорошее описание и скриншоты с вашим расширением в действии.

Регистрация расширений в реестре Windows

В Windows, информация о расширениях может быть добавлена в реестр, откуда Расширение автоматически будет извлекаться в следующий раз, при загрузке приложения. This allows application installers to easily add integration hooks as extensions. Для получения более подробной информации смотри Adding Extensions using the Windows Registry.

Подробнее о XUL Оверлеях

Помимо добавления UI виджетов, вы также можете использовать XUL фрагменты для:

Изменить атрибуты для "точки слияния", например <statusbar id="status-bar" hidden="true" /> (скрывается строка состояния)
Удалить "точку слияния" из главного документа, например, <statusbar id="status-bar" removeelement="true" />
Контроль позиции вставки “виджета”:

<statusbarpanel position="1" .../>

<statusbarpanel insertbefore="other-id" .../>

<statusbarpanel insertafter="other-id" .../>

Создание новых компонентов UI

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

Смотрите документацию по XUL на крупных ресурсах для разработчиков XUL.

Файлы По умолчанию

Файлы по умолчанию, которые вы используете для профиля пользователя, должны быть помещены в defaults/ в корень в иерархии папок вашего Расширения. По умолчанию .js файлы с настройками должны храниться в defaults/preferences/ - после того как вы поместите их туда они будут автоматически загружаться в системные настройки Firefox при запуске, так что вы сможете получить к ним доступ использую Preferences API.

Пример файла настроек по умолчанию:

pref("extensions.sample.username", "Joe"); //строка
pref("extensions.sample.sort", 2); //число
pref("extensions.sample.showAdvanced", true); //булево

XPCOM Components

Firefox поддерживает XPCOM компоненты в расширениях. Вы можете легко создавать свои собственные компоненты на JavaScript или C + + (с использованием Gecko SDK).

Поместите все ваши. JS или. DLL файлы каталог components/ - после установки расширения , они автоматически будут зарегистрированы при первом запуске Firefox.

Для получения дополнительной информации см. Как создать XPCOM компонент на JavaScript, Как создать XPCOM компонент с использованием Visual Studio и Cкниги по созданию XPCOM Компонентов.

Командная строка приложения

Один из возможных вариантов использования пользовательских XPCOM компонентов добавить в командную строку указатель для Firefox или Thunderbird. Вы можете использовать этот метод для запуска ваших расширений, как приложений:

 firefox.exe -myapp

I should move the useful parts of this to the Command Line page. -Nickolay This is done by adding a component containing the function... function NSGetModule(comMgr, fileSpec) { return myAppHandlerModule; } This function is run by firefox each time firefox is started. Firefox registers the myAppHandlerModule's by calling its 'registerSelf()'. Then it obtains the myAppHandlerModule's handler factory via 'getClassObject()'. The handler factory is then used to create the handle using its 'createInstance(). Finally, the handle's 'handle(cmdline)' processes the command line cmdline's handleFlagWithParam() and handleFlag(). Смотрите Chrome: Command Line , а также обсуждения на форуме.

Локализация

Для поддержки более чем одного языка, вы должны вместо отдельных строк из вашего содержимого использовать "сущности" или a href="mks://localhost/en/XUL_Tutorial/Property_Files" title="en/XUL_Tutorial/Property_Files">"связки строк". Это лучше делать в самом начале разработки Вашего Расширения, а не возвращаться, к этому позже!

Информация о локализации хранится в каталоге локализации расширения. Например, чтобы добавить локализацию для нашего расширения, создайте директорию с именем "locale" в каталоге chrome (где находится каталог "content" ) и добавьте следующую строчку в файл chrome.manifest:

locale sample en-US chrome/locale/en-US/

Для создания локализации , значения атрибута в XUL, вы вставляете его значение в .ent (или .dtd) файле который, затем помещаете каталог локализации и который выглядит так:

<!ENTITY  button.label     "Click Me!">
<!ENTITY  button.accesskey "C">

Затем, подключаете его в верхней части вашего XUL документа ( сразу под строкой ), вот так::

<!DOCTYPE window SYSTEM "chrome://packagename/locale/filename.ent">

где window это localName значение, которое является корневым элементом вашего XUL документа, и свойство SYSTEM значение которого chorm URI к файлу с сущностями. Для примера нашего расширения, мы используем корневой элемент overlay.

Для использования сущностей измените ваш XUL, что бы он выглядел так:

<button label="&button.label;" accesskey="&button.accesskey;"/>

Chrome реестр всегда будет загружать тот файл с сущностями, который соответствует текущей выбранной локализации.

Для строк которые вы используете в сценарии (скрипте), создайте файл .properties, текстовый файл который будет содержать строки в таком формате:

key=value

а, затем используйте nsIStringBundleService/nsIStringBundle или тег <stringbundle>, чтобы получить значения в сценарии (скрипте).

Understanding the Browser

Use the DOM Inspector to inspect the browser window or any other XUL window you want to extend.

Примечание: DOM Inspector не устанавливается в режиме стандартной установки Firefox. Начиная с версии Firefox 3 Beta 4, DOM Inspector доступен с сайта Firefox Add-ons, как автономное расширение. Для более ранних версий, вам необходимо переустановить FireFox в режиме Пользовательской установки и выбрать путь к DOM Inspector(или Developer Tools в Firefox 1.5), если DOM Inspector'a нет в меню Инструменты (Tools) в вашего браузера.

Используйте кнопку Point-and-click icon в верхнем правом углу панели инструментов DOM Inspector для визуального выбора интересующего элемента в окне XUL. После выбора элемента, в окне DOM inspector появится DOM иерархия интересующего Вас элемента.

Use the DOM Inspector's right side panel to discover merge points with ids that you can use to insert your elements from overlays. If you cannot discover an element with an id that you can merge into, you may need to attach a script in your overlay and insert your elements when the load event fires on the master XUL window.

Debugging Extensions

Analytical Tools for Debugging

The DOM Inspector - inspect attributes, DOM structure, CSS style rules that are in effect (e.g. find out why your style rules don't seem to be working for an element - an invaluable tool!)
Venkman - set breakpoints in JavaScript and inspect call stacks
arguments.callee.caller in JavaScript - access a function's call stack

printf debugging

Use dump("string") (see the link for details; this requires a bit of configuration to work properly)
Use Components.utils.reportError() or nsIConsoleService to log to the JavaScript console

Advanced debugging

Run a debug Firefox build and set breakpoints in Firefox itself, or your C++ components. For the experienced developer, this is often the fastest way to diagnose a problem. See Build Documentation and Developing Mozilla for more information.
See Debugging a XULRunner Application for more helpful tips.

Быстрый старт

Вы можете использовать Extension Wizard, инструмент для создания простых Расширений.

A Hello World extension similar to what you can generate with the Extension Wizard is explained line-by-line in another tutorial from MozillaZine Knowledge Base.