T3 Labels : Label Layouts

• • Next Steps

---

Introduction

Layouts control what will be printed on each label and how it is arranged. \

Things to know:

• Layouts can be static, meaning each label will be exactly the same, dynamic, which means data is inserted into the label from the data list. Most commonly, layouts are a mix of both.
• Layouts are responsive, meaning they will resize to fit the template dimensions. Usually, they'll be designed to fit specific labels.
• Layouts are made up of one or more layout elements.

The entire label layout specification can be viewed here

Examples

Here is an example of a layout with a barcode in the top 75%, and text in the bottom 20%. Both the barcode and the text show a package label:

{
  "labelContentLayoutElements": [
    {
      "elementType": "CODE128_BARCODE",
      "valueTemplate": "{{package.label}}",
      "yStartFraction": 0.25
    },
    {
      "elementType": "TEXT",
      "valueTemplate": "{{package.label}}",
      "yEndFraction": 0.2
    }
  ]
}

Here is this layout renders in a 3x1 label:

Barcode/text layout rendered on 3x1 thermal label

Here is this layout renders in an Avery 8160 label sheet:

Barcode/text layout rendered on Avery 8160

Layout Elements

A layout element is a single element that appears somewhere on a label. Text, images, and barcodes are all examples of layout elements.

Each layout element has a specific "type" that describes how it will appear. Available layout element types:

Text

A TEXT layout element adds a paragraph of text.

Tables

A TABLE element adds multiple pieces of text formatted in rows and columns.

• All text in a table has a consistent font size and spacing.
• Table borders are not displayed by default.
• Tables are defined with HTML.

Images

An IMAGE layout element adds an image file onto the label.

• Images are centered in the layout element and fit to the available space.
• Image data is passed as base64 and accessed via filename (see value templates)

Barcodes

A CODE128_BARCODE layout elements displays a scannable Code128 barcode which encodes a piece of text.

• The barcode will fill the layout element area horizontally and vertically.
• The barcode encodes whatever is passed in the value template.

QR Codes

A QR_CODE layout elements displays a scannable QR barcode which encodes a piece of text.

• QR codes are centered in the layout element and fit to the available space, with padding.
• The QR code encodes whatever is passed in the value template.

Boxes

A BOX element draws a border box around the entire element. It does not use a value template.

Position and Sizing

Layout elements are positioned as rectangles inside the template. The boundaries of the rectangle are specified as percentages of the height and width. This is done to allow for the label to be compatible with any template.

All layout element measurements are defined in width decimal percentages (For example, 0.05 = 5% of the total dimension).

Layout elements use the following values to define size and position:

• xStartFraction
• xEndFraction
• yStartFraction
• yEndFraction

Note: The default start and end percentages fill the entire printable area (0% and 100%, respectively). Note in the previous example, only one fraction is defined for each layout element.

Aspect Ratio Limits

By default, layouts will fill the available template width and height. You can define ma minimum and maximum aspect ratio for the layout, which will limit how much it will "stretch".

Layout elements use the following four values to define size and position:

• minAspectRatio
• maxAspectRatio

Note: If T3 detects a minimum or maximum aspect ratio is reached, it will center the layout inside the template.

Textual Elements

Textual elements (TEXT, TABLE) have options to control how the text appears: size, font, spacing, positioning, etc.

Text Formatting

Textual elements can control font size, font family, and font spacing.

• paragraphFontSize controls the font size. Default is 6.
• paragraphSpacing controls the paragraph spacing. Default is 6. The font size cannot exceed the spacing.
• paragraphFontName controls the font family. Supported fonts:
  • Times-Roman
  • Times-Bold
  • Times-Italic
  • Times-BoldItalic
  • Helvetica
  • Helvetica-Bold
  • Helvetica-Oblique
  • Helvetica-BoldOblique
  • Courier
  • Courier-Bold
  • Courier-Oblique
  • Courier-BoldOblique
  • Symbol
  • ZapfDingbats

Text Alignment

Textual elements can control how text is aligned inside the element boundaries - or in the case of tables, inside each cell.

• horizontalParagraphAlignment controls horizontal alignment: LEFT, CENTER, RIGHT
• verticalParagraphAlignment controls vertical alignment: TOP, CENTER, BOTTOM

Responsive Sizing

Textual elements also allow you specify how the text will behave inside the boundaries of the layout element using paragraphTextResizeStrategy:

• ALLOW_OVERFLOW (default) will display text at its initial font size, even if it overflows the layout element boundaries.
• TRUNCATE_TEXT will preserve the initial font size and remove letters from the end until the remaining text fits inside the element boundaries. An ellipsis (...) will be appended at the end to indicate the text was truncated.
• SHRINK_TEXT will preserve the initial text length, but make the text smaller and smaller until it fits inside the element boundaries.

Note: TRUNCATE_TEXT and SHRINK_TEXT are best-effort, meaning they will only shorten or shrink the text to a certain point before giving up.

Element Values

A value is just the data that appears inside a layout element: paragraph text, table contents, image data, barcode contents. This data is created from a value template.

Value Templates

The value template is used to specify text, html, or images that will appear inside the element. Different element types use the value template differently, and some do not use the value template at all.

Each value template is processed to determine what will appear on each label.

Template Processing

All value templates are processed before being added to the label.

Supports Jinja templates.

• TEXT uses the value template as the source of the text displayed inside the element.
  • Example: Hello, my name is {{ user.name }}
• TABLE uses the value template as the source of the HTML table displayed inside the element. Supports Jinja templates.
  • Example: <table><tr><td>First Name</td><td>{{ Last Name }}</td></tr><tr><td>{{ user.firstName }}</td><td>{{ user.lastName }}</td></tr><table>
• IMAGE uses the processed value
• CODE128_BARCODE uses the entire processed value as the barcode scan value.
• QR_CODE uses the entire processed value as the qr code scan value.

Jinja Templating

---

Next Steps

• Start your free 30-day T3+ trial