Kurs XUL:Pliki manifestu

z Mozilla Developer Center, polskiego centrum programistów Mozilli.

W tym artykule zobaczymy jak umieścić chrome i pliki XUL w paczce oraz stworzyć dla niej pliki manifestu.

[edytuj] Paczki

Paczka to zbiór plików XUL oraz skryptów, które definiują funkcjonalność interfejsu użytkownika. Paczki mogą być zainstalowane w przeglądarce Mozilla i odnosić się poprzez adres URL chrome. Paczka zawiera różnego rodzaju pliki i może być podzielona na podkatalogi dla różnych części paczki. Paczka jest przechowywana jako katalog lub jako archiwum JAR.

[edytuj] Pliki manifestu

Plik manifestu opisuje paczkę i mapę lokalizacji na dysku do adresu URL chrome. Pliki manifestu w katalogu chrome będą wykonywane, kiedy aplikacja Mozilli zostanie uruchomiona, aby zobaczyć jakie paczki zostały zainstalowane. To znaczy, że wszystko potrzebne do wykonania instalacji nowej paczki jest dodany nowy plik manifestu albo do katalogu aplikacji chrome albo użytkownik wskaże określony katalog chrome. Z dwóch katalogów chrome jest normalnie używany jeden od katalogu aplikacji mogącego nie mieć dostatecznych uprawnień do zapisanego w nim.

Jeśli tylko chcesz wypróbować uprzywilejowany kod XUL w przeglądarce Firefox, możesz to zrobić w prosty sposób poprzez użycie manifestu z zawartą w sobie jedną linią:

1. Gdziekolwiek utwórz nowy katalog. Na przykład, używając Windows możesz skorzystać C:\testfiles
2. Utwórz nowy plik ASCII¹ i nazwij go test.manifest w katalogu chrome. W tym momencie nie jest w ogóle ważne jak się on nazywa, ważne żeby miał rozszerzenie .manifest. _{( 1. nie działa z UTF-8 z BOM)}
3. Dodaj następującą linie do niego:

 content tests file:///C:/testfiles/

Ścieżka pliku w tej linii powinna wskazywać na katalog utworzony powyżej. Jeśli nie jesteś pewien(a), co jest ścieżką pliku, otwórz ten katalog i skopiuj adres URL z paska adresu.

To jest to! Teraz, wszystko co jeszcze musisz zrobić to jest dodanie jakiegoś pliku XUL do tego nowego folderu i będziesz mógł go wczytać wpisując adres URL w formie chrome://tests/content/<filename>. Oczywiście musisz uruchomić ponownie przeglądarkę, żeby zmiany dały efekt. Jeśli plik się nie wczytał, sprawdź czy wpisałeś poprawną ścieżkę.

Prosta składnia linii kodu w pliku manifestu dla zawartości paczki jest:

'content <packagename> <filepath>'

Pierwsze pole 'content' sygnalizuje zawartość paczki. Dla motywów, 'skin' is used while 'locale' is used for locales. The packagename is the example above is 'tests', which means that the first field in the chrome URL is 'tests' as in chrome://tests/content/sample.xul. If the package name was 'browser', the chrome URL would be chrome://browser/content/. The final field is the path where the files are located. This can be either a local file path using a file URL or a JAR archive using a jar URL, which will be described in a moment. You can specify multiple packages by including another line in the manifest file.

Plik browser.manifest użyty przez Firefoksa wygląda tak jak ten:

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

Two packages are listed here, 'branding' and 'browser'. Three overlays are also specified, which allow content from different packages to combine together. Extensions will make the most use of overlays, since they merge their UI with the browser UI.

The file paths for the branding and browser packages use jar URLs as the content is packaged up into an archive. A JAR archive can be created with a ZIP utility. For a JAR file located in the chrome directory, the syntax is fairly simple:

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

For the browser package, the archive is browser.jar, located alongside the manifest file in the chrome directory. The path 'content/browser' specifies the path inside the archive where the XUL files are located. You won't need to specify a path if you don't have any directories in the archive. In this case, there is, since the files for the branding package are stored in a different path in the same archive.

For the 'tests' package created above, the files are not packaged into an archive, so a direct file path is used instead. This is good for development since you don't have to package up all the files every time you change them. However, when distributing an application or extension, you will want to package them into an archive to avoid having to install lots of smaller files.

The xpcnativewrappers=yes part at the end of the manifest line is a flag that may optionally be used. In JavaScript, it is possible for a web page to override built-in functions with their own code. If the xpcnativewrappers flag is specified, it indicates that scripts running in a privileged context don't call these overriden versions, but the original built-in versions instead. Otherwise, if an extension attempted to call the modified versions, it would likely not work properly, or worse, create a security hole. This flag was added to prevent this problem and should always be used for newer extensions, but is left out for older extensions that might not be compatible with the change.

[edytuj] Motywy i pliki lokalizacji

The themes and locales, the syntax is similar as for content packages, but you also need to specify the content package you are providing a theme or locale for. For example:

skin browser classic/1.0 jar:classic.jar!/skin/classic/browser/
locale browser en-US jar:en-US.jar!/locale/browser/

For these, the extra field has been added to indicate that the skin and locale applies to the browser. The skin name is 'classic/1.0'. In this case, a version number is being used as part of the theme name, but that is optional if you are making your own theme. Mozilla doesn't handle the version number in a special way; the version number is just part of the theme name. The locale is 'en-US'. The chrome URLs that these would map to would be chrome://browser/skin and chrome://browser/locale. If you were creating your own theme or locale for the browser, all you need to do is create a manifest file with one of these two lines in it, modified to suit your theme or locale.

Aby dowiedzieć się więcej nt. motywów, zobacz Motywy. Aby dowiedzieć się więcej nt. lokalizacji, zobacz Lokalizacja.

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

[edytuj] Instalowanie paczki

For an application to be installed, you will need to create an installer for it, or include it as part of another application. The method used depends on what kind of application you are creating. For extensions, you will need to create an install file install.rdf which describes what will be installed, the author of the extension and which versions of the browser or other applications it is compatible with. A specific directory structure is needed as well since extensions are limited in where the files may be installed to. An extension is packaged up into an XPI file. XPI is short for XPInstall and is used by Mozilla to install components. Like a JAR file, an XPI file is just a ZIP file with a different extension, so you can create and view XPI files with a ZIP utility.

Firefox's extension manager handles installing extensions packaged into XPI files automatically. It is recommended to upload extensions to the Mozilla Add-ons site, where users can locate them for installation. While they may be installed from any site, other sites are not configured to allow installations by default.

It is also possible to use a install script written in JavaScript to install files. This allows you to copy files to any location and perform other file management tasks. However, applications installed with a script will not be listed in the extension manager and there is no automated method to uninstall them. For this reason, the install scripts are not used often.

For standalone applications, they can be packaged up using XULRunner. This allows a separate executable file, and the application may be distributed independently of a browser.

For more information about creating extensions, see rozszerzenia. For more information about XULRunner, see XULRunner.

[edytuj] Starsze aplikacje

If you are creating applications for older versions of Mozilla software, that is, before Firefox 1.5 or Mozilla 1.8, the process is a bit more involved. The following describes how to set up a package for earlier versions. This section may be skipped if you are writing new extensions or XUL applications.

1. Create a directory somewhere on your disk. Many people put this as a subdirectory inside Mozilla's chrome directory, but this isn't necessary. The directory could be anywhere and on any disk. Put your XUL files in this directory.
2. Create a file called contents.rdf and place it in this directory. Copy the text in the box below into the new contents.rdf file. This file is used to identify the application id, its name, author, version and so on.

<?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>

3. Change the highlighted parts of the file above to your own information. The red text 'myapplication' should be the ID of your application. You make this up, but typically, the ID is similar to your application's name. Replace the blue highlighted text above with your application's title and author.
4. If the 'chrome:extension' field is true, the application is a Mozilla Firefox Extension and it will show up in the Extensions window of the browser. If false, it will not appear.
5. Save the contents.rdf and make sure it is in the directory you created in step 1.
6. Open the file <mozilla-directory>/chrome/installed-chrome.txt, where <mozilla-directory> is the directory where Mozilla is installed. Exit Mozilla before you do this.
7. Next, you are going to register the new application with Mozilla so it will know where to find it. Add a line at the end of installed-chrome.txt pointing to the new directory you created in step 1. Change the highlighted text to the file URL below of the directory. Make sure that it URL ends with a slash and that you press enter at the end of the line. If you aren't sure what the URL is, open the directory created in step 1 into a Mozilla browser and copy the URL from the location field. Note that the reference should always be a directory, not a file.

content,install,url,file:///main/app/

8. Delete the file <mozilla-directory>/chrome/chrome.rdf.
9. Start Mozilla. You should be able to view any XUL files you put into the directory using a URL of the form: chrome://applicationid/content/file.xul where file.xul is the filename. Your main XUL file should be applicationid.xul which you can load using the shortcut URL chrome://applicationid/content/.

If you are creating skin and/or locale portions, repeat the steps above, except that the format of the contents.rdf file is slightly different. Look at the contents.rdf files in other applications for details.

[edytuj] Usuwanie nieprawidłowości

Tworzenie pakietu chrome może być często skomplikowane i jest trudne do zdiagnozowania w przypadku jakichkolwiek problemów. Znajduje się tu kilka porad w przypadku, gdybyśmy nie mogli sobie poradzić.

• Otwórz plik <mozilla-directory>/chrome/chrome.rdf. Powinniśmy tam znaleźć odniesienie do ID swojej aplikacji. Jeśli nie, coś poszło źle podczas rejestracji. Jeśli jednak tam są, to jest prawdopodobne, że używasz złego adresu URL chrome, kiedy wczytujesz plik.
• Spróbuj usunąć plik <mozilla-directory>/chrome/chrome.rdf. Zostanie on odnowiony. Usuń także cały katalog <mozilla-directory>/chrome/overlayinfo/, jeśli stosujemy nakładki.
• Upewnij się, że adres URL w linii dodanej do installed-chrome.txt kończy się znakiem slash i sam plik kończy się pustą linią.
• W Windows adresy URL pliku są często w formie file:///C|/files/app/, gdzie C to litera partycji dysku.
• Upewnij się, że plik contents.rdf jest w odpowiednim katalogu i jest w odpowiednim typie. Otwórz ten plik w Mozilli, żeby zobaczyć czy jest rozpoznawany jako typ XML. Jeśli nie, ujrzysz błąd na żółtym tle.
• Jeśli używasz debugera Mozilli, niektóre informacje będą wpisane do terminala podczas startowania, pokazując które aplikacje chrome są sprawdzane. Sprawdź czy twoja aplikacja jest na liście.

Aby dowiedzieć się więcej, przeczytaj artykuł o rejestracji Chrome.

W następnym artykule rozpoczniemy już naukę języka XUL.