в верхнем правом углу панели инструментов DOM Inspector для визуального выбора интересующего элемента в окне XUL. После выбора элемента, в окне DOM inspector появится DOM иерархия интересующего Вас элемента.Этот урок по шагам покажет Вам как создать простое Расширение – сутью которого является добавление в панель статуса 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="http://www.w3.org/1999/02/22-rdf-syntax-ns#" xmlns:em="http://www.mozilla.org/2004/em-rdf#"> <Description about="urn:mozilla:install-manifest"> <em:id>sample@example.net</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>http://www.example.com/</em:homepageURL> </Description> </RDF>
<em:type>2</em:type> -- объявляет, что устанавливается именно расширение. Если бы Вы устанавливали тему, то это было бы 4 ( Install Manifests#type for other type codes).(В 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 с полным перечнем основных и дополнительных свойств.
Сохраните файл.
Пользовательский интерфейс 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 Оверлея:
<?xml version="1.0"?>
<overlay id="sample"
xmlns="http://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.
Для получения дополнительной информации о присоединении “виджетов” и изменении пользовательского интерфейса, используя Оверлеи, см. далее.
XUL Файлы - это часть пакета Chrome Packages - пакета компонентов пользовательского интерфейса, которые загружаются через chrome://URIs. Вместо того, чтобы загружать их диска, используя file://URI (так как местоположение Firefox в системе может меняться от платформы к платформе и от системы к системе), разработчики Mozilla придумали решение, которое позволяет создать URIs к информационному наполнению XUL, о котором знает установленное приложение.
В окне браузера: chrome://browser/content/browser.xul. Напечатайте этот URL в адресной строке Firefox!
Chrome URIs состоит из нескольких составляющих:
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 Manifest.
Откройте файл с названием chrome.manifest который Вы создали рядом с каталогом chrome в корне исходной иерархии директории Вашего Расширения.
Добавьте в него код:
content sample chrome/content/
(Не забывайте, косую черту "/"! Без этого пакет не будет зарегистрирован.)
Здесь определяется:
Эта строка говорит, что для 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/.C:\extensions\my_extension\ или ~/extensions/my_extension/. Сохраните файл, указав в качестве имени идентификатор вашего Расширения, в нашем примере этоsample@example.net.(Не забывайте, косую черту, "/"! Без этого ваше расширение не будет зарегистрировано.)
(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-страниц, в том числе использование прямых ссылок на файлы XPI и использование InstallTrigger method объекта. Разработчикам расширений и веб разработчикам, рекомендуется использовать для установки XPI методы InstallTrigger, которые дают больше возможностей их пользователям.
С помощью сайта Mozilla Add-ons вы может распространять ваше Расширение для бесплатного пользования. Вше расширение будет иметь зеркала на Mozilla, что обеспечит доступность вашего расширения, если оно станет очень популярным. Сайт Mozilla также упрощает установку расширений для пользователей , и автоматически сделает доступными ваши новые версии для пользователей вашей текущей версии, после того как вы загрузите их. Кроме того Mozilla Add-ons позволяет пользователям оставлять комментарии и тем самым обеспечивает обратную связь с Вашим Расширением. Настоятельно рекомендуется использовать Mozilla Add-ons для распространения ваших расширений!
Зайдите на http://addons.mozilla.org/developers/ создайте учётную запись и начинайте распространение ваших расширений!
Примечание:Ваше Расширение будет скачиваться быстрее и чаще, если у вас будет хорошее описание и скриншоты с вашим расширением в действии.
В Windows, информация о расширениях может быть добавлена в реестр, откуда Расширение автоматически будет извлекаться в следующий раз, при загрузке приложения. This allows application installers to easily add integration hooks as extensions. Для получения более подробной информации смотри Adding Extensions using the Windows Registry.
Помимо добавления 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" .../>
Вы можете создавать ваши собственные окна и диалоговые окошки в отдельных .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); //булево
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>, чтобы получить значения в сценарии (скрипте).
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) в вашего браузера.
Используйте кнопку в верхнем правом углу панели инструментов 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.
Analytical Tools for Debugging
arguments.callee.caller in JavaScript - access a function's call stackprintf debugging
dump("string") (see the link for details; this requires a bit of configuration to work properly)Components.utils.reportError() or nsIConsoleService to log to the JavaScript consoleAdvanced debugging
Вы можете использовать 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.