Dokumentacja techniczna wydruków

Wstęp

Definicje wydruków znajdują się w katalogu c:\Retail\POS2\Printouts\. Każda definicja znajduje się w oddzielnym katalogu, którego nazwa jest jednocześnie nazwą definicji. Wewnątrz katalogu muszą zostać umieszczone co najmniej trzy pliki definiujące źródło danych, układ wydruku oraz jego wygląd. Każdy z tych plików musi być poprawnym plikiem xml o określonej nazwie. Dokładna struktura każdego z tych plików została opisana poniżej.

Źródło danych

Źródło danych dla wydruku musi zostać umieszczone w pliku o nazwie Data.xml. Głównym elementem w pliku jest data, wewnątrz którego musi się znaleźć dokładnie jeden element setf. Wewnątrz elementu setf musi się znaleźć jeden lub więcej elementów set.

Każdy element set reprezentuje jeden zbiór danych (wynik jednego zapytania SQL). Musi on zawierać dwa elementy podrzędne: name – który określa nazwę zbioru oraz query, które definiuje zapytanie SQL.

Przykładowy plik Data.xml

<?xml version="1.0" encoding="utf-8"?>
<data>
  <setf>
    <set>
      <name>SummaryAmount</name>
      <query>
        SELECT
        FORMAT(Value,'N2','pl-PL') as Amount, c.Symbol as Currency
        from Configuration.Currencies c, [Documents].[TradeDocuments] ts
        join Documents.Payments dp on dp.DocumentId = ts.Id
        where ts.Id = {0} and c.IsSystem = 1
      </query>
    </set>      
    <set>
      <name>DocumentRates</name>
      <query>
        SELECT cvr.Name as Name,
        FORMAT(dva.NetValue,'N2','pl-PL') as NetValue,
        FORMAT(dva.GrossValue,'N2','pl-PL') as GrossValue,
        FORMAT(dva.VatValue,'N2','pl-PL') as Vat
        FROM Documents.VATAggregates dva
        JOIN Configuration.VATRates cvr ON cvr.id = dva.VATRateId
        where DocumentId={0}
      </query>
    </set>
  </setf>
</data>>

Zapytanie może być standardowym zapytaniem SQL lub nazwą procedury składowanej, która zwraca żądany wynik. Aby skorzystać z procedury składowanej do elementu query należy dodać atrybut type z wartością StoredProcedure

Parametry źródła danych

Przy wykonywaniu zapytań z pliku Data.xml przekazywane są do nich parametry zależne od typu oraz kontekstu wydruku. W przykładzie powyżej wykorzystany został jeden parametr @DocumentId.

Układ wydruku

Zawartość oraz układ wydruku definiowany jest w pliku Layout.xml. Głównym elementem w pliku jest document. Musi zawierać on co najmniej element body, który zawiera główną część wydruku. Dodatkowo w elemencie document może zostać umieszony element title oraz wiele elementów header oraz footer. Zawartość elementów body, header oraz footer może zostać skomponowana z elementów opisanych w sekcji Układ. Elementy te mogą być zagnieżdżane.

Wygląd wydruku

Dostosowanie wyglądu wydruku możliwe jest poprzez plik Styles.xml. Głównym elementem pliku jest style, który zawiera elementy określające wygląd poszczególnych elementów wydruku zdefiniowanych w pliku Layout.xml.

Jednym z elementów podrzędnych elementu style jest element fonts, który określa wszystkie czcionki, które zostaną wykorzystane w wydruku. Może on zawierać, jeden lub więcej elementów font, który definiuje krój, wielkość, wygląd oraz styl fontu.

<font name="title" face="Arial" size="20" color="#9fc54c"/>

Atrybuty elementu font to:

• name – określa nazwę czcionki
• face – nazwa kroju czcionki
• size – rozmiar w punktach
• color – kolor
• style – style czcionki. Może zawierać jedną (lub więcej wartości oddzielonych znakiem spacji) z wartośći bold, italic, underline.

Wewnątrz elementu fonts powinien znaleźć się także jeden element font z pominiętym atrybutem name. Czcionka ta będzie stosowana jako domyślny czcionka dla wydruku.

<fonts>
        <font face="Trebuchet MS" size="10"/>
        <font name="title" face="Arial" size="20" color="#9fc54c"/>
        <font name="header" face="Tahoma" size="8" color="#999999"/>
        <font name="summary_value" face="Trebuchet MS" size="15" color="#9fc54c" style="bold"/>
</fonts>

Oprócz elementu fonts w pliku Styles.xml mogą znajdować się elementy w schemacie

<selektor>
        <reguła/>
        <reguła/>
        [...]
</selektor>

Gdzie selektor decyduje o tym, czy podległe mu reguły zostaną zastosowane dla danego elementu. Większość selektorów ma taką samą nazwę jak element, który stylują. Np. w celu ostylowania paragrafu (element p w pliku Layout.xml) należy zastosować selektor p

<p>
        <margin top="5"/>
</p>

Powyższy przykład wszystkim paragrafom wydruku ustawi margines górny na 5 punktów.
Selektor może wybrać do ostylowania tylko wybrane elementy danego typu. W tym celu do elementu w pliku Layout.xml oraz selektora w pliku Styles.xml należy dodać atrybut class. Selektor wybierze wtedy tylko te elementy, które mają identyczną wartość atrybutu class.

<p>
        <text font="normal"/>
</p>
<p class="title">
        <text font="title"/>
</p>

Powyższy przykład ustawi font wszystkich paragrafów na normal ale te, których atrybut class to title zostanie ustawiony font title.

Dokładny opis innych atrybutów selektorów oraz spis reguł stylujących znajduje się w sekcji Wygląd. Lista selektorów oraz reguł, które można zastosować dla danego elementu znajduje się w opisie poszczególnych elementów w sekcji Układ.
Reguły z pliku Styles.xml stosowane są od góry do dołu tzn. jeżeli dwa selektory dopasują ten sam element i zawierają one takie same reguły z innymi wartościami to zostanie zastosowana wartość występująca później.

Układ wydruku

Wszystkie dostępne elementy, które mogą zostać zastosowane podczas tworzenia układu wydruku zostały opisane w tej sekcji. Opis każdego elementu zawiera następujące sekcje:

• Zawartość – opisuje jakie elementy podrzędne można umieścić wewnątrz danego elementu.
• Parametry – opisuje wszystkie dostępne atrybuty jakie można dodać do elementu i co oznaczają.
• Elementy stylujące – zawiera listę selektorów, które dopasowują dany element w pliku Styles.xml
• Elementy podrzędne – opcjonalna sekcja opisująca elementy, które mogą wystąpić tylko wewnątrz danego elementu. Dla każdego elementu podrzędnego zachowany jest układ opisu taki sam jak dla głównego elementu.
• Przykład – zawiera fragment kodu z przykładowym wykorzystanie opisywanego elementu.

Elementy

Barcode

<barcode type="Code 93"><data set="DocumentHeader" var="EAN" /></barcode>

Body

<?xml version="1.0" encoding="utf-8"?>
<document>
        <title><data set="DocumentHeader" var="NumberString" /></title>
        <body>
                 [zawartość wydruku]
        </body>
</document>

Br

<p>Tekst<br/> w wielu<br/>liniach</p>

Data

<barcode type="Code 93"><data set="DocumentHeader" var="EAN" /></barcode>

Footer

<?xml version="1.0" encoding="utf-8"?>
<document>
        <footer page="last">
                 <p>Stopka ostatniej strony</p>
       </footer>

Header

<?xml version="1.0" encoding="utf-8"?>
<document>
       <header>
                 <p>Nagłówek</p>
        </header>
        <body>
[...]

Horizontal i Section

Horizontal

Section

Przykład dla Horizontal i Section

<horizontal>
        <section><p class="sign">Dokument wystawił</p></section>
        <section weight="0,1"></section>
        <section><p class="sign">Towar wydał</p></section>
        <section weight="0,1"></section>
        <section><p class="sign">Data odbioru</p></section>
        <section weight="0,1"></section>
        <section><p class="sign">Towar odebrał</p>
<p class="footer">Strona<pageNumber/> z <numOfPages/></p></section>

</horizontal>

Hr

<p>tekst1</p>
<hr />
<p>tekst2</p>

If

Test

True

False

Przykład dla If

<if>
        <test><data set="DocumentsPositions" var="Id" /> &lt; 3123</test>
        <true>
                 <horizontal>
                         <section weight="2">
                                  <p><data set="DocumentsPositions" var="Name" /></p>
                                  <p><data set="DocumentsPositions" var="Barcode" /></p>
                         </section>                         <section weight="3">
                                  <p><data set="DocumentsPositions" var="Name" /></p>
                                  <p><data set="DocumentsPositions" var="Barcode" /></p>
                         </section>                 </horizontal>        
</true>        
<false>
                 <p><data set="Header" var="CompanyName" /></p>
        </false>
</if>

Image

<image path="logowms.png" />
<image set="Header" var="Logo" />

PageNumber

<footer>
        <p class=”footer”>Strona<pageNumber/> z <numOfPages/></p>
</footer>

P

<p class="date">Data wystawienia:&#160;<data set="DocumentHeader" 
var="DocumentCreationDate" /></p>

RowNumber

<table set="DocumentPositions">
        <column weight="2" description=”N." class="number">
                 <rowNumber />
        </column>
        <column weight="12" description=”[Kod] Nazwa towaru">
                 [<tableData var="Code" />] <tableData var="Name" />
        </column></table>

StaticTable

Head

Column

Row

Cell

Przykład

<staticTable class="customer">
        <head>
                 <column weight="1"><p class="tableHead">Odbiorca</p></column>
                 <column weight="1"><p class="tableHead">Nabywca</p></column>
        </head>
        <row>
                 <cell>
                         <p class="customer"><data set="DocumentHeader" var="CustomerName" /><br/>
                         <data set="DocumentHeader" var="Street" /><br/>
                         <data set="DocumentHeader" var="ZipCode" />&#160;<data set="DocumentHeader" var="City" /><br/>
                         IVA: <data set="DocumentHeader" var="Tin" /><br/>
                         </p>
                 </cell>
                 <cell>
                        <p class="customer"><data set="DocumentHeader2" var="CustomerName" /><br/>
                         <data set="DocumentHeader2" var="Street" /><br/>
                         <data set="DocumentHeader2" var="ZipCode" />&#160;<data set="DocumentHeader2" var="City" /><br/>
                         IVA: <data set="DocumentHeader2" var="Tin" /><br/>
                         </p>
                 </cell>
        </row>
        <row>
                <cell collspan="2">
                         <p>...</p>
                 </cell>
        </row>
</staticTable>

Table

Column

Dynamic-columns

If

Element warunkowy pozwalający na pokazanie lub ukrycie wybranych kolumn.

Patrz generyczny element If

TableData

Przykład 1 – Kolumny statyczne i warunkowe

<table set="DocumentPositions">
        <column weight="2" description="N." class="number">
                 <rowNumber />
        </column>
        <column weight="12" description="[Kod] Nazwa towaru">
                 [<tableData var="Code" />] <tableData var="Name" />
        </column>
                 <if>
                         <test>
                                  <hasColumn var="Column15" /> = 1
                         </test>
                         <true>
                                  <column weight="2" description="Test" class="number">
                                          <tableData var="Column15" />
                                  </column>
                         </true>
                 </if>
        <column weight="4" description="Ilość" class="number">
                 <tableData var="RealizedQuantity" />
        </column>
        <column weight="4" description="Jm. (podstawowa)">
                 <tableData var="BasicUnitSymbol" />
        </column>
        <column weight="4" description="Ilość" class="number">
                 <tableData var="SecondaryQuantityRealized" />
        </column>
        <column weight="4" description="Jm. (pomocnicza)">
                 <tableData var="SecondaryUnitSymbol" />
        </column>
</table>

Przykład 2 – Kolumny dynamiczne

<table set="DocumentPositions">
        <column weight="2" description="N." class="number">
                <rowNumber />
        </column>
        <column weight="12" description="[Kod] Nazwa towaru">
                 [<tableData var="Code" />] <tableData var="Name" />
        </column>
        <dynamic-columns weight="4" description="Waluta {{1}}" names="Currency(.+)">
                 <tableData var="{{0}}" /> {{1}}
</dynamic-columns>
</table>

Title

Wygląd wydruku

Wszystkie elementy stylujące (selektory) oraz reguły stylujące zostały opisane w tej sekcji. Opis każdego selektora zawiera listę elementów, które styluje oraz listę reguł, jakie można w nim umieścić.
Opis każdej reguły zawiera listę atrybutów jakie można w niej zastosować.

Atrybuty zawężające

Każdy selektor może zostać zawężony poprzez atrybut class. Dodatkowo selektory elementów związane z tabelami mogą zostać zawężone poprzez atrybut index, który może zawierać liczbę całkowitą lub wyrażenie postaci An+B, gdzie A oraz B to liczby całkowite. Selektor taki dopasuje element, jeżeli zgadza się on z indeksem wiersza tabeli (wiersze tabeli numerowane są od 0 z góry na dół).

Przykłady

• index=”0″ – dopasuje pierwszy wiersz w tabeli
• index=”first” – dopasuje pierwszy wiersz w tabeli
• index=”last” – dopasuje ostatni wiersz w tabeli
• index=”5″ – dopasuje szósty wiersz w tabeli
• index=”2n” – dopasuje parzyste wiersze tabeli tzn. z indeksem równym 0,2,4… czyli wiersze pierwszy, trzeci, piąty…
• index=”3n+1″ – dopasuje wiersze z indeksem 1, 4, 7…
• index=”3n+2″ – dopasuje wiersze z indeksem 2, 5, 8…

Selektory

Barcode

Body

Cell

DataCell

Footer

HeadCell

Header

Hr

Image

P

Section

StaticTable

Table

Reguły

Background

Reguła określająca tło elementu.

Atrybuty

• color – kolor tła elementu. Może on być w formacie #RRGGBB lub 0xRRGGBB lub 0xAARRGGBB

Border

Reguła określająca obramowanie elementu.

Atrybuty

• left – szerokość lewego obramowania.
• right – szerokość prawego obramowania.
• top – szerokość górnego obramowania.
• bottom – szerokość dolnego obramowania.
• color – kolor obramowania elementu. Może on być w formacie #RRGGBB lub 0xRRGGBB lub 0xAARRGGBB
• borderStyle – styl obramowania. Może przyjmować jedną z wartości:
  • dashdot
  • dashdotdot
  • dashlargegap
  • dashsmallgap
  • dot
  • none
  • single

Szerokość obramowania może być podana w różnych jednostkach m.in.: cm, in, mm, pt. Domyślną jednostką są punkty.

Stylowanie wybranego elementu obramowania

Istnieje możliwość ostylowania tylko wybranej części obramowania np. tylko lewej krawędzi elementu. W tym celu należy zastosować jeden z wybranych selektorów:

• borderLeft
• borderRight
• borderTop
• borderBottom

Każdy z tych selektorów może zawierać następujące reguły:

• width – szerokość obramowania
• color – kolor obramowania
• borderStyle – styl obramowania

Fit

Reguła określająca rozmiar elementu.

Atrybuty

• width – szerokość elementu
• height – wysokość elementu

Szerokość i wysokość może być podana w różnych jednostkach m.in.: cm, in, mm, pt. Stylowany element zachowa swoje proporcje przyjmując mniejszy z podanych wymiarów.

Margin

Reguła określająca marginesy elementu.

Atrybuty

• left – lewy margines
• right – prawy margines
• top – górny margines
• bottom – dolny margines

Szerokość marginesu może być podana w różnych jednostkach m.in.: cm, in, mm, pt.

Page

Reguły specjalne dla strony.

Atrybuty

• orientation – orientacja strony
• size – rozmiar strony
• width – szerokość strony
• footer-distance – odległość stopki od dołu strony
• header-distance – odległość nagłówka od góry strony

Text

Reguła określająca styl tekstu.

Atrybuty

• align – wyrównanie tekstu. Przyjmuje jedną z wartości:
  • right – wyrównanie do prawej
  • left – wyrównanie do lewej
  • justify – wyjustowanie tekstu
  • center – wyśrodkowanie tekstu
• indent – wcięcie pierwszej linii tekstu.
• leftIndent – wcięcie tekstu z lewej.
• rightIndent – wcięcie tekstu z prawej.
• font – nazwa fontu zdefiniowana wcześniej w sekcji fonts.
• color – kolor tekstu. Może on być w formacie #RRGGBB lub 0xRRGGBB lub 0xAARRGGBB

Width

Reguła określająca szerokość elementu.

Atrybuty

• percentage – procentowa szerokość elementu bazująca na szerokości elementu-rodzica.