Printable Labels

From CollectiveAccess Documentation
Jump to: navigation, search

[Valid for v1.3] For v1.5 or later see this has been replaced with the PDF_Output system

Printable Label Setup

CollectiveAccess can generate printable labels from any search result. You can create label formats by editing two configuration files: label_element_styles.conf and ca_objects_label_layouts.conf.

PDF back-ends: PDFLib vs. Zend_PDF

CA creates label output as PDF files suitable for printing. One of two mechanisms for creating PDFs depending upon your server setup.

  • PDFLib-Lite is a commercial PDF creation library. When combined with the PECL-PDFlib extension, PDFLib-Lite provides the best performance and feature set for creation of PDFs within CA. If you can support PDFLib-lite, you should. However installation may not be possible on shared hosts and other servers where your access is limited. For users of languages requiring Unicode characters there is a significant problem: PDFLib-Lite does not support Unicode! Only the rather expensive full version does. Therefore if you need to output Unicode characters, unless you want to purchase PDFLib you should stick with Zend_PDF.
  • Zend_PDF is a pure-PHP PDF creation library bundled with CA. If PDFLib is not available Zend_PDF will be used instead. Performance is not as good as with PDFLib and certain features - notably rotation of field content- are not currently supported.

CA will automatically detect the presence of PDFLib and use it if available.


CA can generate common barcode formats such as CODE-128 or 2-dimensional QR-Codes on labels. Note that barcode generation requires the presence of the GD library in your PHP installation. Barcode support will not be available if you only have one of the other graphics processing libraries that CA supports such as ImageMagick or GraphicsMagick installed. (You can still use these other libraries for processing of uploaded media; GD simply must be present for the barcode generation library to operate.)

The label_element_styles.conf configuration file

label_element_styles.conf is a simple style sheet defining formatting rules that can be applied to label forms. The file is a list of named styles, each of which includes a set of key-value pairs defining formatting parameters.

title = {
	"font" = "Helvetica",
	"size" = 12px,
	"leading" = 18px

The example style above defines a style called 'title' that will format text it is applied to as 12 pixel-high Helvetica with leading of 18 pixels.

Styles are a time-saving device that allow you to centralize formatting settings in one place and reuse them across label formats. You can always bypass label_element_styles.conf and set formatting values directly in ca_objects_label_layouts.conf if you wish.

The ca_objects_label_layouts.conf configuration file

ca_objects_label_layouts.conf defines the precise measurements of a label form and well as layout of fields on each label and the form as a whole.

Before getting into the details of the configuration syntax, a few terms should be defined:

Label form 
A page format containing one or more printable "sub-forms" or labels. A typical label form is page (US letter, A4, etc.) that contains a number of regularly spaced labels. CA's label system assumes that the sub-forms are regularly spaced in a grid pattern and that all sub-forms on a form are of uniform size and orientation.
Sub-form (aka. "label") 
A defined region on a form containing one or more data fields. The fields may contain text data, barcodes or images.

There will be as many sub-forms/labels as there are items in the result set which you are printing labels for - one label per item. There will be as many label forms/pages as required to print the labels.

The configuration file defines an associative list (aka. "hashes" or key/value lists) for each supported label format, the name of which is a unique descriptor for the form.

An typical format definition looks like this - this example defines a layout for Avery-brand #15163 labels:

avery_15163 = {
	"name" = "Avery-brand 15163 labels",
	"code" = "avery_15163",
	"pageWidth" = 8.5in,
	"pageHeight" = 11in,
	"marginLeft" = 0.25in,
	"marginRight" = 0.125,
	"marginTop" = 0.5in,
	"marginBottom" = 0.4in,
	"horizontalGutter" = 0.125,
	"verticalGutter" = 0.00in,
	"pageElements" = {
		"title" = {
			"type" = text,
			"style" = "pageTitle",
			"width" = 3 in,
			"height" = .5 in,
			"top" = 0.25 in,
			"left" = 0.25 in,
			"default" = "Printed by CollectiveAccess"
		"datetime" = {
			"type" = text,
			"style" = "pageTitle",
			"width" = 1.75 in,
			"height" = 18px,
			"top" = 0.25 in,
			"left" = 6.5in
	"subFormWidth" = 4in,
	"subFormHeight" = 2in,
	"subFormLayout" = {
		"v_admin_idno" = {
			"type" = text,
			"style" = small_label_title_content,
			"width" = 1.875 in,
			"height" = 0.035 in,
			"top" = 0.25 in,
			"left" = 0.05 in,
			"default" = "?"
		"v_admin_idno_barcode" = {
			"type" = barcode,
			"style" = barcode_code128,
			"width" = 1.75 in,
			"height"=  .25 in,
			"top" = 0.28 in,
			"left" = 0.05 in
		"v_title" = {
			"type" = text,
			"style" = small_label_field_content,
			"width" = 1.95 in,
			"height" = 0.3 in,
			"top" = 0.6 in,
			"left" = 0.05 in,
			"default" = "?"
		"v_phys_type" = {
			"type" = text,
			"style" = small_label_field_content,
			"width" = 1.875 in,
			"height" = 0.125 in,
			"top" = 0.9 in,
			"left" = 0.05 in,
			"default" = "?"
		"v_admin_source" = {
			"type" = text,
			"style" = small_label_field_content,
			"width" = 1.875 in,
			"height" = 0.125 in,
			"top" = 1.05 in,
			"left" = 0.05 in,
			"default" = "?"
		"v_primary_representation_small" = {
			"type" = image,
			"width" = 1.75 in,
			"height" = 1.5 in,
			"top" = 0.125 in,
			"left" = 2.125 in,
			"display" = meet
		"v_content_description" = {
			"type" = text,
			"style" = small_label_field_content,
			"width" = 1.95 in,
			"height" = 0.6 in,
			"top" = 1.35 in,
			"left" = 0.05 in,
			"default" = "?"

For each label format the following parameters are defined:

Parameter Description
name Name of label format; is displayed in the label format list in CA
code A unique code for the format; used internally
pageWidth The width of the label form; in other words the width of the printable page containing the labels
pageHeight The height of the label form; in other words the height of the printable page containing the labels
marginLeft The space between the left side of the label form and the start of the area containing printable labels
marginRight The space between the right side of the label form and the start of the area containing printable labels
marginTop The space between the top of the label form and the start of the area containing printable labels
marginBottom The space between the bottom of the label form and the start of the area containing printable labels
horizontalGutter The height of the space between rows of printable labels. CA assumes that the space between labels in a form is uniform throughout
verticalGutter The width of the space between columns of printable labels. CA assumes that the space between labels in a form is uniform throughout
pageElements An associative list of fields to layout on the page form. Page elements exist outside of labels, contain static content (not database content) and are intended for placement of utility information on printed label forms such as date/time of output
subFormWidth The width of each sub-form/label on the label form. CA assumes sub-forms on a label form are of uniform size
subFormHeight The height of each sub-form/label on the label form. CA assumes sub-forms on a label form are of uniform size
subFormLayout An associative list of data fields to layout on each sub-form. The data fields map to a list of supported CA database fields
useBorder Determines if border are drawn around the perimeter of each sub form. If set to 1 borders are drawn; if set to zero no borders are drawn
borderDash Determines length of dashed lines to use for sub form border. Omit of set to zero to draw solid lines

Note that measurements can be expressed in inches, centimeters, millimeters, pixels or points. For the purposes of label format definition, pixels and points are considered equivalent. To specify a measurement's units simply follow the quantity with one of the following unit abbreviations:

Abbreviation Units
in Inches
cm Centimeters
mm Millimeters
px Pixels
p Points

If you omit the units from a measurement pixels/points are assumed.

The pageElements list

Each entry in the pageElements associative list is a unique identifier for the field it represents and an associated list of parameters. Possible parameters are:

Parameter Description Example values
type The type of field text, pagenumber, image, barcode, qrcode
style The name of a style defined in label_element_styles.conf myStyle
width Width of the field; content will be wrapped (if text) or scaled (if image or barcode) to fit 10cm
height Height of the field; content will be clipped (if text) or scaled to fit 2.1in
top Location of top of field as measured relative to the top of the label form 0.75"
left Location of the left of field as measured relative to the left of the label form 10px
default Default content to fill field with if not filled by calling code [EMPTY]
barcode If type is barcode, this specifies the type of barcode to output code39, code128, ean13, postnet
qr_format If type is qrcode, this allows you to embed the actual data in an arbitrary string to, for example, constitute an URL to the object detail page in your Pawtucket instance. The placeholder "^FIELDCONTENT" is replaced by the actual data. "^FIELDCONTENT/"

The following parameters can be defined in a pageElement field or in a style definition in label_element_styles.conf:

Parameter Description Possible values
size Size of type 12
align Alignment of content in field left, center, right
font Name of font to use Only the standard PDF fonts or fonts installed on your system can be used
leading Height of text lines 12px
rotate Rotation in degrees of content of field; only supported when using the PDFLib backend 30
padding Padding around field content 0.125"
border Width of border around field (all 4 sides); border, if specified with a width, is always a solid black line 1px
border-left Width of border around left side of field only 2px
border-right Width of border around right side of field only 2px
border-top Width of border around top of field only 1px
border-bottom Width of border around bottom of field only 1px

The subFormLayout list

The subFormLayout list is an associative list that defines the field layout of a typical sub-form/label. The possible parameters for each subFormLayout field are the same as for pageElements fields with a few additions:

Parameter Description Possible values
fields List of information to display in the pageElement. See the the "Field lists" section below for more information. [, ca_objects.idno] (displays object label + object identifier/accession number)
field_delimiter Text to place between values in the pageElement when displaying multiple fields , (puts commas between values)

Field lists

defining a subFormLayout page element,the "fields" (data items) to display in the fields parameter

Related wikipages

Printable Labels Sharepoint [1]



Personal tools