Aller au contenu principal

Modèles d'étiquettes et de tickets

Un modèle est une étiquette ZPL, une étiquette EPL ou un ticket avec des {{variables}}. Créez-le une fois dans le tableau de bord, puis imprimez-le depuis n'importe quelle application avec l'ID du modèle et les données :

await jp.print({
  templateId: "tpl_01J9SHIPLABEL",
  data: { order: "10492", customer: { name: "Anne Joseph" } },
});
  • Mode cloud (POST /v1/jobs) : le cloud remplit le modèle, et l'agent reçoit du ZPL, de l'EPL ou du JSON de ticket ordinaire.
  • Mode local (SDK navigateur) : chaque agent de l'organisation reçoit les modèles dans sa configuration et les remplit lui-même. Cela fonctionne aussi hors ligne.

Créer un modèle​

Tableau de bord → Modèles → Nouveau modèle :

  1. Choisissez le type : étiquette ZPL, étiquette EPL ou ticket. L'éditeur part d'un exemple qui fonctionne.
  2. Choisissez le papier (facultatif). Un travail qui ne précise pas de papier utilise celui du modèle.
  3. Écrivez le modèle et des données d'exemple (JSON).
    • L'aperçu montre ce que reçoit l'imprimante.
    • Pour les tickets, il montre aussi une image dessinée par le moteur de l'agent lui-même.
  4. Enregistrer. Les agents reçoivent le modèle en quelques secondes. L'éditeur affiche ensuite le code pour l'imprimer.

Une organisation peut avoir 200 modèles, 2 Mo au total.

Syntaxe​

ÉcrivezRésultat
{{name}}La valeur, échappée selon le type de modèle
{{customer.name}}Une valeur imbriquée
{{{name}}} ou {{& name}}La valeur telle quelle, non échappée
{{#items}}…{{/items}}Répété pour chaque élément d'une liste. Un objet devient le contexte une seule fois ; les autres valeurs affichent le bloc quand elles sont vraies, non vides ou non nulles.
{{^items}}…{{/items}}Affiché quand la valeur est absente, fausse, vide ou nulle
{{.}}L'élément courant d'une liste
{{@index}}, {{#@first}}…{{/@first}}, {{^@last}}…{{/@last}}Position dans une liste (à partir de 0), premier et dernier élément
{{! note }}Un commentaire

Une valeur absente n'imprime rien. Les nombres, true et false s'impriment comme en JSON ; les objets et les listes s'impriment en JSON.

Échappement​

Les valeurs de vos données ne peuvent jamais devenir des commandes d'imprimante :

  • ZPL :
    • Dans un champ qui commence par ^FH (par exemple ^FO40,40^A0N,40,40^FH^FD{{name}}^FS), les caractères ^, ~, l'indicateur de ^FH et les caractères de contrôle sont imprimés à l'identique, sous forme de codes hexadécimaux (_5E).
    • Ailleurs, ces caractères sont supprimés.
    • Placez ^FH avant ^FD dans chaque champ qui contient une valeur. Les exports de ZebraDesigner utilisent déjà ^FH\, et l'indicateur \ est aussi pris en charge.
  • EPL : les guillemets et les barres obliques inverses reçoivent une barre oblique inverse, et les retours à la ligne sont supprimés.
  • Tickets : les valeurs sont écrites comme contenu de chaîne JSON, donc les guillemets et les retours à la ligne ne posent pas de problème. Utilisez {{{rows}}} pour insérer une liste de vos données en JSON :
{ "type": "table", "columns": [{ "width": 0.7 }, { "width": 0.3, "align": "right" }], "rows": {{{rows}}} }

ou construisez les lignes dans le modèle :

"rows": [{{#items}}["{{name}}", "{{price}}"]{{^@last}},{{/@last}}{{/items}}]

Imprimer depuis votre serveur​

curl https://api.jodaprint.dev/v1/jobs \
  -H "Authorization: Bearer $JODAPRINT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"deviceId":"dev_…","alias":"label","templateId":"tpl_01J9SHIPLABEL","data":{"order":"10492"}}'

GET /v1/templates liste les modèles (portée jobs:read). Avec le SDK Node :

const { data: templates } = await jp.templates.list();
await jp.jobs.create({ deviceId: "dev_…", templateId: templates[0].id, data: { order: "10492" } });

Un travail avec un modèle inconnu, ou avec des données que le modèle ne peut pas rendre, échoue avec INVALID_JOB.

Aperçu des étiquettes​

Le tableau de bord montre l'aperçu des étiquettes ZPL et EPL sous forme des commandes que reçoit l'imprimante, pas sous forme d'image. L'ADR 0040 explique pourquoi. Pour voir une étiquette dessinée, collez le ZPL rendu dans un visualiseur de confiance. Le résultat rendu contient vos données.

Documents : rapports et devis​

Un modèle Document (HTML) est une page complète en HTML et CSS, pour les imprimantes laser et jet d’encre : rapports, devis, relevés.

  • L’agent l’imprime via le navigateur de l’ordinateur (Chrome ou Edge), qui doit donc en avoir un. Les agents Android n’impriment pas le HTML.
  • Réglez le format et les marges en CSS : @page { size: letter; margin: 16mm; }, ou size: A4.
  • Les valeurs sont échappées en HTML (<, >, &, guillemets) : les données ne deviennent jamais du balisage. N’utilisez {{{html}}} que pour du HTML de confiance.
  • Les agents à partir de la version 1.0.1 reçoivent les modèles HTML pour le mode local. Les travaux cloud fonctionnent avec toutes les versions.

Galerie​

Tableau de bord → Modèles → Galerie propose des modèles prêts à l’emploi : 5 tickets, 5 étiquettes, 5 rapports et 5 devis. Utiliser ce modèle ouvre une copie dans l’éditeur, avec les mots imprimés (Total, Devis…) dans votre langue et des données d’exemple qui montrent les variables attendues. Enregistrez-la, puis modifiez-la à votre guise : c’est votre modèle.