Technologia obiektu
PmaReport jest orientowana przede wszystkim na pliki źródłowe w formacie HTML i XML i dlatego jest konieczne pewna znajomość składni
HTML włącznie z powiązanymi stylami
CSS. Można jednak stosować zwykłe pliki TXT.
W celu łatwiejszego zrozumienia następujących opisów zalecamy przejrzenie
Przykłady raportów.
Zasady ogólne
Podstawową zasadą obiektu obiektu
PmaReport jest, że wczyta plik źródłowy, wyszuka w nim polecenia i wykona je. Polecenie w pliku źródłowym ma zawsze formę
<!--Pm:xxxxxxxx--> gdzie
xxxxxxxx jest formą konkretnego polecenia (
<!-- --> przedstawia notatkę HTML i dlatego można źródłowy plik HTML przeglądać na przykład w przeglądarce internetowej nawet jeżeli występują w nim polecenia).
Przez wykonanie polecenia zawsze zostanie zmieniona zawartość pliku źródłowego i polecenie jest z pliku usunięte.
Wieęszkość poleceń stosuje parametry. Takie parametry wpływają na dane polecenie. Wartością parametru może być:
- Stała (tekst - na przykład "hello", liczba - na przykład 3.14)
-
Wartość klucza podstawionego do obiektu
PmaReport przy pomocy metody
SetKeyValue (i tak tworzyć zawartość z bieżącymi danymi z aplikacji). Na przykład jeżeli do obiektu
PmaReport jest włożony klucz
SetKeyValue("txt1","Temperatura kotła przekroczyła 80 stopni Celsjusza"), wtedy w poleceniu można się do tekstu klucza odnosić przy pomocy identyfikatora
key.txt1.
-
Wartość poleecnia pętli - patrz dalej w poleceniach
Pm:Cycle....
Pm:SetText - Polecenie bezpośredniego włożenia tekstu
Całe polecenie zostanie zastąpione przez tekst obliczony przez to polecenia
Składnia:
<!--Pm:SetText(sValue)-->
Parametry:
- sValue: Wartość (tekst), które zastąpi (przepisze) polecenie
Przykład1:
Jeżeli było ustawione:
oReport.SetKeyValue("value1", "Temperatura kotła przekroczyła 80 stopni Celsjusza")to w zawartości pliku źródłowego sekcja:
<!--Pm:SetText(key.value1)-->
zastąpiona przez tekst:
Temperatura kotła przekroczyła 80 stopni Celsjusza
Przykład2:
Przy pomocy
Makro wyrażenie $.text polecenie zostanie zastąpione przez zlokalizowany tekst o identyfikatorze
txt1.
<!--Pm:SetText($.text("app","txt1")-->Pm:TagSetValue - Polecenie zmiany wartości tagu
Polecenie włoży lub zmieni wartość bezpośrednio następującego tagu HTML lub XML (to polecenie nie jest więc przeznaczone dla plików tekstowych)
Składnia:
<!--Pm:TagSetValue(sValue)-->
Parametry:
- sValue: Wartość, która zostanie włożona do tagu HTML/XML
Przykład:
Jeżeli było ustawione:
oReport.SetKeyValue("value1", "Temperatura kotła przekroczyła 80 stopni Celsjusza")to w zawartości pliku źródłowego sekcja:
<!--Pm:TagSetValue(key.value1)-->
<h1></h1>
zastąpiona przez tekst:
<h1>Temperatura kotła przekroczyła 80 stopni Celsjusza</h1>
Pm:TagSetAttr - Polecenie zmiany atrybutu tagu
Polecenie włoży lub zmieni wartość atrybutu bezpośrednio następującego tagu HTML lub XML (to polecenie nie jest więc przeznaczone dla plików tekstowych)
Składnia:
<!--Pm:TagSetAttr(sName,sValue)-->
Parametry:
- sName: nazwa atrybutu HTML/XML
- sValue: Wartość, która zostanie włożona do atrybutu HTML/XML
Przykład1:
Jeżeli było ustawione:
to w zawartości pliku źródłowego sekcja:
<!--Pm:TagSetAttr("class",key.value2)-->
<h1>Title</h1>
zastąpiona przez tekst:
<h1 class="xyz">Title</h1>
Przykład2:
Przy pomocy wyrażenia
$.path("appres") zostanie do atrybutu
src tagu
<img> ustawiona ścieżka do ilustracji
picture.jpg.
<!--Pm:TagSetAttr("src", $.path("appres","picture.jpg"))-->
<img src="" title="picture.jpg"/>
Pm:TagSetStyle - Polecenie zmiany stylu tagu
Polecenie włoży lub zmieni wartość stylu bezpośrednio następującego tagu HTML lub XML (to polecenie nie jest więc przeznaczone dla plików tekstowych).
Składnia:
<!--Pm:TagSetStyle(sName,sValue)-->
Parametry:
- sName: nazwa HTML CSS stylu
- sValue: Wartość, która zostanie włożona do HTML CSS stylu
Przykład:
Jeżeli było ustawione:
to w zawartości pliku źródłowego sekcja:
<!--Pm:TagSetStyle("background-color",key.value2)-->
<h1>Title</h1>
zastąpiona przez tekst:
<h1 style="background-color:#ff0000;">Title</h1>
Pm:If.. (Pm:If..Pm:IfElse)- Polecenie obliczenia prostego warunku
Wyrażenia w warunku mogą zawierać stałe, wartości słowa kluczowego, zmienne pętli. Można zastosować jednowierszową składnię (1. składnia) dla krótkich, prostych testów. Forma blokowa (2. składnia) jednak oferuje więcej elastyczności i możliwości strukturowania niż forma jednowierszowa. Warunek jest opracowywany przy wykonywaniu bloku. Jeżeli warunek jest
true, wtedy zostaną wykonane następujące polecenia. Jeżeli warunek jest
false (2. składnia), wtedy zostaną wykonane polecenia w bloku
IfElse.
Składnia:
<!--Pm:IfBegin(warunek)-->
...
<!--Pm:IfEnd-->
lub:
<!--Pm:IfBegin(warunek)-->
...
<!--Pm:IfElse-->
...
<!--Pm:IfEnd-->
Forma warunku:
Wartość1 == Wartość2 : równe
Wartość1 != Wartość2 : jest różne
Wartość1 < Wartość2 : mniejsze niż
Wartość1 > Wartość2 : większe niż
Wartość1 <= Wartość2 : mniejsze lub równe
Wartość1 >= Wartość2 : większe lub równe
Przykład1:
Jeżeli było ustawione:
to w zawartości pliku źródłowego sekcja:
<!--Pm:IfBegin(key.req==3)-->
<p>test</p>
<!--Pm:IfEnd-->
zastąpiona przez tekst:
<p>test</p>
w innym przypadku zostanie usunięty cały odcinek tekstu pomiędzy tymi dwoma poleceniami.
Przykład2:
Jeżeli było ustawione:
to w zawartości pliku źródłowego sekcja:
<!--Pm:IfBegin(key.req!=3)-->
<p>test1</p>
<!--Pm:IfElse-->
<p>test2</p>
<!--Pm:IfEnd-->
zastąpiona przez tekst:
<p>test2</p>
w innym przypadku zostanie usunięty cały odcinek tekstu pomiędzy tymi dwoma poleceniami.
Pm:VarSet - Polecenie wytworzenia i ustawienia wartości zmiennej
To polecenie wytworzy i ustawi wartość zmiennej. Taką zmienną można zastosować w następujących poleceniach przy wytwarzaniu szablonu.
Składnia:
<!--Pm:VarSet(sKey,sKeyName,Value)-->
Parametry:
- sKey: Klucz
- sKeyName: Nazwa zmiennej
- Value: Wartość zmiennej
Przykład1:
Wytworzy zmienną bDone i przypisze jej wartość 1.
<!--Pm:VarSet("key","bDone",1)-->
Przykład2:
Test, czy została wprowadzona wartość wejściowa bDone. Jeżeli nie, wtedy wytworzy ją i przypisze wartość 0.
<!--Pm:IfBegin(!key.bDone)-->
<!--Pm:VarSet("key","bDone",0)-->
<!--Pm:IfEnd-->
PmLib.GetArraySize - Stwierdzi rozmiary tablicy
Zwraca 1. lub 2. rozmiar zmiennej typu
Array.
Składnia:
PmLib.GetArraySize(key.arr,n)
Parametry:
- arr: nazwa zmiennej tablica (array).
- n: 1 do stwierdzania pierwszego lub 0 drugiero rozmiaru
do stwierdzania pierwszego rozmiaru jest możliwy także skrócony zapis:
PmLib.GetArraySize(key.arr)Pm:Cycle... - Polecenie jednofazowego mnożenia tekstu (pętla prosta)
To polecenie jest przeznaczona dla prostego mnożenia tekstu w następującym znaczeniu: W pliku źródłowym pliku występuje np. tag:
i jest konieczne w tym tagu kolejno wypełnić wszystkie wartości z dostarczonej tablicy wartości. To znaczy, że wymagamy, żeby ten tag pomnożył się i wynikiem było np.:
<p>1234</p>
<p>3.14</p>
<p>56.8</p>
<p>-345</p>
Właśnie taki wymóg rozwiązuje to polecenie. Najczęściej jest stosowane na przykład do mnożenia wierszy w tabeli (tzn. do mnożenia tagu
<tr> v tagu
<table>) - patrz
Przykład3. Jednak koncept jest ogólny i może zostać zastosowany na przykład do mnożenia wartości w pliku tekstowym, itd.
Składnia:
<!--Pm:CycleBegin(sId,PmLib.GetArraySize(key.arr,1))-->
... (mnożony teksty i dalsze polecenia, na przykład Pm:TagSetValue)
<!--Pm:CycleEnd(sId)-->
Parametry:
- sId: identyfikator pętli. CycleBegin i jemu odpowiadające CycleEnd muszą mieć ten sam identyfikator. Identyfikator jest sotsowany także do stwierdzania zmiennej pętli (w formie na przykład id.sId.Index).
- PmLib.GetArraySize(key.arr,1): ilość rzomnożenia (np. ilość wierszy)
Zmienne pętli (te zmienne można zastosować w poleceniach wewnątrz pętli):
- id.sId.Index: indeks pętli (indeksowane od 0), np. indeks opracowywanego wiersza.
- PmLib.GetArraySize(key.arr,1): ilość pozycji, np. całkowita ilość wierszy.
Przykład3:
Przy pomocy metody
SetKeyValue jest do klucza
arr włożona tablica 2-wymiarowa. Ilość kolumn tablicy zawsze wynosi 3, ilość wierszy jest zmienna i jest zapisana do klucza
rows. Polecenie w pliku źródłowym może wtedy wyglądać następująco:
<table>
<tr>
<th>Col1</th>
<th>Col2</th>
<th>Col3</th>
</tr>
<!--Pm:CycleBegin("cyc",PmLib.GetArraySize(key.arr,1))-->
<tr>
<!--Pm:TagSetValue(key.arr[0][id.cyc.Index+1])-->
<td></td>
<!--Pm:TagSetValue(key.arr[1][id.cyc.Index+1])-->
<td></td>
<!--Pm:TagSetValue(key.arr[2][id.cyc.Index+1])-->
<td></td>
</tr>
<!--Pm:CycleEnd("cyc")-->
</table>
Pm:CyclePage... / Pm:CycleLine... - Polecenie dwufazowego mnożenia tekstu (pętla podwójna)
To polecenie uogólnia prostą pętlę o możliwość pomnożenia na przykład nie tylko wiersze w tabeli lecz równocześnie do pomnożenia tabel. To rozwiązuje przypadek, kiedy ilość wierszy w tabeli jest bardzo duża i zachodzi potrzeba rozdzielenia tej tabeli n akilka części żeby podczas wydruku każda część została wyrdukowana ze swoim nagłówkiem, itd. Przy tym jest wymagane, że wejściem może być tylko duża tablica wartości (co wartość to wiersz tablicy) i żeby polecenie samo rozdzieliło wartości do tabel i wierszy.
Całe polecenie jest złożone z polecenia zewnętrznego
Pm:CyclePage.. (zapewnia mnożenie tabel, co tabela to strona) i polecenie wewnętrzne
Pm:CycleLine.. (zapewnia mnożenie wierszy w tabeli).
Pojęcia "tabela", "wiersz", "strona", "Line", "Page" są tylko pojęciami pomocniczymi. Koncepcja polecenia jest ogólna i nie musi rozchodzić się tylko o rozdzielanie wierszy na kilka tabel i stronic. Polecenie również nie zapewnia właściwego fizycznego stronicowania w druku HTML.
Składnia:
<!--Pm:CyclePageBegin(sId,PmLib.GetArraySize(key.arr,1),nCountFirstPage,nCountNextPages)-->
... (mnożone teksty i polecenia, na przykład nagłówek każdej tabeli)
<!--Pm:CycleLineBegin(sId)-->
... (mnożone teksty i polecenia, na przykład wiersze tabeli)
<!--Pm:CycleLineEnd(sId)-->
... (mnożone teksty i polecenia, na przykład stopka każdej tabeli)
<!--Pm:CyclePageEnd(sId)-->
Parametry:
- sId: identyfikator pętli. CyclePageBegin i jemu odpowiadające CycleLineBeginEnd, CycleLineEnd oraz CyclePageEnd muszą mieć ten sam identyfikator. Identyfikator jest stosowany także do stwierdzania zmiennej pętli (w formie na przykład id.sId.Index).
- PmLib.GetArraySize(key.arr,1): Całkowita ilość pomnożenia, na przykład całkowita ilość wierszy we wszystkich tabelach.
- nCountFirstPage: ilość w pierwszej pętli polecenia Pm.CycleLine... Umożliwia na przykład określić, że w pierszej tabeli będzie inna ilość wierszy niż w następujących tabelach.
- nCountNextPage: ilość w następujących pętlach polecenia Pm.CycleLine.. (ilość wierszy w następujących tabelach).
Zmienne pętli (te zmienne można zastosować w poleceniach wewnątrz pętli):
- id.sId.Index: całkowity indeks pętli (indeksowane od 0), na przykład indeks opracowywanego wiersza ponad wszystkie tabele.
- PmLib.GetArraySize(key.arr,1): Całkowita ilość pozycji, na przykład całkowita ilość wierszy ponad wszystkie tabele.
- id.sId.PageIndex: indeks opracowywanej pętli wewnętrznej (indeksowane od 0), na przykład numer strony (tabeli).
- id.sId.PageCount: Całkowita ilość opracowanai pętli wewnętrznych, na przykład całkowita ilość stron (tabel).
- id.sId.LineIndex: indeks pozycji opracowywanej przez pętlę wewnętrzną (indeksowane od 0), na przykład indeks wiersza w danej tabeli.
- id.sId.LineCount: ilość pozycji opracowywanych przez pętlę wewnętrzną, na przykład ilość wierszy w danej tabeli.
Przykład:
Przy pomocy metody
SetKeyValue jest do klucza
arr zapisana tablica 2-wymiarowa. Ilość kolumn tablicy jest zawsze 3, ilość wierszy jest zmienna i jest zapisana do klucza
rows. Ponieważ
rows może być duże (np. 300), wymagamy, żeby wynik był zapisany w kilku tabelach, w pierwszej tabeli żeby było maks. 35 wierszy a w następujących 40 wierszy. Zostanie wytworzona taka ilość tabel, żeby znalazły się tam wszystkie wiersze tablicy. Każda z tabel będzi emieć nagłówek s nazwami kolumn (
Col1, Col2, Col3). Polecenie w pliku źródłowym może wtedy wyglądać następująco:
<!--Pm:CyclePageBegin("cyc",PmLib.GetArraySize(key.arr,1),35,40)-->
<table>
<tr>
<th>Col1</th>
<th>Col2</th>
<th>Col3</th>
</tr>
<!--CycleLineBegin("cyc")-->
<tr>
<!--Pm:TagSetValue(key.arr[0][id.cyc.Index+1])-->
<td></td>
<!--Pm:TagSetValue(key.arr[1][id.cyc.Index+1])-->
<td></td>
<!--Pm:TagSetValue(key.arr[2][id.cyc.Index+1])-->
<td></td>
</tr>
<!--Pm:CycleLineEnd("cyc")-->
</table>
<br/>
<!--Pm:CyclePageEnd("cyc")-->