Nakładki XUL

UWAGA: Tłumaczenie tej strony nie zostało zakończone.
Może być ona niekompletna lub wymagać korekty.
Chcesz pomóc? | Dokończ tłumaczenie | Sprawdź ortografię | Więcej takich stron+.

Pliki oraz nakładki XUL

Nakładki to pliki XUL używane do opisu dodatkowej zawartości interfejsu użytkownika (UI). Za pomocą nakładek definiuje się często elementy UI dodane w wyniku aktualizacji lub poprawki jakiegoś rodzaju, ale mogą być też używane w inny sposób. Nakładki dostarczają ogólnego mechanizmu do:

  • dodawania UI do dodatkowych komponentów jak opisuje w przykładzie powyżej
  • nadpisywania małych części pliku XUL bez potrzeby zmiany całego UI
  • ponownego użycia części UI

Pliki oraz nakładki XUL współpracują w celu opisania pojedynczego dokumentu głównego. Pomimo tego, że nie ma formalnych zastrzeżeń odnośnie treści plików "bazowych" XUL jak i nakładek, to nakładki definiują przeważnie elementy niezdefiniowane w podstawowych wersjach UI, tj. dodatkowe komponenty. Gdy wtyczki, rozszerzenia przeglądarki, lub inne aplikacje dostarczają nowe elementy interfejsu użytkownika przeglądarki, to te elementy powinny zostać zdefiniowane w plikach nakładki. Przykładowo, przy instalacji wtyczek mediów mogą zostać dodane do interfejsu nowe ikony lub elementy menu:

SSP UI w przeglądarce

W pliku navigatorOverlay.xul lub navigatorSSPOverlay.xul (gdzie navigator.xul definiuje podstawowy interfejs użytkownika paczki nawigatora) te nowe elementy wtyczki będą zdefiniowane jako zbiór elementów lub poddrzew:

<menuitem name="Super Stream Player"/>

<menupopup name="SS Favorites">
 <menuitem name="Wave" src="mavericks.ssp"/>
 <menuitem name="Soccer" src="brazil_soccer.ssp"/>
</menupopup>

<titledbutton id="SSP" crop="right" flex="1"
              value="&SSButton.label;" onclick="FireSSP()"/>

Nakładki a atrybuty ID

Silnik nakładki używa atrybutu ID w celu określenia, gdzie będą dołączone elementy w pliku nakładki. Używaj tych samych ID w bazowym pliku XUL-a oraz w nakładce; w przeciwnym wypadku nie pojawią się żadne nowe elementy. W pliku bazowym wierzchołek rodzica elementów nakładki musi zostać nadany ID, jeśli jeszcze jego nie posiadają. Przykładowo element <menu> w poniższym poddrzewie powinien być rodzicem elementu menu Super Stream Player, tak że nadano mu ID file_menu:

<menu id="file_menu">
 <menuitem name="New"/>
 <menuitem name="Open"/>
 <menuitem name="Save"/>
 <menuitem name="Close"/>
</menu>

W pliku nakładki możesz "zsynchronizować" nowe elementy poprzez zrobienie ich dziećmi znacznika o tym samym ID w pliku nakładki. The layout engine takes the elements directly under the overlay tag with IDs and merges them with the corresponding nodes in the base file. The complete XUL overlay file for adding the single Super Stream Player menu item from the example above is as follows:

<?xml version="1.0"?>
<overlay id="singleItemEx"
         xmlns:html="http://www.w3.org/1999/xhtml"
         xmlns="http://www.mozilla.org/keymaster/gatekeeper/there.is.only.xul">
 <menu id="file_menu">
  <menuitem name="Super Stream Player"/>
 </menu>
</overlay>

Note that below menu in the base file and overlay in the overlay file, the subtrees are equivalent. Merged items can be arbitrarily nested subtrees: new wyskakujące menu may contain other popup submenus, extra paski narzędzi can overlay existing toolbars or appear beneath them, as the Personal Toolbar does below the Location Bar in Netscape's Communicator, etc. As long as the IDs of the elements appearing below the overlay tag in the overlay file and tag with the same ID in the base file, overlays support the merging of any valid subtree.

At the moment you can't overlay an element without an ID, so you need to użyj metod DOM to tweak the element you need in a load handler.

Wczytywanie nakładek

Overlays can be loaded explicitly or dynamically. When you load an overlay explicitly, it means that you intend to make it available every time the base file is loaded. Since one of the main purposes of overlays is to provide UI for additions or components to the basic package, explicit loading can be somewhat problematic when the overlay defines optional UI elements.

Loading Overlays Explicitly

A processing instruction is used to load overlay files explicitly into the master document. Inserting the following processing instruction before the DOCTYPE declaration in a base file tells the layout engine to load the named overlay file:

<?xul-overlay href="chrome://component/content/componentOverlay.xul"?>

where component is the name of the package being overlayed (e.g. chrome://navigator/content/navigatorOverlay.xul).

The layout engine loads any overlay files and then flows the resulting XUL document, so problems associated with incremental insertion in menus, boxes, tables, and forms are avoided. Any number of overlays can be loaded into a master document, and an overlay can also load other overlays. Because an overlay is superimposed on the master document, there are no ambiguities relating to scoping of style sheets of scripts. Style sheets and scripts loaded by the overlay simply apply to the entire master document.

Wczytywanie dynamicznych nakładek

The chrome registry makes it possible to load XUL overlays dynamically -- or only when necessary. The chrome registry, which is a special RDF datasource into which user-specific information is persisted, or stored, contains information about the components or additional packages that have been installed with the browser. When a component such as the "Super Stream Player" from the examples above is registered there, overlays associated with that component are loaded automatically. When the component is not present, only the base files are loaded.

Loading Overlays at Run-time

Firefox 1.5 and other Gecko 1.8-based applications also support loading overlays on-the-fly via document.loadOverlay function. TODO: elaborate

Overlays and Skins

Always load master skins from base files. Never load master skins from overlays.

Unlike base files, overlays should never load the master skin file for a package. The navigatorOverlay.xul file, for example, does not and should never load the navigator.css file that defines the master skin for the navigator package. Since the purpose of an overlay is to define new UI elements for a package within the context of that package's skin, the overlay should add structure but not new style. Any skins that are loaded by an overlay destructively replace the master skin for the base file, and can change the basic appearance of the package's skin in unfortunate ways.

The master skin is not the same as the global skin. For any package, the master skin file is that CSS file named after the package itself. The master skin file for the bookmarks package, for example, is called bookmarks.css, and is located in the skin/default subdirectory.

Overlaying Attributes

In addition to new elements and subtrees, you can also overlay attributes into existing elements. In XUL, attributes control important features of the skin like image sources, as in the following example, where an overlay destructively overwrites the image source in the base file with a replacement. In the base file, the HTML image element points to a Netscape GIF icon:

<html:img id="foo" src="netscapeImage.gif"/>

In the overlay, an element with the same ID attribute specifies a different image, and that image is superimposed on top of the original Netscape image as part of the merge process:

<html:img id="foo" src="mozillaImage.gif"/>

When the base file references an overlay file which contains the html image element above, the new src attribute is superimposed over original, and the Mozilla icon replaces the Netscape icon.

Overlay Positioning

XUL overlays also support positioning of nodes. You can specify a position attribute on a node in the overlay to provide a hint for insertion into the master document. In the following example, the last menu item, Example Four, will be placed just after the "New" menu item instead of being appended to the end of the menu like the other kids.

<overlay id="main-overlay" xmlns:html="http://www.w3.org/1999/xhtml"
         xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
         xmlns="http://www.mozilla.org/keymaster/gatekeeper/there.is.only.xul">
 <menu id="file_menu">
  <menuitem name="Example One"/>
  <menuitem name="Example Two"/>
  <menuitem name="Example Three"/>
  <menuitem name="Example Four" position="1"/>
 </menu>
</overlay>

The node with the position attribute orders itself to the top of the menu. The position can also be given for nodes in overlay files that will be ordered in a group of similar items in the base file. For example, if only the last menuitem above had been in an overlay and the other items were defined in the base file, the overlayed menuitem would still appear at the top of the parent menu.

UI Reuse with Overlays

One of the biggest benefits of using overlays is that it allows you to reuse groups of elements that appear frequently in the UI. The overlay mechanism allows you to merge elements into existing subtrees, but it also allows you to store common UI elements in overlay files and merge them into any base files that use them. Using the ID attribute on an otherwise empty node in the base file, you can essentially reference a subtree defined in an overlay file and merge it in wherever it's needed.

For example, the buttons that appear at the bottom of common dialogs, the OK and Cancel buttons, may be used in dozens of places in the UI. Rather than redefining this set of buttons each time they are necessary in a particular dialog, base XUL files can overlay the XUL file in which these buttons are defined, dialogOverlay.xul. (Actually, the implementation is one step more complicated than this: base files overlay dialogOverlay.xul from the global component directory, which in turn overlays a platform-specific XUL file such as platformDialogOverlay.xul. The mechanism is the same, however.)

Any dialog that wants to overlay these buttons just declares the overlay at the top:

<?xul-overlay href="chrome://global/content/dialogOverlay.xul"?>

And includes an empty box with an ID of okCancelButtons in the UI. The following snippet shows a dialog with custom UI elements at the top and a reference to the overlay's OK and Cancel buttons at the bottom:

<box align="horizontal" id="bx1" flex="100%" style="margin-bottom: 1em; width: 100%;">
 <html:input type="checkbox" id="dialog.newWindow"/>
 <html:label for="dialog.newWindow">&openWin.label;</html:label>
 <spring flex="100%"/>
</box>

<box id="okCancelButtons"/>

For more detail, see the OK and Cancel button definitions being referenced here in the global component file platformDialogOverlay.xul. Toolbars, submenus, boxes, and any other subtrees that appear in multiple places can be defined in overlays files in this way and referenced for reuse wherever necessary.


Czytaj dalej

Autorzy i etykiety dokumentu

Autorzy tej strony: Ptak82, Bedi, Mgjbot
Ostatnia aktualizacja: Bedi,