05Expressions

Expressions compute the content of an element from the record: fields, functions, operators, variables, references to other elements and translations. They work the same in the label model, in data binding, in print jobs, in zplCore Server and in the zplCore Designer.

Expressions

Fields as [Name] or [Customer.Address.City], element names ([TextItem1]), literals, operators + - * / % (+ concatenates text), = <> < <= > >=, and/or/not. Variables LABEL_INDEX, LABEL_NUMBER and your own.

var label = new Label();
label.Expressions.Variables["SHIFT"] = "B";
label.Expressions.Functions["Euro"] = args => $"{ExpressionEngine.Num(args[0]):0.00} €";

label.Add(new TextItem { Expression = "Euro([Price] * 1.2) + \" / Schicht \" + SHIFT" });
label.Add(new TextItem { Y = 8, Expression = "Format(AddDays(Today(), 30), \"dd.MM.yyyy\")" });
label.Add(new TextItem { Y = 16, Expression = "Gs1CheckDigit(\"95060001343\")" });

var engine = new ExpressionEngine();
string s = engine.EvaluateToString("PadLeft(Str(42), 6, \"0\")");   // "000042"

Types, custom functions and variables

Expressions may call public members of registered types (AddTypeReference) – everything else stays blocked. SetCustomFunction/SetCustomVariable are the chainable counterparts of Functions[…]/Variables[…].

var label = new Label();
label.Expressions
    .AddTypeReference(typeof(Math))                 // Math.Max(1, [Qty]) …
    .AddTypeReference<DateTime>()                   // DateTime.Now.AddDays(3)
    .SetCustomVariable("WERK", "Graz")
    .SetCustomFunction("Kg", args => $"{ExpressionEngine.Num(args[0]):0.0} kg");

label.Add(new TextItem { Expression = "\"Werk \" + WERK + \": \" + Kg([Weight])" });
label.Add(new TextItem { Y = 8, Expression = "Math.Max(1, [Qty]) + \" Stk\"" });
label.Add(new TextItem { Y = 16, Expression = "DateTime.Now.AddDays(3).ToString(\"dd.MM.\")" });
// unregistered types are blocked → FormatException

Item references & localization

Expressions and table cells access the text of other items with [Items.Name] or [Items.Name.Text] (forward references work too; circular references yield ""). Multilingual templates: Label.Strings (via AddString), Label.Culture and {t:key} placeholders; resolution de-CH → de → "" → key; per print job with LabelBinding.WithCulture.

var label = new Label(LabelUnit.Dots, 400, 200)
    .Add(new TextItem { Name = "Total", Expression = "\"Summe: \" + [Items.Price.Text]" })
    .Add(new TextItem { Name = "Price", Y = 50, Expression = "Format(2 * 21, \"0.00\", \"de-DE\")" })
    .Add(new TableItem { Y = 100, ColumnWidths = [200], RowHeights = [30], Cells = [["[Items.Total]"]] });

var l = new Label(LabelUnit.Dots, 400, 200) { Culture = "de-CH" }
    .AddString("", "weight", "Weight")      // Fallback
    .AddString("de", "weight", "Gewicht")   // de-CH → de → "" → key
    .AddString("fr", "weight", "Poids");
l.Add(new TextItem { Text = "{t:weight}: 5 kg" });
string de = l.ToZpl();                                                          // Weight: 5 kg
string fr = l.For<Dictionary<string, object?>>().WithCulture("fr-FR").ToZpl([new()]); // Poids: 5 kg

Cultures & formatting

DataFieldFormat formats with TextItem.CultureName (e.g. "de-DE"; without it: invariant with a format, the current culture without). Every culture-dependent formatting of zplCore – bound fields, number texts, table cells, expressions, clock fields – prints the same on every operating system: dates use the culture's standard calendar from a fixed table (ExpressionEngine.StandardCalendar: ar-SA Umm al-Qura, th Thai Buddhist, Persian for fa, ps, ckb-IR, lrc, mzn, uz-Arab; all others Gregorian), and special spaces such as the narrow no-break space in fr-FR thousands or 2:30 PM become plain spaces. Details: cultures in the expression reference.