Templates and data

Applies to: BarcoderX Basic and Ultimate

Status: Planned. Nothing is released yet and there is nothing to download. This page explains the ideas at the level of concepts. Names of properties and options are working names until the first release.

What a template is

A label template is a document that describes one label: its page, the elements on it, the data it expects and how it behaves. The same template drives the preview, the exported files and the printing. BarcoderX has its own template format. It does not copy the format of any other product.

A template holds:

• The page: width and height, the unit, the resolution, the orientation, the color mode, the media and the print settings.
• The elements on the label, in order.
• The fields that the label expects from your data, and the variables, counters and masks it uses.
• Settings for how the label behaves, such as what to do with a missing value or with invalid barcode data.

The page

• Units: inch, millimeter, centimeter, dot, point, pica, mil, twip and micrometer. BarcoderX stores each value exactly as you write it.
• Resolution: any whole number of dots per inch from 96 to 1,200. The standard values are 152, 203, 300 and 600.
• Position and angle: the origin is the top-left corner of the label. A value to the right or downward is positive. An element turns clockwise around its center by any angle.
• Orientation: 0, 90, 180 or 270 degrees, applied to the whole page. The positions of the elements in the template do not change.
• Color mode: black and white, gray or color.
• Media: continuous, gap or black mark.
• Layout: columns and rows of labels on a roll or a sheet, with gaps, margins and the order in which the labels fill.
• Retargeting: you can move a design to another resolution. BarcoderX rescales it and tells you the X-dimension you actually get, if it differs from the one you asked for.
• Guides: a page can have non-printing guides and a background image, and safe insets that warn you when an element crosses them. None of these reach the output.

The elements

A template can hold ten kinds of element:

Every element has a name, a position, a size and a rotation. It can also carry a condition, called print when, that decides whether it appears. An element can be locked, and it can carry a comment. The order of the elements is the stacking order, and the first element is at the bottom.

Almost any property of an element can be set by an expression, such as its position, color, font size or symbology.

JSON and XML

• JSON is the main format. BarcoderX reads and writes it in a fixed, predictable form, so the same template is always saved the same way.
• XML is an exact equivalent. A template converted from JSON to XML and back to JSON comes out identical. XML is planned for the first release. A schema is published for each format, so you can check a template before you load it.
• Templates are versioned. Each template carries the version of the format it uses. BarcoderX upgrades an older template when it loads it. Every version of the format that has been released keeps loading in every later release. A template written for a newer format than your BarcoderX understands is refused with a clear message, and nothing is half loaded.
• Nothing is lost. Properties that BarcoderX does not know are kept and written back, so a newer template does not lose data when an older tool edits it. A host application can also keep its own data in members whose names start with x- and an identifier of the host.
• Readers are hardened. XML cannot load outside files or definitions. Depth and size are limited, and a template that goes past a limit is refused quickly.

Here is a short illustration. It is a GS1-128 shipping label, with an upper-cased name, a line, and a barcode built from an SSCC field. The illustration is abridged, and the property names are working names that can change before release.

{
  "schemaVersion": 1,
  "name": "shipping-sscc",
  "page": {
    "unit": "mm", "width": 101.6, "height": 152.4, "dpi": 203, "orientation": 0,
    "media": { "sensing": "gap", "gapLength": 3 },
    "layout": { "columns": 1, "rows": 1 }
  },
  "fields": [
    { "name": "ShipTo.Name", "type": "string" },
    { "name": "Sscc", "type": "string" }
  ],
  "counters": [ { "name": "box", "start": 1, "step": 1, "width": 3 } ],
  "elements": [
    { "type": "text", "id": "e1", "name": "shipTo", "x": 5, "y": 5, "width": 90, "height": 12,
      "content": { "expr": "Upper({ShipTo.Name})" },
      "font": { "family": "BX Core", "size": 14, "bold": true },
      "sizing": "shrinkToFit", "align": "start" },
    { "type": "line", "id": "e2", "x": 0, "y": 95, "x2": 101.6, "y2": 95, "stroke": 0.5 },
    { "type": "barcode", "id": "e3", "x": 8, "y": 100, "width": 85, "height": 32,
      "symbology": "gs1-128", "content": { "expr": "\"(00)\" & {Sscc}" },
      "xDimension": 0.375, "humanReadable": { "position": "below" }, "output": "auto" }
  ]
}

Data

BarcoderX gets your data from a data source, matches it to the fields of the template and makes one label for each record. It repeats each label for the number of copies you ask for. The number of copies can be a constant, a field or an expression.

In the SDK, a data source can be:

• a list of .NET objects, read without slow per-row lookups;
• a DataTable, or a table of a DataSet;
• a DataView or a forward-only data reader, for very large sets, with bounded memory;
• a CSV file, with a header row, any delimiter and quoted fields that contain line breaks;
• a JSON document, as an array of objects or the part you point to;
• an XML document, where you name the row element and its attributes and child elements become fields.

In the web API, you send the data in the request, or you store a data source on your server and refer to it. The engine never fetches data from the internet.

• Fields are found by a dotted path such as ShipTo.Name, without regard to upper or lower case.
• Declared fields. A template can declare the fields it expects, so the editor and the validator work without live data. A reference to a field that is not declared produces a warning. BarcoderX can also work out the field list from a sample CSV, JSON or XML file.
• Missing values. You choose what happens when a value is missing: empty text, an error or a placeholder. A diagnostic is raised each time.
• Formatting. Numbers and dates are always formatted with an explicit culture. The same number is written differently for Spanish and for English, and the culture of the computer is never used.
• Label text in several languages. A template can hold its own texts for several languages and pick one by key, depending on the language of the job. This is separate from the language of BarcoderX itself.
• Pictures come from an asset ID, an asset name or base64 data in a field.
• Secret values. A template can declare a variable of type secret, for example for an RFID password. The template never holds its value. Each job supplies it. It is not shown in logs, previews or audit records.

Counters, masks and sequences

• A counter has a name, a start, a step (positive or negative), a width and padding, an alphabet (decimal, hexadecimal, letters, letters and digits, or your own), and what happens at the end (wrap or stop with an error). It can count per label, per copy or every given number of labels. BarcoderX calculates counters itself, so running the same job twice gives the same numbers. Where the printer can number labels itself, BarcoderX can hand the counting to the printer when you choose the NativePreferred intent.
• A mask formats a value with a pattern such as (##) ####-####, where # stands for a digit, A for a letter and * for a letter or a digit. A mask can also say how a serial number counts up, skipping the fixed characters.
• A sequence is a counter that lives on your server, in the web API. It gives out blocks of numbers that never overlap, even when many requests ask at the same time, and a repeated request returns the same block. Sequences suit serial references such as the SSCC.

Templates in the web API

The web API keeps every saved version of a template and does not change it afterwards. You work on a draft, publish it, and can restore an earlier version. A template with its fonts and images can be exported as one archive and imported into another server. When a font is imported, the person who imports it must confirm the font license again.

Limits

BarcoderX limits the size of a template, how deeply it can be nested, the number of elements and the size of data sources, and refuses input that goes past a limit. The web API publishes the limits in force.

BarcoderX is a product of P4 Software.