5.5.4. Szablony parametrów definiowalnych

Szablony są mechanizmem pozwalającym na tworzenie parametrów definiowalnych na podstawie pozostałych obecnych w konfiguracji parametrów. Zarówno ilość parametrów jak i ich atrybuty mogą być zależne od danych obecnych w konfiguracji.

Szablony mogą być obecne w elemencie ipk:drawdefinable i są przetwarzane równolegle z kopiowaniem pozostałych parametrów definiowalnych, a więc po wszelkich innych przekształceniach na konfiguracji. Istotna jest kolejność wstawienia szablonu do parametrów definiowalnych - szablon ma dostęp do parametrów zdefiniowanych przed nim (także za pomocą innych szablonów), natomiast parametry zdefiniowane po nim mogą korzystać z parametrów powstałych w wyniku działania szablonu.

Szablon definiujemy przez element template o dwóch atrybutach:

• xpath - (atrybut obowiązkowy) określa zbiór elementów "bazowych" dla szablonu. Są one traktowane jako początek kontekstu przy dalszych wyrażeniach XPath, a poza tym, co ważniejsze, określają ilość utworzonych parametrów. Dla każdego elementu ze zbioru określanego przez atrybut zostanie iteracyjnie przetworzona zawartość elementu template.

• name - (opcjonalny) służy jako komentarz do szablonu, jego zawartość zostanie skopiowana do atrybutu template z przestrzeni nazw http://www.praterm.com.pl/SZARP/extra. Ma to na celu ułatwienie debugowania konfiguracji - wiadomo, że dany element w pliku wynikowym powstał jako efekt działania szablonu i wiadomo jaki to był szablon.

W elemencie template może być umieszczonych dowolna ilość elementów variable, które określają zmienne pomocnicze, używane do tworzenia parametrów wynikowych. Zmienne są globalne w całym dokumencie, mogą być wielokrotnie przedefiniowywane, za niezainicjowane zmienne podstawiane są puste napisy. Odwołania do zmiennych mogą występować w określonych, wymienionych w dokumentacji miejscach i mają postać \n, gdzie n jest numerycznym identyfikatorem zmiennej (od 0 do 9). Element variable może mieć następujące atrybuty:

• id - obowiązkowy, numeryczny identyfikator zmiennej

• xpath - opcjonalny atrybut zawierający wyrażenie XPath typu string, które zostanie podstawione jako wartość zmiennej. Jeżeli atrybutu nie będzie, to zmienna będzie pustym napisem. Obliczanie wyrażenia XPath zaczyna się od węzła "bazowego", czyli zdefiniowanego przez atrybut xpath szablonu. Wartość wyrażenia musi być typu string, jeżeli potrzeba, możemy posłużyć się dodatkowo funkcją XPath string(). W zawartości atrybutu xpath są także dokonywane podstawienia za zmienne (czyli, w szczególności, zmienna może rekurencyjnie zależeć od siebie).

Zawartość elementu variable jeżeli nie jest pusta, traktowana jest jako wyrażenie regularne dokonujące podstawień na wartości zmiennej otrzymanej na podstawie atrybutu xpath. Sposób interpretacji wyrażenia i dokonywania podstawień jest identyczny, jak dla pozostałych elementów konfiguracji zagregowanej.

Wszystkie pozostałe elementy wchodzące w skład elementu template i nie pochodzące z przestrzeni nazw aggr są rekurencyjnie kopiowane do dokumentu wyjściowego. Na zawartości atrybutów i elementów dokonywane jest podstawienie zdefiniowanych wcześniej zmiennych za napisy postaci \n gdzie n odpowiada identyfikatorowi zmiennej, której wartość chcemy podstawić.

Pomocą w zrozumieniu działania mechanizmu może być następujący przykład. Załóżmy, że w konfiguracji zagregowanej (po zastosowaniu wcześniejszych przekształceń) mamy zestaw parametrów opisujących energię dostarczoną przez węzły cieplne, w MWh. Parametry te mają postać:

<ipk:param name="Węzły:[nazwa węzła]:energia sumaryczna" short_name="Esum"
    draw_name="Energia sumaryczna" unit="MWh" base_ind="auto" prec="2">
  <ipk:draw title="Węzeł [nazwa węzła]" min="0" max="2"/>
</ipk:param>

Chcemy dodać do konfiguracji parametry podające tą samą wielkość (energia z węzła) ale w GJ, a także parametr sumujący wszystkie te wartości. Możemy tego dokonać za pomocą następujących dwóch szablonów:

<ipk:drawdefinable>
    <template xpath="//ipk:param[starts-with(@name, '{chrw}') and
    ( contains(@name, ':Licznik energii CO') or
      ( contains(@name,':Licznik energii  CO'))
    ) and not (
      contains(@name, 'Licznik energii CO ') or
      contains(@name, 'CO+CWU')
    )]"
      name="Energia z węzłów - przeliczanie GJ na MWh">
      <variable id="0" xpath="string(./@name)"/>
      <variable id="1" xpath="string(./@name)">s#^.*$#\0 GJ#</variable>
      <variable id="2" xpath="string(./ipk:draw/@title)"/>
      <variable id="9" xpath="'\9 (\1) 0 N +'"/>
      <ipk:param name="\1" short_name="Esum" draw_name="Energia sumaryczna MWh"
        unit="GJ" prec="2">
        <ipk:define type="DRAWDEFINABLE" formula="(\0) 0 N 3600 / "/>
        <ipk:draw title="\0" min="0" max="7200"/>
      </ipk:param>
    </template>
    <template xpath="//ipk:drawdefinable" name="Energia z węzłów - suma MWh">
      <ipk:param name="Węzły:Definiowalne:suma energii z węzłów"
        short_name="ESum" draw_name="Sumaryczna energia z węzłów"
        unit="GJ" prec="2">
        <ipk:define type="DRAWDEFINABLE" formula="0 \9"/>
        <ipk:draw title="Węzły - wielkości sumaryczne" min="0" max="20000"/>
      </ipk:param>
    </template>
  </ipk:drawdefinable>

Pierwszy szablon wybiera interesujące nas parametry (przykład jest rzeczywisty, więc zawiera kilka obejść dla błędów literowych, takich jak podwójne spacje w nazwach parametrów). Zmienna \0 zawiera nazwę parametru, zmienna \1 nazwę parametru po przekształceniu wyrażeniem regularnym (efekt dodania napisu "GJ" na końcu można oczywiście osiągnąć prościej, nie korzystając z wyrażeń regularnych). Interesująca jest natomiast zmienna \9, która tworzy rekurencyjnie formułę zawierającą sumę wszystkich parametrów. Jest ona potem wykorzystywana do utworzenia parametru sumującego wszystkie poprzednie.