Kvitteringer

Maler

Kvitteringssystemet i Mandarin Kasse er bygd opp av maler, og det er egne maler basert på type kvittering:

• Vanlig kvittering
• Faktura
• Svinn
• Korreksjon
• Retur av varer

Malsystemet er bygd på XML med innslag av Liquid.

Mal-oppbygging

Malene er bygd opp av et rotelement <receipt>, med underliggende linjeemelent <line> som kan inneholde flere tekstelement <text>. Det finnes også flere elementer som <cut/> for å indikere at det skal skjæres på dette punktet i kvitteringen.

<receipt></receipt>

Dette er rot-elementet i en kvitteringsmal. En mal kan kun inneholde ett rot-element. Dette elementet inneholder kvitteringen eller kvitteringene som skal lages. Det har ingen attributter.

<line></line>

Dette elementet indikerer en linje. Innholdet i linjen kan gå over flere linjer, men alt i elementet vil starte på en ny linje. Elementet kan ikke inneholde ren tekst. Tekst skal puttes i <text>-element. Elementet kan har to valgfrie attributter for å bestemme formatering på linjen; center="true" og height="true". center="true" indikerer at innholdet på linjen skal være sentrert. height="true" indikerer at teksten på linjen skal være ekstra høy.

<text></text>

Dette elementet inneholder all tekst, og innholdet kan formateres ved hjelp av attributter som bold="true", align="right" og lenght="10". align er standard satt til "left". length="10 brukes til å indikere at teksten skal ta opp en fast mengde plasser uansett innhold i elementet. Står lengden til 10 så vil en tekst på 5 tegn fortsatt ta opp 10 plasser. Om length er brukt i kombinasjon med align="right" vil teksten være høyrejustert i feltet på de antall tegn du spesifiserte. Spesifiserer du 10 tegn og teksten er 5 tegn vil det skrives ut 5 tomme tegn først etterfulgt av teksten.

<cut/>

Dette elementet brukes for å indikere at kniven på en kvitteringsskriver skal skjære. Det er nyttig å bruke midt i en mal om innholdet skal splittes opp. Eksempelvis er denne brukt i faktura-standardmalen der det kommer ut ekstra kopi som skal signeres av kunde.

Valg av mal

For å velge hvilken mal som blir brukt til hvilken kvitteringstype, brukes følgende notasjon i INI-filen:

[install]
TicketTemplateReceipt=standardreceipt
TicketTemplateInvoice=standardinvoice
TicketTemplateWastage=standardwastage
TicketTemplateCorrection=standardcorrection
TicketTemplateReturnOfGoods=standardreturnofgoods

Verdiene over viser standardverdiene for hver kvitteringstype. Navnet på malene kan finnes i Mandarin Setup under Kvitteringsmaler.

Lag ny mal

Nye maler lages i Mandarin Setup under Kvitteringsmaler. Det som er viktig å huske på er at navn på maler ikke kan gjenbrukes, heller ikke etter at en mal er slettet. Standardmalene som ligger ikke kan ikke slettes og er betegnet med navn som starter på "standard".

Ved oppretting av ny mal, velg et navn som er enkelt å skrive som en opsjon i INI-filen senere. Navn uten mellomrom og spesialtegn er godt egnet.

I listen til høyre har du oversikt over alle felter som er mulig å bruke i malen. Tabeller er notert som (array) og for å få ut verdiene må du iterere over tabellen. Her er et eksempel med "HeaderLines" og "Taxes":

  {% for HeaderLine in HeaderLines %}
  <line align="center">
    <text>{{ HeaderLine }}</text>
  </line>
  {% endfor %}
  {% for Tax in Taxes %}
  <line>
    <text length="5" align="right">{{ Tax.Rate | monetize }}</text>
    <text length="13" align="right">{{ Tax.Base | monetize }}</text>
    <text length="10" align="right">{{ Tax.Amount | monetize }}</text>
    <text length="14" align="right">{{ Tax.Total | monetize }}</text>
  </line>
  {% endfor %}

Bruk av filter

I Liquid finnes det flere filtre som verdier kan mates inn i. Filterene brukes til å manipulere utseende på inndata før de blir skrevet ut til kvitteringen. Dette kan være nyttig når f.eks. tall må formateres i et spesielt format. Ved å følge linken kan du se hvordan filtre brukes. I tillegg til standardfilter, har Mandarin noen spesiallagde filtre for å forenkle mal-design.

• Pluralize - justerer utdata i henhold til antall på inndata (entall/flertall)
• Monetize - Formaterer desimalnummer med 2 eller spesifisert antall desimaler
• Repeat - Repeterer inndata x antall ganger
• FillWidth - Fyller bredden av kvitteringen med inndatastreng

Disse filtrene kan brukes på følgende måter

{{ 1 | pluralize: 'vare', 'varer' }} -> vare
{{ 2 | pluralize: 'vare', 'varer' }} -> varer

{{ TotalAmount | monetize }} ->    1234,56
{{ TotalAmount | monetize: 3 }} -> 1234,567

{{ '1234' | repeat: 2 }} -> 12341234
{{ '1234' | repeat: 4 }} -> 1234123412341234

Ved standard kvittering (42 tegn)
{{ '=' | fill_width }} -> ==========================================
Ved smal kvittering (30 tegn)
{{ '=' | fill_width }} -> ===========================

Standardfiltre som brukes i standardmalene inkluderer:

• Escape - Tar tekst og gjør den sikker for XML. Mange spesialtegn kan fort krasje hele malsystemet om escape ikke blir brukt på tekster med spesielle tegn.
• Round - Runder av tall til spesifisert antall desimaler
• Upcase - Gjør om hele teksten til store bokstaver

Disse filtrene kan brukes på følgende måter

{{ SpecialCharsText | escape }} -> Tekst som passer for XML

{{ 1234.1234 | round: 2 }} -> 1234.12

{{ 'Hei verden!' | upcase }} -> HEI VERDEN!

Mal-objekt

Vanlig kvittering, faktura og svinn

Vanlige kvitteringer, faktura og svinn har tilgang til samme data ved malbygging.

{
    ReceiptWidth: int, // 42 / 30
    HeaderLines: [string],
    FooterLines: [string],
    CompanyName: string,
    OrderDateTime: DateTime,
    PosID: string,
    OrderNr: int,
    OriginalNr: int,
    Employee: {
        Initials: string,
        Name: string
    },
    Table: {
        Nr: int
    },
    CardCustomer: {
        Nr: int,
        Name: string
    },
    ReceiptType: string,
    OrderLines: [{
        ProductName:string,
        Sum: decimal,
        Quantity: decimal,
        Price: decimal,
        Weight: decimal,
        Tara: decimal,
        DiscountTotal: decimal,
        SubElement: boolean
    }],
    OrderTotalProducts: decimal,
    OrderTotal: decimal,
    Payments: [{ // Type = "cash"
        Sum: decimal,
        ForeignSum: decimal (optional),
        LocalCurrencyName: string (optional),
        ForeignCurrencyName: string (optional),
        Type: string,
        Cashback: decimal (optional),
        Name: string,
        Exchange: decimal,
    },{ // Type = "card"
        Sum: decimal,
        Type: string,
        Cashback: decimal (optional),
        Name: string, //Viser navnet til korttypen om spesifiserkorttype=true under [install] i ini-filen
    },{ // Type = "invoice"
        Sum: decimal,
        Type: string,
        Name: string,
        Tip: decimal  (optional)
    },{ // Type = "withdrawal" / "tip" / "wastage" / "notdone"
        Sum: decimal,
        Type: string,
        Name: string
    }],
    CardText: string,
    CardSignatureText: string,
    Taxes: [{
        Rate: decimal, // 25.00, 15.00, etc
        Base: decimal,
        Amount: decimal,
        Total: decimal // Base + Amount
    }],
    TaxTotal: {
        Base: decimal,
        Amount: decimal,
        Total: decimal // Base + Amount
    },
    Customer: {
        Nr: int,
        Name: string,
        DeliveryAddress: [{}],
        InvoiceAddress: [{}],
        Email: string (optional),
        Agreement: string (optional),
        Phone: string (optional),
        CellPhone: string (optional),
        WorkPhone: string (optional),
        ReferenceNr: string (optional),
        ReferenceName: string (optional),
        CurrentCredit: decimal,
        PrePaid: boolean,
        OrderProjectNr: string (optional),
        OrderReferenceName: string (optional)
    }
}

Korreksjon

Slippen som kommer skrives ut for signatur av ansatt for internt bruk.

{
    ReceiptWidth: int, // 42 / 30
    OrderDateTime: DateTime,
    PosID: string,
    OrderNr: int,
    Employee: {
        Initials: string,
        Name: string
    },
    Table: {
        Nr: int
    },
    CardCustomer: {
        Nr: int,
        Name: string
    },
    OrderLines: [{
        ProductName:string,
        Sum: decimal,
        Quantity: decimal,
        Price: decimal,
        Weight: decimal,
        Tara: decimal,
        DiscountTotal: decimal,
        SubElement: boolean
    }],
    OrderTotalProducts: decimal,
    OrderTotal: decimal
}

Retur av varer

Slippen som kommer skrives ut for signatur av ansatt og kunde for internt bruk.

{
    ReceiptWidth: int, // 42 / 30
    Title: string,
    OrderDateTime: DateTime,
    PosID: string,
    OrderNr: int,
    Employee: {
        Initials: string,
        Name: string
    },
    Table: {
        Nr: int
    },
    OrderLines: [{
        ProductName:string,
        Sum: decimal,
        Quantity: decimal,
        Price: decimal,
        Weight: decimal,
        Tara: decimal,
        DiscountTotal: decimal,
        SubElement: boolean
    }],
    OrderTotalProducts: decimal,
    OrderTotal: decimal
}

Eksempel

Dette eksempelet viser standardmalen for vanlig kvittering som følger med en ny installasjon av Mandarin.

<?xml version="1.0" encoding="utf-8"?>

<receipt>
  <line height="true" align="center">
    <text bold="true">{{ CompanyName }}</text>
  </line>
  {% for HeaderLine in HeaderLines %}
  <line align="center">
    <text>{{ HeaderLine }}</text>
  </line>
  {% endfor %}
  <line>
    <text>{{ OrderDateTime }}</text>
    <text align="right">Kasse: {{ PosID }}</text>
  </line>
  <line>
    <text>Kvitt: #{{ OrderNr }}</text>
    <text align="right">Ansatt: {{ Employee.Initials }}</text>
  </line>
  {% if Table %}
  <line>
    <text>BordNr: {{ Table.Nr }}</text>
  </line>
  {% endif %}
  {% if Customer %}
  <line>
    <text>Kunde: {{ Customer.Name | escape }}</text>
  </line>
  {% endif %}
  {% if CardCustomer %}
  <line>
    <text>Kortkunde: {{ CardCustomer.Nr }} {{ CardCustomer.Name | escape }}</text>
  </line>
  {% endif %}
  <line align="center">
    <text bold="true">* {{ ReceiptType }} *</text>
  </line>
  <line>
    <text></text>
  </line>
  {% for OrderLine in OrderLines %}
  <line>
    <text>{{ OrderLine.ProductName | escape }}</text>
    <text align="right">{{ OrderLine.Sum | monetize }}</text>
  </line>
  {% if OrderLine.Quantity != 1 %}
  <line>
    <text>  {{ OrderLine.Quantity }} à kr {{ OrderLine.Price | monetize }}</text>
  </line>
  {% elsif OrderLine.Weight != 0 %}
  <line>
    <text>  {{ OrderLine.Weight | minus:OrderLine.Tara | round:3 }} kg à kr {{ OrderLine.Price | monetize }} pr kg</text>
  </line>
  {% endif %}
  {% if OrderLine.DiscountTotal != 0 %}
  <line>
    <text>  -{{ OrderLine.DiscountName }}</text>
    <text align="right">-{{ OrderLine.DiscountTotal | monetize }}</text>
  </line>
  {% endif %}
  {% endfor %}
  <line>
    <text>{{ '-' | fill_width }}</text>
  </line>
  <line>
    <text bold="true">Sum {{ OrderTotalProducts }} {{ OrderTotalProducts | pluralize: 'vare', 'varer' }}</text>
    <text align="right">{{ OrderTotal | monetize }}</text>
  </line>
  {% for Payment in Payments %}
  <line>
    <text>{{ Payment.Name | upcase }}</text>
    <text align="right">{{ Payment.Sum | monetize }}</text>
  </line>
  {% if Payment.Type == 'cash' and Payment.Cashback and Payment.Cashback != 0 %}
  <line>
    <text>TILBAKE KONTANT</text>
    <text align="right">{{ Payment.Cashback | monetize }}</text>
  </line>
  {% endif %}
  {% endfor %}
  <line>
    <text>{{ '=' | fill_width }}</text>
  </line>
  <line></line>
  <line>
    <text length="5">Mva%</text>
    <text length="13" align="right">Grunnlag</text>
    <text length="10" align="right">Mva</text>
    <text length="14" align="right">Totalt</text>
  </line>
  <line>
    <text>{{ '-' | fill_width }}</text>
  </line>
  {% for Tax in Taxes %}
  <line>
    <text length="5" align="right">{{ Tax.Rate | monetize }}</text>
    <text length="13" align="right">{{ Tax.Base | monetize }}</text>
    <text length="10" align="right">{{ Tax.Amount | monetize }}</text>
    <text length="14" align="right">{{ Tax.Total | monetize }}</text>
  </line>
  {% endfor %}
  <line>
    <text>{{ '-' | fill_width }}</text>
  </line>
  <line>
    <text length="5">Sum</text>
    <text length="13" align="right">{{ TaxTotal.Base | monetize }}</text>
    <text length="10" align="right">{{ TaxTotal.Amount | monetize }}</text>
    <text length="14" align="right">{{ TaxTotal.Total | monetize }}</text>
  </line>
  <line>
    <text>{{ '-' | fill_width }}</text>
  </line>
  {% if CardText %}
  <line>
    <text>{{ CardText }}</text>
  </line>
  {% endif %}
  <line>
    <text>{{ '*' | fill_width }}</text>
  </line>
  {% for FooterLine in FooterLines %}
  <line align="center">
    <text>{{ FooterLine }}</text>
  </line>
  {% endfor %}
</receipt>