Sąskaitų faktūrų žymėjimo kalba (InML)

InML (Invoice Markup Language) yra XML pagrindu sukurta šablonų kalba, skirta apibrėžti sąskaitų faktūrų PDF išdėstymą „Haiku.lt“ sistemoje. Ji suteikia visišką kontrolę sąskaitos struktūrai, stiliui ir turiniui.

Galite pasirinkti vieną iš penkių integruotų stilių kaip pradinį tašką ir pritaikyti jį pagal savo poreikius arba sukurti šabloną nuo nulio.

Pagrindinė struktūra

Kiekvienas InML šablonas prasideda šakniniu <inml> elementu:

<inml version="1.0" page-size="A4" margin="20mm"
      font-regular="Roboto-Light" font-bold="Roboto-Medium">
  <page>
    <!-- elementai piešiami kiekviename puslapyje -->
  </page>
  <layout>
    <!-- turinio sritys -->
  </layout>
</inml>

Šakninio elemento atributai

Matavimo vienetai

Visi matmenys nurodomi milimetrais (mm) arba taškais. Reikšmės rašomos kaip 20mm, 5mm, 210mm. Šriftų dydžiai nurodomi taškais be vienetų (pvz. font-size="12").

Puslapio elementai

<page> sekcija apibrėžia elementus, kurie piešiami kiekviename puslapyje, po pagrindiniu turiniu. Naudokite fono paveikslėliams, dekoratyviniams stačiakampiams ar linijoms.

<page>
  <image src="{{background}}" x="0mm" y="0mm" width="210mm" height="297mm" />
  <rect x="0mm" y="0mm" width="210mm" height="30mm" fill="#f1f5f9" />
  <line x1="20mm" y1="50mm" x2="190mm" y2="50mm" color="#cccccc" width="0.5mm" />
</page>

Galimi puslapio elementai

• <image> — fono paveikslėlis. Atributai: src, x, y, width, height.
• <rect> — stačiakampis. Atributai: x, y, width, height, fill, stroke, stroke-width.
• <line> — linija. Atributai: x1, y1, x2, y2, color, width.

Išdėstymas ir sritys

<layout> sekcijoje yra vienas ar daugiau <region> elementų. Kiekviena sritis yra nepriklausoma turinio zona su savo pozicionavimo režimu.

<layout>
  <region id="header" flow="fixed" margin-top="5mm"
          margin-left="20mm" content-width="170mm">
    <!-- turinys -->
  </region>
  <region id="body" flow="sequential" margin-top="20mm">
    <!-- turinys -->
  </region>
</layout>

Srities atributai

Pozicionavimo režimai

• sequential — sritys išdėstomos viena po kitos iš viršaus į apačią. Tai dažniausiai naudojamas režimas pagrindiniam turiniui.
• absolute — pozicionuojama konkrečioje vietoje, apskaičiuojant nuo dabartinės vertikalios pozicijos. Sekančios „sequential“ sritys tęsiasi po jos.
• fixed — pozicionuojama fiksuotoje puslapio vietoje, nepriklausomai nuo kitų sričių. Naudinga antraštėms ar uždengimams.

Išdėstymo stulpeliai

Norėdami sudėti sritis greta viena kitos, apgaubkite jas <columns> elementu išdėstymo lygmenyje:

<layout>
  <columns>
    <column margin-left="20mm" content-width="80mm">
      <region id="left" flow="sequential">
        <!-- kairysis turinys -->
      </region>
    </column>
    <column content-width="80mm">
      <region id="right" flow="sequential">
        <!-- dešinysis turinys -->
      </region>
    </column>
  </columns>
</layout>

Kiekvienas <column> gali turėti margin-left ir content-width atributus ir savyje talpina vieną ar daugiau <region> elementų.

Turinio elementai

Turinio elementai dedami sričių viduje. Visi turinio elementai turi šiuos bendrus nebūtinus atributus:

<logo>

Rodo įmonės logotipą, išlaikant proporcijas.

<logo src="{{logo}}" width="50mm" ratio="{{logoRatio}}" />

<title>

Antraštės tekstas, dažniausiai naudojamas sąskaitos pavadinimui.

<title font="bold" font-size="14" align="center">{{invoiceTitle}}</title>

<text>

Paprastas tekstas.

<text font="regular" font-size="12">{{seller}}</text>

<columns> ir <column>

Išdėsto turinį greta srities viduje.

<columns>
  <column width="50%" align="left">
    <text font="bold" font-size="12">{{t.invoice.seller}}</text>
    <text font="regular" font-size="12" margin-top="5mm">{{seller}}</text>
  </column>
  <column width="50%" align="right">
    <text font="bold" font-size="12">{{t.invoice.buyer}}</text>
    <text font="regular" font-size="12" margin-top="5mm">{{buyer}}</text>
  </column>
</columns>

Kiekvienas <column> turi width atributą procentais (pvz. 50%) ir neprivalomą align atributą.

<stack> ir <group>

Vertikaliai sudėtos turinio grupės su nurodomomis tarpais tarp jų.

<stack spacing="10mm">
  <group>
    <text font="bold" font-size="12">Pirma sekcija</text>
    <text font="regular" font-size="12">Turinys čia</text>
  </group>
  <group>
    <text font="bold" font-size="12">Antra sekcija</text>
    <text font="regular" font-size="12">Daugiau turinio</text>
  </group>
</stack>

spacing atributas nustato vertikalų tarpą tarp grupių.

<box>

Konteineris su rėmeliu ir užpildu.

<box stroke="#cccccc" padding="5mm">
  <text font="regular" font-size="12">Turinys rėmelyje</text>
</box>

<rect>

Stačiakampis turinio sraute.

<rect width="170mm" height="1mm" fill="#238c83" />

<image>

Paveikslėlis turinio sraute.

<image src="{{logo}}" width="50mm" height="20mm" />

<spacer>

Prideda vertikalų tarpą tarp elementų.

<spacer height="10mm" />

<invoice-table>

Sąskaitos eilučių lentelė. Tai pagrindinis elementas, skirtas sąskaitos prekėms ir paslaugoms su stulpeliais ir suvestinės sekcija.

<invoice-table row-style="minimal" cell-padding="0mm"
       separator-after-header="true" separator-after-items="true"
       separator-color="#aaaaaa" separator-width="0.5mm">
  <col name="id"     label="{{t.invoice.lineItemNo}}"     width="10mm" align="left" />
  <col name="name"   label="{{t.invoice.lineItemName}}"   width="80mm" align="left" />
  <col name="unit"   label="{{t.invoice.lineItemUnit}}"   width="20mm" align="right" />
  <col name="amount" label="{{t.invoice.lineItemAmount}}" width="20mm" align="right" />
  <col name="price"  label="{{priceColumnLabel}}"         width="20mm" align="right" />
  <col name="total"  label="{{t.invoice.lineItemSum}}"    width="20mm" align="right" />

  <summary>
    <row label="{{t.invoice.total}}" value="{{total}}" />
  </summary>
</invoice-table>

Lentelės atributai

Stulpelių apibrėžimai

Kiekvienas <col> apibrėžia lentelės stulpelį:

PVM mokėtojams paprastai pridedami papildomi vat ir vat_sum stulpeliai. Naudokite {{#if vatpayer}} sąlyginiam jų rodymui.

Suvestinės eilutės

<summary> sekcija apibrėžia sumas, rodomas po lentele:

<summary>
  {{#if vatpayer}}
    <row label="{{t.invoice.total_without_vat}}" value="{{totalWithoutVat}}" />
    <row label="{{t.invoice.vat}}" value="{{vatTotal}}" />
  {{/if}}
  <row label="{{t.invoice.total}}" value="{{total}}" />
  {{#if alreadyPaid}}
    <row label="{{t.invoice.alreadyPaid}}" value="{{alreadyPaidFormatted}}" />
    <row label="{{t.invoice.sumToPay}}" value="{{sumToPay}}" />
  {{/if}}
</summary>

Šablono kintamieji

InML naudoja Handlebars sintaksę dinaminiam turiniui. Kintamieji įterpiami su {{kintamojoVardas}}, o sąlyginiai blokai su {{#if kintamojoVardas}}...{{/if}}.

Galimi kintamieji

Sąskaitos duomenys

Kainų laukai

Požymiai

Spalvos

Paveikslėliai

Vertimo eilutės

Visos etiketės pasiekiamos per t objektą. Dažniausiai naudojamos:

Integruoti stiliai

„Haiku.lt“ turi penkis integruotus stilius, kuriuos galite naudoti kaip pradinį tašką:

• minimalist — švarus dizainas su centruota antrašte ir minimaliais skirtukais
• modern-accent — spalvota antraštės juosta su akcentinėmis spalvomis
• left-aligned — kairėn lygiuotas išdėstymas su paprasta struktūra
• bordered — lentelės eilutės ir sekcijos su rėmeliais
• split-column — dviejų stulpelių išdėstymas pardavėjo ir pirkėjo informacijai

Pasirinkite integruotą stilių sąskaitos nustatymuose, tada perjunkite į pasirinktinį InML, kad galėtumėte jį modifikuoti.

Pilnas pavyzdys

Supaprastintas šablonas, rodantis pagrindinius InML konceptus:

<inml version="1.0" page-size="A4" margin="20mm"
      font-regular="Roboto-Light" font-bold="Roboto-Medium">
  <page>
    {{#if background}}
      <image src="{{background}}" x="0mm" y="0mm" width="210mm" height="297mm" />
    {{/if}}
  </page>
  <layout>
    {{#if logo}}
      <region id="logo" flow="absolute">
        <logo src="{{logo}}" width="50mm" ratio="{{logoRatio}}" />
        <spacer height="10mm" />
      </region>
    {{/if}}

    <region id="title-block" flow="absolute" min-height="40mm">
      <title font="bold" font-size="14" align="center">{{invoiceTitle}}</title>
      <text font="bold" font-size="12" align="center" margin-top="8mm">
        {{t.metadata.series}} {{seriesName}} {{t.invoice.no}} {{seriesId}}
      </text>
      <text font="regular" font-size="12" align="center" margin-top="16mm">
        {{formattedDate}}
      </text>
    </region>

    <region id="parties" flow="sequential" min-height="30mm">
      <columns>
        <column width="50%" align="left">
          <text font="bold" font-size="12">{{t.invoice.seller}}</text>
          <text font="regular" font-size="12" margin-top="5mm">{{seller}}</text>
        </column>
        <column width="50%" align="right">
          <text font="bold" font-size="12">{{t.invoice.buyer}}</text>
          <text font="regular" font-size="12" margin-top="5mm">{{buyer}}</text>
        </column>
      </columns>
    </region>

    <region id="table" flow="sequential" margin-top="20mm">
      <invoice-table row-style="minimal" cell-padding="0mm"
             separator-after-header="true" separator-after-items="true"
             separator-color="#aaaaaa" separator-width="0.5mm">
        <col name="id"     label="{{t.invoice.lineItemNo}}"     width="10mm" align="left" />
        <col name="name"   label="{{t.invoice.lineItemName}}"   width="80mm" align="left" />
        <col name="unit"   label="{{t.invoice.lineItemUnit}}"   width="20mm" align="right" />
        <col name="amount" label="{{t.invoice.lineItemAmount}}" width="20mm" align="right" />
        <col name="price"  label="{{priceColumnLabel}}"         width="20mm" align="right" />
        <col name="total"  label="{{t.invoice.lineItemSum}}"    width="20mm" align="right" />

        <summary>
          <row label="{{t.invoice.total}}" value="{{total}}" />
        </summary>
      </invoice-table>
    </region>

    <region id="footer" flow="sequential">
      {{#if extra}}
        <text font="regular" font-size="12">{{extra}}</text>
        <spacer height="10mm" />
      {{/if}}
      <text font="regular" font-size="12">
        {{t.invoice.invoiceIssuedBy}} {{issuer}}
      </text>
    </region>
  </layout>
</inml>