Join MDN and developers like you at Mozilla's View Source conference, 12-14 September in Berlin, Germany. Learn more at https://viewsourceconf.org

Файлы манифеста (Manifest)

В этой главе мы опишем, как собирать chrome и XUL файлы в пакеты и как создавать для этих пакетов файлы манифестов.

Пакеты

Пакет - это набор XUL файлов и сценариев, определяющих функциональность пользовательского интерфейса. Пакеты могут быть инсталлированы в Mozilla и на них можно ссылаться с помощью chrome URL-ов. Пакет может содержать любые типы файлов и может быть распределен по поддиректориям для разных частей пакета. На диске пакет может храниться либо в распакованном виде с своей папке, либо в виде JAR архива.
 

Файлы Манифеста

Файлы манифеста описывают пакет и отображают его расположение на диске на chrome URL. Файлы манифеста расположенные в папке chrome (<ApplicationDirectory>/chrome) считываются при запуске приложения Mozilla для того, чтобы определить, какие пакеты установлены. Это означает, что все, что вам необходимо сделать для того, чтобы установить новый пакет, это добавить новый файл манифеста либо в папку chrome приложения или в папку chrome определенного пользователя. Второй из вышеперечисленных вариантов можно использовать, если у вас нет достаточных прав на запись в папку самого приложения.

Если вы хотите только попробовать тестирование привилегированного XUL кода в браузере Firefox, вы можете легко сделать это использовав манифест, состоящий всего лишь из одной строки:

  1. Создайте новую папку где-нибудь на диске. Например на компьютере под управлением Windows вы можете создать папку "C:\testfiles".
  2. Создайте новый ASCII1 файл с именем test.manifest в папке chrome. Имя файла не имеет особого значения, главное, чтобы его расширение было .manifest. ( 1. не работает с UTF-8 с BOM.)
  3. Напишите в созданном файле строку:
 content tests file:///C:/testfiles/

Путь к файлам должен указывать на папку, которую вы создали на первом шаге. Если вы не уверены, каков путь к этой папке, откройте папку в браузере и скопируйте адрес из адресной строки.

Это все! Теперь все, что вам нужно сделать, это добавить несколько XUL файлов в эту новую папку, и вы сможете загружать их набирая chrome URL следующего вида "chrome://tests/content/tests.xul<filename>". Конечно же вам необходимо перезапустить браузер, чтобы внесенные изменения вступили в силу. Если же файл не загружается, проверьте, правильно ли вы указали путь к папке.

Базовый синтаксис строк файла манифеста для пакетов контента следующий:

'content <packagename> <filepath>'

Первое поле 'content' обозначает пакет контента. Для тем это будет 'skin', а 'locale' - соответственно для локалей. Название пакета в вышеприведенном примере - 'tests', что означает, что первое поле в chrome URL - это 'tests', как например chrome://tests/content/sample.xul. Если бы название пакета было 'browser', chrome URL выглядел бы так chrome://browser/content/browser.xul. Последнее поле - это путь к папке, в которой находятся файлы. Это может быть как путь к папке на локальном диске указанный как URL файла, так и к JAR архиву, указанному с помощью jar URL, который мы опишем ниже. Вы можете описать несколько пакетов включив еще строки в файл манифеста.

Файл browser.manifest, который используется в Firefox, выглядит примерно так:

content branding jar:browser.jar!/content/branding/ xpcnativewrappers=yes
content browser jar:browser.jar!/content/browser/ xpcnativewrappers=yes
overlay chrome://global/content/viewSource.xul chrome://browser/content/viewSourceOverlay.xul
overlay chrome://global/content/viewPartialSource.xul chrome://browser/content/viewSourceOverlay.xul
overlay chrome://browser/content/pageInfo.xul chrome://pippki/content/PageInfoOverlay.xul

Здесь перечислены два пакета, 'branding' и 'browser'. Также указаны три оверлея, что дает возможность объединять вместе контент из разных пакетов. В расширениях оверлеи используются максимально часто, так как расширения интегрируют свой интерфейс в интерфейс браузера.

Пути к файлам пакетов  'branding' и 'browser' используют JAR URL, поскольку контент упаковывается в архив. Архив JAR может быть создан с помощью утилиты ZIP. Для файла JAR, расположенного в каталоге chrome, синтаксис довольно прост:

jar:<filename.jar>!/<path_in_archive>

Для пакета 'browser' архив - browser.jar, располагается рядом с файлом манифеста в каталоге chrome. Путь 'content/browser' указывает путь внутри архива, в котором располагаются файлы XUL. Вам не требуется указывать путь, если у вас нет никаких каталогов в архиве. В этом случае файлы пакета 'branding' хранятся по другому пути в том же самом архиве.

Для пакета 'tests', созданного выше, файлы не упаковываются в архив, вместо этого используется прямой путь доступа к файлам. Это хорошо для разработки, так как вы не должны упаковывать все файлы каждый раз, когда вы изменяете их. Однако, при распространении приложения или расширения, вы скорее всего захотите упаковать их в архив, чтобы избежать необходимости устанавливать множество отдельных мелких файлов.

Часть xpcnativewrappers=yes в конце строки декларации - флаг, который может использоваться опционально. В JavaScript для веб-страницы возможно переопределить встроенные функции с их собственным кодом. Если используется флаг xpcnativewrappers, это указывает, что сценарии, выполняющиеся в привилегированном окружении, не вызывают эти переопределенные версии, а используют вместо этого исходные встроенные версии. Иначе, если бы расширение попыталось вызвать модифицированные версии, то оно, вероятно, не работало бы должным образом, или хуже, создало бы дыру в системе безопасности. Этот флаг был добавлен, чтобы предотвратить эту проблему и должен всегда использоваться для более новых расширений, но не учитывается для более старых расширений, которые могут быть несовместимыми с изменением. Для получения дополнительной информации об этой функции, см. XPCNativeWrapper.

Темы и локали

Для тем и локалей синтаксис сходен с используемым для пакетов контента, но вы всегда должны указывать пакет контента, для которого вы предоставляете тему или локаль. Например:
skin browser classic/1.0 jar:classic.jar!/skin/classic/browser/
locale browser en-US jar:en-US.jar!/locale/browser/

Для этого было добавлено новое поле, указывающее, что эти тема и локаль используются для браузера. Имя скина - 'classic/1.0'. В данном случае номер версии является частью названия темы, но это необязательно, если вы создаете свою собственную тему. Mozilla не обрабатывает номер версии каким-либо особенным образом; номер версии - это просто часть названия темы. Локаль - 'en-US'. Chrome URL-ы на которые отображаются эти элементы будут выглядеть так: chrome://browser/skin/browser.css и chrome://browser/locale/browser.dtd. Если вы создаете свою собственную тему или локаль для браузера, все, что вам необходимо - создать файл манифеста с одной из двух этих строк внутри него, измененной так, чтобы подходить к вашей теме или локали.

Более подробную информацию о темах см. здесь Темы. Более подробно о локалях см. здесь Локализация.

Наш пример диалога поиска файлов

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

 
content findfile file:///findfile/content/
skin findfile classic/1.0 file:///findfile/skin/
locale findfile en-US file:///findfile/locale/

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

Заметьте, как второе поле строк для скина и локали указывает 'findfile'. Это означает, что скин и локаль изменили пакет findfile, который был указан в первой строке. Три пути выше указывают подкаталоги для каждой части. Возможно вы захотите создать эти подкаталоги, чтобы держать все файлы по отдельности.

 

Установка пакета

Для того, чтобы установить приложение, вы должны сделать для него инсталлятор или включить его в инсталлятор другого приложения. Используемый метод зависит от того, какого рода приложение вы создаете. Для расширений вам необходимо будет создать файл install.rdf, который описывает, что именно будет установлено, кто является автором расширения и какая версия браузера или другого приложения совместима с вашим расширением. Необходима Особая структура папок, так как для расширений действуют ограничения на месторасположение, в которое они могут устанавливать свои файлы. Расширение упаковывается в XPI файл. XPI это сокращение от XPInstall и используется для установки компонентов Mozilla-ой. Подобно JAR файлу XPI это всего лишь ZIP архив, но с другим расширением, поэтому вы можете создавать XPI файлы с помощью ZIP архиватора.

Менеджер расширений Firefox выполняет установку расширений, упакованных в XPI файлы, автоматически. Рекомендуется выкладывать все расширения на Сайт дополнений Mozilla, на котором пользователи могут найти, чтобы установить. Конечно расширения можно устанавливать с любых сайтов, но другие сайты не сконфигурированы так, чтобы позволять установку по умолчанию.

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

Что касается самостоятельных приложений, то их можно упаковать с помощью программы XULRunner. При этом будет создан отдельный исполняемый файл, и приложение может быть установлено независимо от браузера.

Более подробно о создании расширений см. Расширения. Дополнительная информация о XULRunner, в главе XULRunner.

Устаревшие приложения

Если вы создаете приложения для устаревших версий программ Mozilla, т.е., до Firefox 1.5 или Mozilla 1.8, процесс немного усложняется. Ниже описано, как создать пакет для старых версий. Этот раздел можно пропустить, если вы создаете только новые расширения или XUL приложения.

Примечание: Этот устаревший процесс, но он тем не менее также используется и для нового продукта SeaMonkey 1.0. Ядро кода этого проекта еще не работает с новым форматом "Manifest".
<?xml version="1.0"?>

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

  <RDF:Seq about="urn:mozilla:package:root">
    <RDF:li resource="urn:mozilla:package:myapplication"/>
  </RDF:Seq>

  <RDF:Description about="urn:mozilla:package:myapplication"
          chrome:displayName="Application Title"
          chrome:author="Author Name"
          chrome:name="myapplication"
          chrome:extension="true"/>

</RDF:RDF>
content,install,url,file:///main/app/
  1. Создайте папку где-либо на вашем жестком диске. Многие создают подкаталог в папке chrome Mozilla, но это вовсе не обязательно. Папка может располагаться в любом месте на любом диске. Поместите ваши XUL файлы в эту папку.
  2. Создайте файл с именем "contents.rdf" и поместите его также в эту папку. Скопируйте текст из рамки ниже в ваш файл "contents.rdf". Этот файл используется для определения идентификатора приложения, его названия, автора, версии и т.п. данных.
  3. Измените выделенные части файлы выше на вашу собственную информацию. Текст 'myapplication' выделенный красным замените на ID вашего приложения. Вы можете выбрать любое название, но, как правило, ID делают совпадающим с названием всего приложения в целом. Замените выделенный синим цветом текст на название вашего приложения и имя его автора.
  4. Если поле 'chrome:extension' равно истине, приложение является расширение для Mozilla Firefox и будет отображаться в окне Расширений в настройках браузера. Если же вы установите значение "false", в окне расширений его видно не будет.
  5. Запишите "contents.rdf" и убедитесь, что он находится в папке, которую вы создали на шаге №1.
  6. Откройте <mozilla-directory>/chrome/installed-chrome.txt, где <mozilla-directory> - это папка, в которую установлена ваша Mozilla. Выйдите из Mozilla прежде чем выполнить данный шаг.
  7. Далее, вы должны зарегистрировать новое приложение в Mozilla, чтобы она знала, где его искать. Добавьте строку в конец файла "installed-chrome.txt", указывающую на новую, созданную вами на Шаге №1, папку. Измените выделенный текст на адрес папки в формате URL. Убедитесь в том, что в этой ссылке в конце строки стоит косая черта и что вы нажали Enter в конце строки, т.е. создали пустую строку. Если вы не уверены, каким должен быть URL, откройте папку, созданную на Шаге №1 в браузере Mozilla и скоируйте URL из поля адреса. Помните, что ссылка эта должна быть адресом папки, но не файла.
  8. Удалите файл <mozilla-directory>/chrome/chrome.rdf.
  9. Запустите Mozilla. Вам должны быть доступны любые XUL файлы, которые вы поместили в папку, с помощью URL вида: chrome://applicationid/content/file.xul где "file.xul" - это имя файла. Главный XUL файл, который вы можете загрузить с помощью URL ярлыка chrome://applicationid/content/, будет иметь вид "applicationid.xul".

Если вы создаете части скина и/или локали, повторите вышеприведенные шаги, с отличием в том, что формат файла "contents.rdf" будет несколько иным. Вы можете посмотреть на файлы "contents.rdf" других приложений, чтобы узнать подробности.

Выявление неисправностей

Создание chrome пакетов часто может быть довольно сложным и выявить возникающие проблемы непросто. Ниже приводится несколько советов на тот случай, если у вас что-то застопорилось.

  • Откройте файл <mozilla-directory>/chrome/chrome.rdf. Вы найдете там ссылки на ваш ID приложения. Если его там нет, что-то неверно с регистрацией. Если он там есть, возможно вы используете неверный chrome URL при загрузке файла.
  • Попробуйте удалить файл <mozilla-directory>/chrome/chrome.rdf. Он будет создан заново. Также удалите полностью папку <mozilla-directory>/chrome/overlayinfo/, если вы используете оверлеи.
  • Убедитесь, что URL в строке, которую вы добавили в installed-chrome.txt, заканчивается косой чертой, а сам файл завершается пустой строкой.
  • В ОС Windows, URL файлов выглядят так "file:///C|/files/app/", где "C" - буква диска.
  • Убедитесь, что файл "contents.rdf" находится в правильной папке и составлен правильно. Откройте файл "contents.rdf" в Mozilla, чтобы проверить, что он парсится, как валидный XML. Если это не так, вы увидите сообщение об ошибке на желтом фоне.
  • Если вы используете отладочную сборку (build) Mozilla, при запуске на терминал будет выведена некоторая информация, сообщающая, какие chrome приложения проверяются. Посмотрите, есть ли ваше приложение в этом списке.
  • Сообщение об ошибке "XML Parsing Error: undefined entity" в вашем XUL файле может быть вызвано ошибкой в манифесте или в jar файле, на который есть ссылка в манифесте. Например, в <!DOCTYPE window SYSTEM "chrome://fireclipse/locale/fireclipse.dtd"> файл dtd должен существовать и его папка должна быть правильно адресована в манифесте "locale", в противном случае при парсинге XML произойдет ошибка.

Более подробную информацию о файлах манифеста см. Регистрация Chrome.

В следующей главе мы приступаем к более подробному описанию языка XUL.

Метки документа и участники

 Внесли вклад в эту страницу: Roman.Kulikov, teoli, RedFox
 Обновлялась последний раз: Roman.Kulikov,