Labels

Part-DB support the generation and printing of labels for parts, part lots and storage locations. You can use the “Tools -> Label generator” menu entry to create labels or click the label generation link on the part.

You can define label templates by creating Label profiles. This way you can create many similar-looking labels with for many parts.

The content of the labels is defined by the template’s content field. You can use the WYSIWYG editor to create and style the content (or write HTML code). Using the “Label placeholder” menu in the editor, you can insert placeholders for the data of the parts. It will be replaced by the concrete data when the label is generated.

Label placeholders

A placeholder has the format [[PLACEHOLDER]] and will be filled with the concrete data by Part-DB. You can use the “Placeholders” dropdown in the content editor, to automatically insert the placeholders.

Common

Placeholder	Description	Example
[[USERNAME]]	The user name of the currently logged in user	admin
[[USERNAME_FULL]]	The full name of the current user	John Doe (@admin)
[[DATETIME]]	The current date and time in the selected locale	31.12.2017, 18:34:11
[[DATE]]	The current date in the selected locale	31.12.2017
[[TIME]]	The current time in the selected locale	18:34:11
[[INSTALL_NAME]]	The name of the current installation (see $config[‘partdb_title’])	Part-DB
[[INSTANCE_URL]]	The URL of the current installation	https://demo.part-db.de

Parts

Placeholder	Description	Example
[[ID]]	The internal ID of the part	24
[[NAME]]	The name of the part	ATMega328
[[CATEGORY]]	The name of the category (without path)	AVRs
[[CATEGORY_FULL]]	The full path of the category	Aktiv->MCUs->AVRs
[[MANUFACTURER]]	The name of the manufacturer	Atmel
[[MANUFACTURER_FULL]]	The full path of the manufacturer	Halbleiterhersteller->Atmel
[[FOOTPRINT]]	The name of the footprint (without path)	DIP-32
[[FOOTPRINT_FULL]]	The full path of the footprint	Bedrahtet->DIP->DIP-32
[[MASS]]	The mass of the part	123.4 g
[[MPN]]	The manufacturer product number	BC547ACT
[[TAGS]]	The tags of the part	SMD, Tag1
[[M_STATUS]]	The manufacturing status of the part	Active
[[DESCRIPTION]]	The rich text description of the part	NPN
[[DESCRIPTION_T]]	The description as plain text	NPN
[[COMMENT]]	The rich text comment of the part
[[COMMENT_T]]	The comment as plain text
[[LAST_MODIFIED]]	The datetime when the element was last modified	2/26/16, 5:38 PM
[[CREATION_DATE]]	The datetime when the element was created	2/26/16, 5:38 PM

Part lot

Placeholder	Description	Example
[[LOT_ID]]	Part lot ID	123
[[LOT_NAME]]	Part lot name
[[LOT_COMMENT]]	Part lot comment
[[EXPIRATION_DATE]]	Expiration date of the part lot
[[AMOUNT]]	The amount of parts in this lot	12
[[LOCATION]]	The storage location of this part lot	Location A
[[LOCATION_FULL]]	The full path of the storage location	Location -> Location A

Storelocation

Placeholder	Description	Example
[[ID]]	ID of the storage location
[[NAME]]	Name of the storage location	Location A
[[FULL_PATH]]	The full path of the storage location	Location -> Location A
[[PARENT]]	The name of the parent location	Location
[[PARENT_FULL_PATH]]	The full path of the storage location
[[COMMENT]]	The comment of the storage location
[[COMMENT_T]]	The plain text version of the comment
[[LAST_MODIFIED]]	The datetime when the element was last modified	2/26/16, 5:38 PM
[[CREATION_DATE]]	The datetime when the element was created	2/26/16, 5:38 PM

Twig mode

If you select “Twig” in parser mode under advanced settings, you can input a twig template in the lines field (activate source mode). You can use most of the twig tags and filters listed in official documentation.

Twig allows you for much more complex and dynamic label generation. You can use loops, conditions, and functions to create the label content and you can access almost all data Part-DB offers. The label templates are evaluated in a special sandboxed environment, where only certain operations are allowed. Only read access to entities is allowed. However as it circumvents Part-DB normal permission system, the twig mode is only available to users with the “Twig mode” permission.

The following variables are in injected into Twig and can be accessed using {{ variable }} ( or {{ variable.property }}):

Variable name	Description
{{ element }}	The target element, selected in label dialog.
{{ user }}	The current logged in user. Null if you are not logged in
{{ install_title }}	The name of the current Part-DB instance (similar to [[INSTALL_NAME]] placeholder).
{{ page }}	The page number (the nth-element for which the label is generated
{{ last_page }}	The page number of the last element. Equals the number of all pages / element labels
{{ paper_width }}	The width of the label paper in mm
{{ paper_height }}	The height of the label paper in mm

Use the placeholders in twig mode

You can use the placeholders described above in the twig mode on element using the {{ placeholder('PLACEHOLDER', element) }} function or the [[PLACEHOLDER]] filter:

{# The function can be used to get the a single placeholder value of an element, if the placeholder does not exist, null is returned #}
{{ placeholder('[[NAME]]', element) }}

{# The filter can be used to replace all placeholders in a string with the values of the element #}
{{ "[[NAME]]: [[DESCRIPTION]]"|placeholders(element) }}

{# Using the apply environment every placeholder in the apply block will be replaced automatically #}
{% apply placeholders(element) %}
    [[NAME]]: [[DESCRIPTION]]
{% endapply %}

{# If the block contains HTML use placeholders(element)|raw to prevent escaping of the HTML #}
{% apply placeholders(element)|raw %}
    <b>[[NAME]]</b>: [[DESCRIPTION]]
{% endapply %}

Important entity fields in twig mode

In twig mode you have access to many fields of the entity you are generating the label for and their associated entities. Following are some important fields of the entities listed. See the SandboxedTwigFactory service for the full list of allowed class methods.

Please not that the field names might change in the future.

Part

Field name	Description
id	The internal ID of the part
name	The name of the part
category	The category of the part
manufacturer	The manufacturer of the part
footprint	The footprint of the part
mass	The mass of the part
ManufacturerProductNumber	The manufacturer product number of the part
tags	The tags of the part
description	The rich text (markdown) description of the part
comment	The rich text (markdown) comment of the part
lastModified	The datetime object when the part was last modified
creationDate	The datetime object when the part was created
ipn	The internal part number of the part
partUnit	The unit of the part
amountSum	The sum of the amount of all part lots of this part
amountUnknwon	Bool: True if there is at least one part lot with unknown amount
partLots	The part lots of the part
parameters	The parameters of the part
orderdetails	The order details of the part as array of Orderdetails

Part lot

Field name	Description
id	The internal ID of the part lot
name	The name of the part lot
comment	The rich text (markdown) comment of the part lot
expirationDate	The expiration date of the part lot (as Datetime object)
amount	The amount of parts in this lot
storageLocation	The storage location of this part lot
part	The part of this part lot
needsRefill	Bool: True if the part lot needs a refill
expired	Bool: True if the part lot is expired
vendorBarcode	The vendor barcode field of the lot

Structural entities like categories, manufacturers, footprints, and storage locations

Field name	Description
id	The internal ID of the entity
name	The name of the entity
comment	The rich text (markdown) comment of the entity
parent	The parent entity of the entity
children	The children entities of the entity
lastModified	The datetime object when the entity was last modified
creationDate	The datetime object when the entity was created
level	The level of the entity in the hierarchy
fullPath	The full path of the entity (you can pass the delimiter as parameter)
pathArray	The path of the entity as array of strings

Orderdetails

Field name	Description
id	The internal ID of the order detail
part	The part of the order detail
supplier	The supplier/distributor of the order detail
obsolete	Bool: True if the order detail is obsolete
pricedetails	The price details of the order detail as array of Pricedetails

Pricedetails

Field name	Description
id	The internal ID of the price detail
price	The price of the price detail
currency	The currency of the price detail
currencyIsoCode	The ISO code of the used currency
pricePerUnit	The price per unit of the price detail
priceRelatedQuantity	The related quantity of the price detail
minDiscountQuantity	The minimum discount quantity of the price detail

User

Field name	Description
id	The internal ID of the user
username	The username of the user
email	The email of the user
fullName	The full name of the user
lastName	The last name of the user
firstName	The first name of the user
department	The department of the user

Part-DB specific twig functions and filters

Part-DB offers some custom twig functions and filters, which can be used in the twig mode and ease the rendering of certain data:

Functions

Function name	Description
placeholder(placeholder, element)	Get the value of a placeholder of an element
entity_type(element)	Get the type of an entity as string
entity_url(element, type)	Get the URL to a specific entity type page (e.g. info, edit, etc.)
barcode_svg(content, type)	Generate a barcode SVG from the content and type (e.g. QRCODE, CODE128 etc.). A svg string is returned, which you need to data uri encode to inline it.

Filters

Filter name	Description
format_bytes	Format a byte count to a human readable string
format_money(price, currency)	Format a price to a human readable string with the currency
format_amount(amount, unit)	Format an amount to a human readable string with the unit object
format_si(value, unit_str)	Format a value using SI prefixes and the given unit string
placeholders(element)	Replace all placeholders in a string with the values of the element

Use custom fonts for PDF labels

You can use your own fonts for label generation. To do this, put the TTF files of the fonts you want to use into the assets/fonts/dompdf folder. The filename will be used as name for the font family, and you can use a _bold (or _b), _italic (or _i) or _bold_italic (or _bi) suffix to define different styles of the font. So for example, if you copy the file myfont.ttf and myfont_bold.ttf into the assets/fonts/dompdf folder, you can use the font family myfont with regular and bold style. Afterward regenerate cache with php bin/console cache:clear, so the new fonts will be available for label generation.

The fonts will not be available from the UI directly, you have to use it in the HTML directly either by defining a style="font-family: 'myfont';" attribute on the HTML element or by using a CSS class. You can define the font globally for the label, by adding following statement to the “Additional styles (CSS)” option in the label generator settings:

* {
    font-family: 'myfont';
}

Non-latin characters in PDF labels

The default used font (DejaVu) does not support all characters. Especially characters from non-latin languages like Chinese, Japanese, Korean, Arabic, Hebrew, Cyrillic, etc. are not supported. For this, we use Unifont as fallback font. This font supports all (or most) Unicode characters but is not as beautiful as DejaVu.

If you want to use a different (more beautiful) font, you can use the custom fonts feature. There is the Noto font family from Google, which supports a lot of languages and is available in different styles (regular, bold, italic, bold-italic). For example, you can use Noto CJK for more beautiful Chinese, Japanese, and Korean characters.