Szablony

Wypełnianie elementami

XUL dostarcza metody, w których możemy tworzyć elementy za pomocą kodu RDF, albo pochodzące z pliku RDF lub pochodzące z własnych źródeł. Liczne źródła danych są dostarczane z Mozilli także jako podręczniki, historia i wiadomości e-mail. Więcej informacji znajduje się w następnym artykule.

Często, elementy takie jak elementy drzewa i elementy menu będą wypełnione danymi. Jednakże, będziesz chciał używać jej zdefiniowanej dla specjalnych warunków. Niemniej jednak, rozpoczniemy z tymi innymi elementami, ponieważ drzewa i menu potrzebują więcej kodu.

Pozwolenie na tworzenie elementów opartych na kodzie źródłowym, potrzebujesz przygotować prosty szablon, który będzie tworzony jako duplikat na każdym elemencie. Istotnie, tworzymy pierwszy element, który pozostanie jako konstrukcja na pozostałych elementach.

Szablon jest tworzony używając elementu template. Wewnątrz, możesz położyć te elementy, które chcesz użyć do skonstruowania elementu. Elementy template powinny być umieszczone wewnątrz zbioru, który stanowi stworzone elementy. Na przykład jeśli używasz drzewa, powinieneś położyć element template do wewnątrz elementu tree.

Przykład prostego szablonu

Lepiej będzie to wytłumaczyć na przykładzie. Weźmy prosty przykład gdzie chcemy utworzyć przycisk dla każdej górnego-poziomu zakładki. Mozilla dostarcza kod źródłowy zakładek tak więc mogą być one użyte do pobrania danych. Ten przykład będzie potrafił tylko pobrać zakładek górnego-poziomu (lub folderów zakładek) jakie będziemy chcieli używać jako przyciski. Dla potomnych zakładek, będziemy potrzebować do użycia elementu do wyświetlenia hierarchii takiej jak drzewo lub menu.

Aby obejrzeć ten przykład, utwórz pakiet chrome i wczytaj z niego pliki. Możesz teraz potwierdzić adres URL chrom wpisując go do przeglądarki URL.

var el = env.locale; Przykład 1 : Źródła

<vbox datasources="rdf:bookmarks" ref="NC:BookmarksRoot" flex="1">
  <template>
    <button uri="rdf:*" label="rdf:https://home.netscape.com/NC-rdf#Name"/>
  </template>
</vbox>

Powyżej zostało stworzone pionowe pole okna, które stanowi kolumnę przycisków, każda jedna zakładka jest wyrównywana do górnego poziomu. Możesz zobaczyć jak template stanowi pojedynczy button. Używany jest w liczbie mnogiej dla wszystkich potrzebnych przycisków do tworzenia. Możesz obejrzeć grafikę gdyż ustawienia przycisków zostały utworzone, jeden dla każdej zakładki.

Spróbuj dodać zakładkę do przeglądarki podczas gdy masz otwarte okno przykładu. Zostaniemy natychmiast powiadomieni, że przyciski z przykładu zostały zaktualizowane (możesz skupić się na tej zmianie).

Kontener i źródła danych

Szablon samoczynnie umieści się w pionowym polu. Pole posiada dwa specjalne atrybuty używane w szablonach, które są użyte tam skąd pochodzą dane. Pierwszy atrybut pola jest to atrybut datasources. Jest on użyty do deklaracji w co kod źródłowy RDF będzie zaopatrywał tworzony element. W tej sytuacji, są użyte rdf:bookmarks. Możemy prawdopodobnie przypuszczać jakie znaczenie ma użyty kod źródłowy, który został dostarczony przez Mozillę. Aby użyć własnego kodu źródłowego, używamy określonego adresu URL dla pliku RDF zawierającego atrybut datasources, jak pokazuje poniższy przykład:

<box datasources="chrome://zoo/content/animals.rdf"
     ref="https://www.some-fictitious-zoo.com/all-animals">

Możesz podać wiele źródeł danych poprzez oddzielnie ich za pomocą spacji w wartości atrybutu. Używa się tego do wyświetlenia danych z wielu źródeł.

Atrybut ref oznacza, z którego źródła chcesz pobierać dane. W przypadku zakładek wartość NC:BookmarksRoot jest użyta do wskazania podstawy hierarchii zakładek. Inne wartości do użycia zależą od źródła danych. Jeśli używasz jako źródło własnego pliku RDF wartość ta odpowiadała będzie zwykle wartości atrybutu about w RDF-ie Bag, Seq lub elementowi Alt.

Wewnątrz szablonu

By adding these two attributes to the box above, it allows the generation of elements using the template. However, the elements inside the template need to be declared differently. You may notice in the example above that the button has a uri attribute and an unusual value for the label attribute.

An attribute value inside the template that begins with 'rdf:' indicates that the value should be taken from the datasource. In the example earlier, this is the case for the label attribute. The remainder of the value refers to the name property in the datasource. It is constructed by taking the namespace URL used by the datasource and appending the property name. If you don't understand this, try re-reading the last part of the previous section. It explains how resources in RDF can be referred to. Here, we only use the name of the bookmark but numerous other fields are available.

The label of the buttons is set to this special URI because we want the labels on the buttons to be set to the names of the bookmarks. We could have put a URI in any of the attributes of the button, or any other element. The values of these attributes are replaced with data supplied by the datasource which, in this case, is the bookmarks. So we end up with the labels on the buttons set to the names of the bookmarks.

The example below shows how we might set other attributes of a button using a datasource. Of course, this assumes that the datasource supplies the appropriate resources. If a particular one is not found, the value of the attribute will be set to an empty string.

<button class="rdf:https://www.example.com/rdf#class"
        uri="rdf:*"
        label="rdf:https://www.example.com/rdf#name"
        crop="rdf:https://www.example.com/rdf#crop"/>

As you can see, you can dynamically generate lists of elements with the attributes provided by a separate datasource.

The uri attribute is used to specify the element where content generation will begin. Content earlier will only be generated once whereas content inside will be generated for each resource. We'll see more about this when we get to creating templates for trees.

Atrybut '''uri''' jest użyty w stosunku do specyficznych elementów gdzie zawartość wygenerowana będzie na początku. Zawartość

Więcej przykładów

Poprzez dodawanie tych funkcjonalności do kontenera będącego w szablonie (który w tym przypadku jest prostokątem) i do elementów szablonu, możemy wygenerować różnorodne spisy treści zewnętrznej. Oczywiście, możemy umieścić więcej niż jeden element wewnątrz szablonu i dodać specjalnie referencje RDF do atrybutów elementów. Poniższy przykład demonstruje to.

var el = env.locale; Przykład 2 : Źródła

<vbox datasources="rdf:bookmarks" ref="NC:BookmarksRoot" flex="1">
  <template>
    <vbox uri="rdf:*">
      <button label="rdf:https://home.netscape.com/NC-rdf#Name"/>
      <label value="rdf:https://home.netscape.com/NC-rdf#URL"/>
    </vbox>
  </template>
</vbox>

Przykład ten utworzy pionowy box z przyciskiem i etykietą dla każdej zakładki. Przycisk posiada nazwę zakładki, a etykieta to jest URL.

Nowe elementy są utworzone jako funkcjonalne, jedyne, nie inne potrafią wpisać się bezpośrednio w plik XUL. Atrybut id jest dodawany do każdego elementu utworzonego poprzez szablon, który jest ustawiony na wartość, która identyfikuje zasoby kodu. Możesz używać tego do identyfikacji swoich zasobów.

Możesz także wyszczególnić wielokrotną wartość źródła w tym samym atrybucie poprzez odseparowanie go spacją, jak w przykładzie poniżej. Więcej o składni źródła (XULPlanet).

var el = env.locale; Przykład 3 : Źródła

<vbox datasources="rdf:bookmarks" ref="NC:BookmarksRoot"
     flex="1">
  <template>
    <label uri="rdf:*" value="rdf:https://home.netscape.com/NC-rdf#Name rdf:https://home.netscape.com/NC-rdf#URL"/>
  </template>
</vbox>

Jak są budowane szablony

Kiedy element posiada atrybut datasources, to sygnalizuje, że ten element oczekuje na budowę poprzez formularz szablonu. Note that it isn't the template tag that determines whether content is built, it is the datasources attribute. When this attribute is present, an object called a Builder is added to the element. It is this object that is responsible for building the content from the template. In JavaScript you can access the builder object with the builder property, although usually you would only need to do this to have the builder regenerate the content in situations where it is not done automatically.

Istnieją dwa rodzaje kreatorów. Pierwszym, najczęściej używanym, jest kreator treści, natomiast drugi to kreator drzewek stosowany jedynie do drzewek.

Kreator treści

The content builder takes the content inside the template element and duplicates it for each row. For instance, if the user had ten bookmarks in the example above, ten label elements would be created and added as children of the vbox element. If you were to use DOM functions to traverse the tree, you will find these elements there and can query their properties. These elements get displayed, but the template itself is not displayed, although it still exists the the document tree. In addition, the id of each of the labels will be set to the RDF resource for that row.

Kreator treści zawsze rozpoczyna pracę od miejsca gdzie wyspecyfikowany jest uri="rdf:*". Jeśli atrybut uri jest umieszczony na niższym elemencie w drzewku, zewnętrze elementy są stworzone tylko raz. W poniższym przykładzie, jeden hbox będzie stworzony i wypełniony napisem dla każdej pozycji.

<template>
  <hbox>
    <label uri="rdf:*" value="rdf:https://home.netscape.com/NC-rdf#Name"/>
  </hbox>
</template>

Jeśli treść znajduje się wewnątrz elementu z atrybutem datasources i na zewnątrz szablonu, treść także się ukaże. Idąc tą drogą, możesz mieszać stałą i dynamiczną treść szablonu.

Kreator drzewek

The tree builder, on the other hand, doesn't generate the DOM elements for the rows. Instead, it gets the data directly from the RDF datasource whenever it needs it. Since trees are often expected to display thousands of rows of data, this is much more efficient. Creating an element for every cell would be too costly. However, the tradeoff is that trees may only display text, and, since no elements are created, you can't use CSS properties to style tree cells in the same way.

Kreator drzewek jest używany wyłącznie do drzewek. Inne elementy są tworzone poprzez kreator treści. To nie powinno być problemem, choć inne elementy - jak na przykład menu - nie powinny wyświetlać zbyt dużo składników. Możliwe jest także użycie kreatora drzewek, stosując element treeitem i inne, odnoszące się do tego elementy będą stworzone w każdym rzędzie.

Zasady

In the image of the earlier example, you may have noticed that the third button is simply a button with hyphens on it. This is a separator in the bookmark list. In the way that we have been using it, the RDF bookmarks datasource supplies the separators as if they were just regular bookmarks. What we would really like to do is add a small amount of spacing instead of a button for separator resources. That means that we want to have two different types of content be created, one type for regular bookmarks and a second type for separators.

Możemy zrobić to dzięki użyciu elementu rule. Definiujemy reguły dla każdego odchylenia elementów, które chcielibyśmy stworzyć. W naszym przypadku, potrzebujemy regułę dla zakładek i regułę dla separatorów. Atrybuty umiejscowiono na elemencie rule określają które reguły należy zaakceptować przy zasobach RDF.

When scanning for which rule applies to the data, each rule element is checked in sequence for a match. That means that the order in which you define rules is important. Earlier rules will override later rules.

Przykład użycia zasady

Przedstawiony przykład demonstruje wcześniejszy przykład z dwiema zasadami:

var el = env.locale; Przykład 4 : Źródła

<window
  id="example-window"
  title="Bookmarks List"
  xmlns:html="https://www.w3.org/1999/xhtml"
  xmlns:rdf="https://www.w3.org/1999/02/22-rdf-syntax-ns#"  
  xmlns="https://www.mozilla.org/keymaster/gatekeeper/there.is.only.xul">

 <vbox datasources="rdf:bookmarks" ref="NC:BookmarksRoot" flex="1">
   <template>

    <rule rdf:type="https://home.netscape.com/NC-rdf#BookmarkSeparator">
     <spacer uri="rdf:*" height="16"/>
    </rule>

    <rule>
      <button uri="rdf:*" label="rdf:https://home.netscape.com/NC-rdf#Name"/>
    </rule>
  
  </template>
 </vbox>

</window>

By using two rules, we have allowed the contents of the template to be selectively generated. In the first rule, bookmark separators are selected, as can be seen by the rdf:type attribute. The second rule does not have any attributes so all data matches it.

All of the attributes placed on the rule tag are used as match criteria. In this case, the bookmarks datasource supplies a rdf:type property to distinguish separators. This attribute is set to a special value for separators in the RDF bookmarks datasource. This is how we can distinguish them from non-separators. You can use a similar technique for any attribute that might be on an RDF Description element.

The special URL value given in the example above for the first rule is used for separators. That means that separators will follow rule one and generate a spacer element, which will display a 16 pixel gap. Elements that are not separators will not match rule one and will fall through to rule two. Rule two does not have any attributes on it. This means that it will match all data. This is, of course, what we want to have happen to the rest of the data.

You should also have noticed that because we wanted to get an attribute from the RDF namespace (rdf:type), we needed to add the namespace declaration to the window tag. If we didn't do this, the attribute would be looked for in the XUL namespace. Because it does not exist there, the rule will not match. If you use attributes in your own custom namespace, you need to add the namespace declaration in order to match them.

You should be able to guess what would happen if the second rule was removed. The result would be a single spacer displayed but no bookmarks because they don't match any of the rules.

Put simply, a rule matches if all of the attributes placed on the rule element match the corresponding attributes on the RDF resource. In the case of an RDF file, the resources would be the Description elements.

There are some small exceptions however. You cannot match based on the attributes id, rdf:property or rdf:instanceOf. Because you can just use your own attributes with your own namespace, it probably doesn't really matter anyway.

Note that a template with no rules in it, as in the first example, is really equivalent functionally to a template with a single rule with no attributes.

Następny artykuł pokazuje nam jak stosować szablony z drzewami.