Documentsjablonen: wat, waarom en hoe.
Dit artikel is een gids over documentsjablonen: wat ze zijn en hoe ze worden ingesteld en gebruikt.
Inhoudsopgave
Samenvatting
-
Wat is een Qargo-sjabloon?
- Een personaliseerbaar, herbruikbaar ontwerp om bedrijfsdocumenten aan te maken, zoals facturen, afleveringsbewijzen, laadbonnen, offertes enz.
- Kan in taken worden gebruikt om automatisch documenten aan te maken en/of te versturen.
-
Waarom sjablonen gebruiken?
- Met sjablonen bepalen gebruikers hoe documenten eruitzien en welke gegevens erin staan.
- Elk bedrijf kan documenten aanmaken in een gewenst formaat, afgestemd op het werkproces, de taal en de huisstijl van het bedrijf.
- Alle vereiste gegevens worden dynamisch vanuit het TMS ingevuld.
-
Hoe worden sjablonen gebruikt?
- Om documenten aan te maken die aan orders en trips gekoppeld zijn.
- In combinatie met werkprocestaken worden documenten vlot en op het juiste moment aangemaakt.
- Documenten worden automatisch aangemaakt, wat invoerfouten vermindert. In combinatie met contacttaken wordt het werkproces efficiënter, bv. een POD of factuur per e-mail versturen enz.
Voorbeeld: taken ‘Document genereren’

-
3 kerncomponenten:
- Handlebars-sjabloon: dynamische placeholders om gegevens in te voegen
- Sjabloonschema: gestructureerde definitie van alle dynamische velden die in het sjabloon beschikbaar zijn; kan lijsten, tabellen, tekst enz. bevatten
- Datamodel: de werkelijke gegevens die bij het aanmaken aan het sjabloon worden doorgegeven (bv. orderwaarde)
-
De velden in het sjabloonschema bepalen welke dynamische gegevenselementen kunnen worden opgehaald en getoond, of herhaald.
- Dat kunnen eenvoudige velden zijn, bv. ‘titel’, of complexere velden voor lijsten en tabellen waarvoor parameters nodig zijn.
-
Sjablonen kunnen worden geconfigureerd door schema’s en visuele lay-outs te bewerken
- Selecteren welke velden worden getoond en logica bepalen (bv. if/else, voorwaarden enz.)
-
Documenten aanmaken: het sjabloon haalt de meest recente gegevens op en vult de dynamische velden in volgens het sjabloonschema en het datamodel.
- Het resultaat is een gebruiksklaar document in het gewenste formaat (bv. PDF, CSV)
-
Sjablonen kunnen globaal of tenantspecifiek zijn
- Globaal sjabloon = basislay-out die kan worden overschreven of met eigen variabelen kan worden uitgebreid
- Tenantsjabloon = afgestemd op speciale vereisten, bv. om aan wettelijke of reglementaire eisen te voldoen.
-
Ondersteunde functies in sjablonen:
- Meertalige ondersteuning (lokalisatie), indien ingeschakeld
- Tabellen en contextspecifieke lussen
- Aangepaste helpers (zoals datums opmaken, barcodes enz.)
- Verwerking van speciale gevallen en voorwaarden, bv. een veld niet tonen als het leeg is
- Bijlagen of afbeeldingen, bv. handtekeningen
-
Met Handlebars-expressies is geavanceerde logica mogelijk

Terminologie
| Term | Definitie |
|---|---|
| Qargo-sjabloon: | Standaard, globale sjabloonversies die Qargo aanbiedt en onderhoudt; dienen als referentiebibliotheek; eenvoudig aan te passen voor huisstijl, taal, speciale gegevensvereisten enz. |
| Tenantsjabloon | Gepersonaliseerd sjabloon dat specifiek is voor de tenant (account) |
| Extern sjabloon | Documentsjablonen uit een externe bron die kunnen worden gebruikt of waarnaar kan worden verwezen; dit kunnen sjablonen zijn die door meerdere organisaties of locaties worden gedeeld, standaardformaten uit de sector of sjablonen die uit externe systemen zijn geïmporteerd, bv. creditnota’s, self-bills, tripbladen, CMR’s. |
| Basissjabloon | Algemeen sjabloon waarmee een nieuw documentsjabloon wordt aangemaakt; wordt geselecteerd in een keuzelijst met vooraf bepaalde opties, op basis van de categorie van het document dat wordt aangemaakt, bv. ‘factuur’. |
| Gearchiveerd sjabloon | Sjablonen die niet meer in het platform worden ondersteund; meestal vervangen door een bijgewerkte versie. |
| Handlebars-expressie | Handlebars-expressies zijn speciale placeholders en logische blokken in sjablonen waarmee gegevens worden ingevoegd en voorwaardelijke of herhalende logica wordt toegevoegd bij het aanmaken van documenten of e-mails. |
| Contextlabel (blauw) | Wordt bij bepaalde velden of rijen in de sjablooneditor getoond; geeft aan dat een veld gekoppeld is aan een specifiek deel van de onderliggende gegevens, bv. stops, die dan als één rij per stop worden getoond. |


De sjabloonindeling begrijpen
Bij het toevoegen van een nieuw sjabloon moet eerst een basissjabloon worden geselecteerd. Daarna worden de gegevensrijen en het previewvenster (nr. 3 Visualiseren) getoond. Het sjabloon wordt met algemene gegevens getoond.

- Op de pagina Nieuw sjabloon het gepaste ‘Basissjabloon’ in de keuzelijst selecteren.
- Het nieuwe sjabloon configureren. Het nieuwe sjabloon een naam geven waaraan het gebruik makkelijk te herkennen is. Velden aanpassen om het sjabloon te personaliseren, of het basissjabloon ongewijzigd gebruiken.
- Het sjabloonformaat in het previewvenster visualiseren. Door op een element in het previewvenster te klikken, wordt de bijbehorende gegevensrij gemarkeerd. In de rij klikken als de getoonde gegevens moeten worden gewijzigd.
-
De sjabloongegevens bewerken door in de gepaste rij te klikken en de inhoud te bewerken.
- In de rij klikken of het ‘oog’-pictogram gebruiken markeert de gegevens van deze rij in het previewvenster.
- Op informatie in het previewvenster klikken markeert de gepaste rij waarin de gegevens kunnen worden bewerkt.
- Het veld ‘Data-eigenaar’ gebruiken om live gegevens te bekijken; de getoonde opties hebben specifiek betrekking op het document. In het voorbeeld hieronder gaat het bijvoorbeeld om een facturatievoorstel, dus de opties in het veld Data-eigenaar zijn aankoopfacturen.
De bewerkingspictogrammen begrijpen
- Door in een rij te klikken om details te bewerken, wordt een reeks bewerkingsopties getoond.

- Opties voor tekstbewerking, waaronder vet, cursief en onderstrepen; lettergrootte en kleur; met H en h worden de gegevens als kop 1 (H) of kop 2 (h) opgemaakt.
- Een URL-link naar een website toevoegen. Er verschijnt een pop-upvenster waarin de link kan worden toegevoegd.
- Gegevens als opsommingstekens of genummerde lijst toevoegen.
- Syntaxisblokken om geavanceerdere voorwaarden aan te maken met expressies die meerdere variabelen of voorwaarden combineren.
- Opmaakopties om een pagina-einde of HTML-blok toe te voegen
Syntaxisblokken gebruiken

- Bij het bewerken van een sjabloon zijn er syntaxisopties beschikbaar om sjablonen aan te maken die specifieke voorwaarden weergeven.
Handlebars-expressies
-
Handlebars-expressies worden gebruikt om variabelen te selecteren die aan het document gekoppeld zijn. De variabelen in de keuzelijst zijn specifiek voor het document en de bijbehorende rij.

‘IF’-blok
-
Het IF-blok in een documentsjabloon gebruiken om bepaalde inhoud of opmaak alleen onder specifieke voorwaarden te tonen, op basis van de gegevens. Bijvoorbeeld om een veld alleen te tonen als het niet leeg is, of om een rij alleen te markeren als een waarde een drempel overschrijdt.
-
Veelvoorkomende scenario’s:
- Kosten met bedrag 0 verbergen: met een IF-blok een kost alleen tonen als de waarde groter is dan nul.
- Inhoud voorwaardelijk tonen: bijvoorbeeld een opmerking of sectie alleen tonen als een veld bepaalde tekst bevat (zoals de naam van een specifieke onderaannemer of een ingevulde opmerking).
- Voorwaardelijke opmaak: tekst vet maken of speciale stijlen toepassen als een waarde aan een voorwaarde voldoet (bv. een locatie vet maken als er een bijbehorende opmerking bestaat).

FOR-blok
-
Het FOR-blok is een krachtige functie in de documentsjablooneditor van Qargo, waarmee documenten dynamisch en op basis van gegevens worden aangemaakt.
-
Om alle producten van een order op te sommen, met elk product en de beschrijving ervan op een nieuwe regel, een FOR-blok voor de goederenarray toevoegen en de productdetails in het blok plaatsen. Het FOR-blok zorgt ervoor dat elk product een eigen regel krijgt in het uiteindelijke document.

COMBINE-instructie
-
Het COMBINE-blok gebruiken om in het sjabloon een samengevoegde of geaggregeerde lijst uit een array te tonen, bijvoorbeeld om een lijst met waarden samen te voegen tot een door komma’s gescheiden tekenreeks.
-
Een FOR-blok doorloopt elk item en geeft de inhoud telkens opnieuw weer. Het Combine-blok verwerkt de array daarentegen tot één resultaat, meestal door de elementen aan elkaar te koppelen of op een andere manier te aggregeren.
-
Een belangrijke beperking is dat IF-instructies (voorwaardelijke logica) niet in een Combine-blok kunnen worden gebruikt. Het Combine-blok is dus het meest geschikt voor eenvoudige aggregatie zonder voorwaarden per item.

Nieuw sjabloon toevoegen
-
Naar Configuratie > Sjablonen gaan
-
Klikken op ‘Sjabloon toevoegen’
-
Het documenttype in de keuzelijst selecteren.
- Opmerking: er kunnen extra opties beschikbaar zijn, bv. “Factuur” biedt de keuze tussen factuur of creditnota, en “Laadbon” biedt de keuze tussen trip of resource
-
Een basissjabloon in de keuzelijst selecteren.

-
In het venster ‘Visualiseren’ in het veld ‘Data-eigenaar’ klikken om de overeenkomende records voor dit soort document te tonen. Door een ervan te selecteren, wordt de preview van het sjabloon met klantgegevens getoond.
- Als het basissjabloon alle gegevens in de vereiste lay-out bevat, het sjabloon een naam geven en op Opslaan klikken.
-
Als de lay-out van het sjabloon moet worden aangepast, de rijen in ‘Configureren’ gebruiken om de gegevens bij te werken.
Een sjabloon aanpassen
-
Het sjabloonformaat is beschikbaar in HTML of PDF.
-
Bij PDF zijn extra opmaakopties beschikbaar. De rij ‘PDF-configuratie’ uitvouwen.
- Wijzigingen in het configuratievenster worden in het rechtervenster als preview getoond.

-
Om afzonderlijke elementen aan te passen, op het element klikken; de rij die moet worden bijgewerkt, wordt dan gemarkeerd.
- In de rij klikken; de bewerkingsopties worden getoond.
- De gepaste actie uit de opties selecteren.
- Na de selectie worden de gewijzigde gegevens bijgewerkt in het preview- of visualisatievenster, zodat ze kunnen worden bevestigd.
-
De optie ‘Achtergrond’ gebruiken om een bestaand briefhoofd te uploaden als achtergrondlay-out voor een factuur.

-
Zodra het sjabloon overeenkomt met de vereiste lay-out en inhoud, op Opslaan klikken.
De sorteervolgorde van de rijen configureren
In de documentsjablooneditor kunnen regels nu op een gekozen veld worden gesorteerd. Elke PDF die op basis van dat sjabloon wordt aangemaakt, volgt die volgorde: verkoopfacturen, creditnota’s, self-bills van onderaannemers, facturatievoorstellen en tripexports. De instelling wordt één keer in het sjabloon bepaald en geldt telkens.
Tot nu toe verschenen regels altijd in dezelfde vaste volgorde (op het geplande starttijdstip van de eerste stop, daarna op de naam van de kost), zonder mogelijkheid om dat te wijzigen. Die volgorde is nu configureerbaar.
Een sorteersleutel instellen
- Naar Configuratie > Sjablonen navigeren en het te bewerken sjabloon openen, of een nieuw sjabloon toevoegen.
- Het blok met rij-iteratie dat de order- of kostenrijen weergeeft, selecteren.
- In de sectie Sorteren bij Sorteren op het veld instellen dat het document moet volgen, en daarna bij Richting kiezen voor Oplopend of Aflopend.
- Optioneel een tweede Sorteren op toevoegen om gelijke waarden te ordenen, bijvoorbeeld eerst op naam van de chauffeur en daarna op geschat starttijdstip.
- Het sjabloon opslaan. Elke PDF die op basis van dat sjabloon wordt aangemaakt, volgt dan de geconfigureerde sortering.

Beschikbare sorteersleutels
De beschikbare sleutels hangen af van het soort rijen dat het geselecteerde blok weergeeft.
Voor orderrijen (sjablonen voor verkoopfacturen en creditnota’s):
- Ordernummer
- Klantreferentie
- Leveringsdatum (gevraagd)
- Leveringsdatum (werkelijk)
- Ophaaldatum (gevraagd)
- Ophaaldatum (werkelijk)
- Tijdstip laatste zendingsstop (de bestaande standaard)
Voor kostenrijen (sjablonen voor aankoopfacturen en facturatievoorstellen of self-bills):
- Naam chauffeur
- Naam resource (voertuig)
- Tripnummer
- Geschat starttijdstip (de bestaande standaard)
- Naam kost
Sjablonen voor tripexports bieden daarnaast Voertuig en Chauffeur als sorteersleutels.
Veelvoorkomend gebruik
- Een verkoopfactuur gesorteerd op Klantreferentie of Leveringsdatum, zodat de klant ze met de eigen administratie kan afstemmen.
- Een self-bill of facturatievoorstel voor een onderaannemer, gegroepeerd op Naam chauffeur (primair) en daarna chronologisch op Geschat starttijdstip (secundair), zodat de trips van elke chauffeur bij elkaar staan.
- Een tripexport gegroepeerd per voertuig door Naam resource (voertuig) als sorteersleutel te gebruiken.
Regels groeperen en subtotalen
Factuursjablonen kunnen kostenregels in blokken afdrukken, met onder elk blok een subtotaal. Dat helpt klanten en onderaannemers die een totaal per vrachtwagen, per chauffeur, per order of per trip nodig hebben, zonder dat handmatig te moeten uitrekenen. Het eindtotaal blijft altijd onderaan het document staan.
Er zijn twee opties:
- Twee basissjablonen met gegroepeerde regels, die regels groeperen op een gekozen sleutel.
- Een optionele subtotaalrij na elke order of trip op de bestaande factuursjablonen.
Regels groeperen op order, trip, voertuig of chauffeur
-
Naar Configuratie > Sjablonen navigeren en op Sjabloon toevoegen klikken.

-
Het documenttype selecteren en daarna het basissjabloon kiezen: Factuursjabloon - gegroepeerde regels voor verkoopfacturen en creditnota’s, of Aankoopfactuursjabloon - gegroepeerde regels voor facturatievoorstellen en self-bills.


-
Sjabloonopties uitklappen en Instellingen regelgroepering openen.
-
Regels groeperen op instellen op de sleutel die het document moet volgen.

-
Het sjabloon opslaan. Elk document dat op basis van het sjabloon wordt aangemaakt, drukt één blok per groep af.

De beschikbare sleutels hangen af van het document:
- Verkoopfacturen en creditnota’s: Order, Voertuig en Chauffeur.
- Facturatievoorstellen en self-bills: Trip, Order (de kostorder van de regel), Voertuig en Chauffeur.

Elk blok heeft een koptekst (bijvoorbeeld het ordernummer, de nummerplaat of de naam van de chauffeur), de bijbehorende kostenregels en een subtotaal. Subtotalen worden standaard afgedrukt. Om ze te verbergen, het veld group_subtotal_label op het sjabloon leegmaken. Koptekst en regels van de groepen blijven staan.

Regels zonder waarde voor de gekozen sleutel worden in één blok aan het einde van het document verzameld, met een eigen subtotaal. Het blok draagt de naam van de sleutel: “Geen voertuig toegewezen” of “Geen chauffeur toegewezen”.
Hoe regels aan een voertuig of chauffeur worden toegewezen:
- Op verkoopdocumenten wordt een order nooit over twee groepen verdeeld. Alle kostenregels ervan worden afgedrukt onder het voertuig of de chauffeur van de leveringsstop.
- Voertuig betekent de primaire tractor, de vrachtwagen of de bestelwagen. Een trailer wordt nooit als groep gebruikt.
- Een trip met twee primaire tractors toont beide nummerplaten in één koptekst. Hetzelfde geldt voor twee primaire chauffeurs.
Een subtotaalrij toevoegen aan bestaande factuursjablonen
De bestaande verkoopfactuursjablonen (1, 2 en 3 kolommen, totaal met details, en totaal met gegroepeerde kosten en details) en de bijbehorende aankoopfactuursjablonen kunnen na elke order (verkoop) of elke trip (aankoop) een subtotaalrij afdrukken.
-
Naar Configuratie > Sjablonen navigeren en het te wijzigen sjabloon openen.
-
order_subtotal_label invullen op verkoopsjablonen, of shipment_subtotal_label op aankoopsjablonen, bijvoorbeeld met “Subtotaal”.

-
De preview in het paneel Visualiseren controleren. De rij verschijnt onder de laatste kostenregel van elke order of trip, in dezelfde kolomindeling als de kostenrijen.
-
Het sjabloon opslaan.
Beide velden zijn standaard leeg, dus bestaande documenten veranderen pas wanneer een label is ingevuld. Om de rij weer te verwijderen, het veld volledig leegmaken.
Goed om te weten
- Er is geen paginatotaal en geen instelling voor het aantal rijen per pagina. Een factuur van meerdere pagina’s toont het totaal alleen op de laatste pagina.
- Er is geen overzichtsblok dat het totaal van elke groep toont vóór de detailregels.
Praktische probleemoplossing: voorbeelden voor factuursjablonen
-
Achtergrond wordt niet getoond: controleren of het bestandsformaat een ondersteund type is en of de optie “Tonen in PDF” tijdens het bewerken is ingeschakeld.
-
Fout
Preview could not be rendered or updated. Please verify that all open '#{{' tags have a corresponding '}}' tag.: kan erop wijzen dat het weergeven van de preview mislukt door de grote omvang van het document. Testen met een kleiner document (slechts enkele orders) om na te gaan of de preview werkt. Het aanmaken van documenten wordt hierdoor niet beïnvloed. -
Moeilijkheden bij het verwijderen van elementen: als ongewenste elementen, zoals een e-mailadres, deel uitmaken van een achtergrondbestand, dat bestand extern bewerken met bijvoorbeeld een PDF-editor en het daarna opnieuw uploaden in de configuratie-instellingen van het sjabloon.
-
Terugkerende problemen met de achtergrond: wijzigingen in het achtergrondbestand altijd opslaan voordat het opnieuw wordt geüpload, en de wijzigingen via de preview controleren.
-
Verkeerde referentienummers: om het referentienummer op facturen bij te werken:
- Naar de sectie Sjablonen in Qargo gaan.
- Het sjabloon openen dat voor de facturen van de betreffende klant wordt gebruikt.
- In het adresveld klikken. Het veld waarin de referentie is opgeslagen, wordt dan in het linkervenster gemarkeerd.
- Het referentienummer naar de gewenste waarde bijwerken.
- Het sjabloon opslaan. De bijgewerkte referentie geldt voor alle nieuw aangemaakte facturen. Als een factuur al de status “Gefactureerd” heeft, kan de PDF worden bijgewerkt door de factuur-PDF opnieuw te genereren, zodat de nieuwe referentie verschijnt.
-
Klantreferenties in Peppol XML controleren: om na te gaan of een klantreferentie in de Peppol XML van een factuur staat:
- De factuur in Qargo openen.
- De preview van de Peppol XML openen.
- Met de zoekfunctie de referentiewaarde opzoeken door het verwachte referentienummer te plakken.
- Controleren of de referentie in de XML in het previewvenster rechts verschijnt.
