Barcodes Syntax and Properties Leave feedback

Note

The examples read the shop data described in The Business Layer.

You can insert barcode images to your documents dynamically using barcode tags. To declare a dynamically inserted barcode image within your template, perform the following steps:

1. Add a textbox to your template at the place where you want a barcode image to be inserted.
2. Set common image attributes such as size, rotation angle, and others for the textbox, making the textbox look like a barcode image without bars and text.
3. Specify a barcode tag within the textbox using the following syntax:

<<barcode [barcode_expression] -barcode_type>>

During run-time, an expression declared within a barcode tag is evaluated, its value is encoded using the specified barcode type, and the tag’s containing textbox is filled with a corresponding barcode image. The tag itself is removed from the textbox then.

The following template puts the customer’s code into a CODE 128 barcode and the shop’s web address into a QR code, then adds a barcode for each of the customer’s orders. A barcode tag works inside a data band like any other tag: each order gets its own textbox and barcode.

<<[customer.CustomerName]>>
Customer code, CODE 128:
[textbox] <<barcode [customer.Barcode] -code128>>
Web site, QR code:
[textbox] <<barcode ["https://harborlane.example/"] -qr>>
Orders
<<foreach [o in customer.Order]>>Order <<[o.OrderNumber]>>: <<[o.Product.ProductName]>>
[textbox] <<barcode [o.Barcode] -code128>>
<</foreach>>

import json

from groupdocs.assembly import DataSourceInfo, DocumentAssembler

with open("customer.json", encoding="utf-8") as f:
    customer = json.load(f)

assembler = DocumentAssembler()
assembler.assemble_document("customer-barcodes.docx", "customer-barcodes-report.docx", DataSourceInfo(customer, "customer"))

Binary file (DOCX, 17 KB)

To specify a barcode type within a barcode tag, you can use one of the predefined identifiers described in the following table:

You can scale barcode symbols of dynamically inserted barcode images specifying the scale attribute for a barcode tag as follows.

<<barcode [barcode_expression] -barcode_type scale="scaling_hint">>

A scale attribute affects the width and height of a 2D barcode symbol and the width of a 1D barcode symbol. The value of a scale attribute represents the percent of barcode symbol scaling.

The value of a scale attribute, however, is just a hint. That is, actual scaling of a barcode symbol can be not precisely equal to the specified one. The reason is that scaling can damage a barcode symbol in a way it to become unreadable by barcode scanners. That is why, the engine calculates actual scaling not to bring such a damage trying to be as close to the specified scaling as possible at the same time.

A symbol scaled up needs a textbox large enough for it: the engine cuts the image at the textbox’s edge.

You can affect initial scaling of all barcode symbols generated by a single DocumentAssembler instance through the DocumentAssembler.barcode_settings.base_x_dimension and DocumentAssembler.barcode_settings.base_y_dimension properties. These properties define the smallest width and height of the unit of barcode modules respectively. That is, for example, to make all barcode symbols twice larger by default, you can use the following code. A larger symbol needs a larger textbox, so the template of this example gives its CODE 128 barcode a textbox 440 points wide and its QR code one of 200 by 200 points:

Customer code, CODE 128:
[textbox] <<barcode [customer.Barcode] -code128>>
Web site, QR code:
[textbox] <<barcode ["https://harborlane.example/"] -qr>>

import json

from groupdocs.assembly import DataSourceInfo, DocumentAssembler

with open("customer.json", encoding="utf-8") as f:
    customer = json.load(f)

assembler = DocumentAssembler()
assembler.barcode_settings.base_x_dimension *= 2
assembler.barcode_settings.base_y_dimension *= 2
assembler.assemble_document("barcode-base-size.docx", "barcode-base-size-report.docx", DataSourceInfo(customer, "customer"))

Binary file (DOCX, 13 KB)

Values of the base_x_dimension and base_y_dimension properties are measured in units defined by the DocumentAssembler.barcode_settings.graphics_unit property. By default, they are 0.6 and 2, and graphics_unit is GraphicsUnit.MILLIMETER (from groupdocs.assembly import GraphicsUnit).

Warning

When the scale attribute is provided for a barcode tag, actual x- and y-dimensions are calculated by the engine as the corresponding percent of base x- and y-dimensions.

The height of a 1D barcode symbol is not affected by the scale attribute of the corresponding barcode tag. However, you can set the height applying the barHeight attribute as follows:

<<barcode [barcode_expression] -barcode_type barHeight="height">>

The value of a barHeight attribute specifies the percent of the overall barcode image height. That is, for example, to set the height of a barcode symbol equal to two thirds of its overall barcode image height, you can use the following barcode tag:

<<barcode ["736192"] -codabar barHeight="67">>

The following template shows the customer’s code three times: at the default size, scaled to 200% in a textbox twice as wide, and with bars a third of the image high.

Default size:
[textbox] <<barcode [customer.Barcode] -code128>>
Scaled to 200%:
[textbox] <<barcode [customer.Barcode] -code128 scale="200">>
Bars a third of the image height:
[textbox] <<barcode [customer.Barcode] -code128 barHeight="33">>

import json

from groupdocs.assembly import DataSourceInfo, DocumentAssembler

with open("customer.json", encoding="utf-8") as f:
    customer = json.load(f)

assembler = DocumentAssembler()
assembler.assemble_document("barcode-sizes.docx", "barcode-sizes-report.docx", DataSourceInfo(customer, "customer"))

Binary file (DOCX, 13 KB)

The fore color of a dynamically inserted barcode image is used to render the barcode’s symbol and text. This color is derived from the font of the corresponding barcode tag. The background color of the image is derived from the solid fill of the textbox containing the tag.

The font used to render barcode text of a dynamically inserted barcode image derives the following attributes from the font of the corresponding barcode tag:

• Name
• Size
• Style (bold and italic)
• Color

The placement of barcode text of a dynamically inserted barcode image – leftward, rightward, or centered – is defined by text alignment of the corresponding barcode tag.

For a dynamically inserted barcode image, the engine automatically corrects barcode text that does not conform the barcode’s specification, if possible. For example, it replaces the wrong check digit of an EAN-13 text with the right one.

Warning

The auto-correction is not possible for barcodes of some types like Databar.

To disable the auto-correction making the engine throw an exception in case of an invalid barcode text, you can set the DocumentAssembler.barcode_settings.use_auto_correction property to False. The exception reaches Python as a RuntimeError. With the auto-correction disabled, an EAN-13 barcode takes the 12 digits of the number without its check digit, which the engine computes: the following example fails on a 13-digit text and succeeds on the 12 digits. The template holds one tag:

<<[product.ProductName]>>, EAN-13:
[textbox] <<barcode [product.Ean] -ean13>>

from groupdocs.assembly import DataSourceInfo, DocumentAssembler

assembler = DocumentAssembler()
assembler.barcode_settings.use_auto_correction = False

for ean in ("5012345678901", "501234567890"):
    product = {"ProductName": "Chestnut honey", "Ean": ean}
    try:
        assembler.assemble_document("product-ean.docx", "product-ean-report.docx", DataSourceInfo(product, "product"))
        print(ean, "assembled")
    except RuntimeError as e:
        print(ean, "rejected:", str(e).splitlines()[0])

Binary file (DOCX, 10 KB)

You can set horizontal and vertical resolution for dynamically inserted barcode images in DPI (dots per inch) using the DocumentAssembler.barcode_settings.resolution property. That is, for example, to set both horizontal and vertical resolution to 300 DPI, you can use the following code:

import json

from groupdocs.assembly import DataSourceInfo, DocumentAssembler

with open("customer.json", encoding="utf-8") as f:
    customer = json.load(f)

assembler = DocumentAssembler()
assembler.barcode_settings.resolution = 300
assembler.assemble_document("customer-barcodes.docx", "customer-barcodes-300-dpi.docx", DataSourceInfo(customer, "customer"))

Binary file (DOCX, 30 KB)

Warning

By default, horizontal and vertical resolution of dynamically inserted barcode images is 96 DPI. The xresolution and yresolution properties set each of them separately.

<<barcode ["736192"] -codabar>>

The template of the following example holds this tag in a textbox. It reads no data, but assemble_document takes at least one data source, so the example passes the customer.

import json

from groupdocs.assembly import DataSourceInfo, DocumentAssembler

with open("customer.json", encoding="utf-8") as f:
    customer = json.load(f)

assembler = DocumentAssembler()
assembler.assemble_document("barcode.docx", "barcode-report.docx", DataSourceInfo(customer, "customer"))

Binary file (DOCX, 12 KB)