Barcodes

A QR code with a payment link or a barcode with a serial number changes with every document, so it's merged from the data like a field. The template contains a barcode with a name, its type, size and position; the data supplies only the value to encode. Barcode placeholders are created in code or in the Document Editor, and values can be checked before they reach a barcode.

Barcodes that your code creates and changes without a merge are covered in Charts and Barcodes of Document Processing. The JavaScript API for barcodes in the editor is described in Charts and Barcodes, and image placeholders, which work the same way, in Images. The examples encode the invoice number of the invoice data from Simple Mail Merge.

How Barcode Placeholders Work

A barcode in a document is a BarcodeFrame. MailMerge processes barcodes like merge fields: when the name of a barcode frame is the name of a field in the data, the value is merged into the barcode.

• The template defines the look. The barcode type, size, alignment and position stay as designed; only the encoded text changes.
• Barcodes in merge blocks are merged for each record, for example a serial number in each row of an order.
• Templates are saved in the TX Text Control format or as RTF. Only these formats save barcodes as barcodes; other formats save an image of the barcode.
• BarcodeMerged occurs after a barcode has been merged.

Barcode Types

BarcodeType has 14 one-dimensional and 6 two-dimensional types:

The enumeration lists the characters and lengths that each type accepts: EAN13 encodes 13 digits, for example, and QRCode up to 1270 ASCII characters.

Create a Template With a QR Code Placeholder

The Core engine creates barcodes with the TXBarcodeCore class. The following program inserts a QR code named InvoiceNumber and saves the template:

using System.Drawing;
using TXTextControl;
using TXTextControl.Barcode;
using TXTextControl.DataVisualization;

using (ServerTextControl tx = new ServerTextControl())
{
    tx.Create();

    tx.Selection = new Selection { Text = "Scan to view the invoice:\r\n" };

    TXBarcodeCore qrCode = new TXBarcodeCore();
    qrCode.Create();

    qrCode.BarcodeType = BarcodeType.QRCode;

    // The size of the code is calculated for 12 characters
    qrCode.UpperTextLength = 12;
    qrCode.Text = "INV-0000-000";

    // The name connects the barcode with the data
    BarcodeFrame barcodeFrame = new BarcodeFrame(qrCode)
    {
        Name = "InvoiceNumber",
        Size = new Size(1440, 1440) // 1 inch in twips
    };

    tx.Barcodes.Add(barcodeFrame, -1);

    tx.Save("barcode-template.tx", StreamType.InternalUnicodeFormat);
}

The code works as follows:

• Create initializes the TXBarcodeCore before it's used.
• BarcodeType selects the type, and Text is the value the placeholder shows until it's merged.
• The BarcodeFrame constructor wraps the barcode. Its Name is matched with the data, and its Size in twips is the space the barcode takes in the document.
• ServerTextControl.Barcodes returns the BarcodeCollection, whose Add method inserts the barcode inline at the input position. Other overloads anchor it to a paragraph or place it at a fixed position, as for images.

UpperTextLength matters for merged barcodes. A barcode must not push other text away, so its frame keeps its size and the code inside adapts: with the maximum number of characters, the code fills the frame, and a shorter text gives a smaller code. Set UpperTextLength to the longest value your data contains, and set it before Text.

Merge the Data

Merge the template with the invoice data. The value of InvoiceNumber is encoded in the QR code:

using TXTextControl;
using TXTextControl.DocumentServer;

using (ServerTextControl tx = new ServerTextControl())
{
    tx.Create();
    tx.Load("barcode-template.tx", StreamType.InternalUnicodeFormat);

    using (MailMerge mailMerge = new MailMerge { TextComponent = tx })
    {
        mailMerge.BarcodeMerged += (sender, e) =>
            Console.WriteLine($"Barcode merged: {e.BarcodeFrame.Name}, block: {e.MergeBlockName}");

        mailMerge.MergeJsonData(File.ReadAllText("data.json"));
    }

    tx.Save("invoice-with-qr-code.pdf", StreamType.AdobePDF);
}

BarcodeMergedEventArgs contains the merged BarcodeFrame and, inherited from FrameMergedEventArgs, the data record and the merge block of the barcode. The online demo Merging barcodes merges serial numbers into barcodes of a repeating block.

Check Values Before Merging

Because each barcode type accepts only certain characters and lengths, a value from the data can be invalid for a barcode. Static methods of TXBarcodeCore check a value before it's merged:

using TXTextControl.Barcode;

string invoiceNumber = "INV-2025-001";

if (!TXBarcodeCore.IsTextValid(BarcodeType.QRCode, invoiceNumber, out string errorMessage))
{
    Console.WriteLine($"Invalid value: {errorMessage}");
}

Console.WriteLine($"EAN13 accepts {TXBarcodeCore.GetMinimumTextLength(BarcodeType.EAN13)} to {TXBarcodeCore.GetMaximumTextLength(BarcodeType.EAN13)} characters");

IsTextValid returns false and an error message for an invalid value. GetMinimumTextLength and GetMaximumTextLength return the lengths a type accepts.

Barcode Placeholders in the Document Editor

In the Document Editor, your JavaScript code inserts barcodes with TXTextControl.barcodes.addInline and names them with setName:

TXTextControl.barcodes.addInline(function (barcodeFrame) {
    // The name connects the barcode with the data
    barcodeFrame.setName("InvoiceNumber");
}, function (error) {
    console.log(error.msg);
}, TXTextControl.BarcodeType.QRCode, "INV-0000-000", -1);

Save the template in the TX Text Control format and merge it on the server as above. Charts and Barcodes in the Document Editor section describes the other barcode settings.

Next Steps

• Images: merge image data into named placeholders.
• Merge Blocks: repeat barcodes for each record.
• Template Design: choose the format your templates are stored in.