<info> <desc> Create your templates manually. </desc> <name>Jim Evins</name> <email>evins@snaught.com</email> <name>Mario Blättermann</name> <email>mariobl@gnome.org</email> <license>

Creative Commons Share Alike 3.0

</license> </info>

This page is a reference guide to manually creating <app>gLabels</app> templates. <app>gLabels</app> templates are defined in simple XML files as described in the DTD: glabels-2.3.dtd (this DTD also describes other XML files used by <app>gLabels</app>).

Manually created template files should be placed in the <file>${HOME}/.glabels</file> and be named with a <file>.template</file> extension.

<app>gLabels</app> searches for templates in several other locations as defined here:

Location | Description
<file>${prefix}/share/libglabels-3.0/templates</file> | Predefined templates distributed with <app>gLabels</app>. <file>${prefix}</file> is usually <file>/usr</file> or <file>/usr/local</file>, depending on where <app>gLabels</app> was installed.
<file>${XDG_CONFIG_HOME}/libglabels/templates</file> | User defined templates created with the <app>gLabels</app> <gui>Template Designer</gui>. Do not put manually created templates in this directory. If <file>${XDG_CONFIG_HOME}</file> is not defined, it defaults to <file>${HOME}/.config</file>.
<file>${HOME}/.glabels</file> | User defined templates that have been created manually should be placed in this directory. Older versions of the <app>gLabels</app> <gui>Template Designer</gui> (prior to 3.0) would also put templates in this directory.

<note>

Completed template files can be sent to the <app>gLabels</app> template mailing list for possible inclusion in future versions of <app>gLabels</app>.

Assumptions/caveats <list> <item>

A sheet contains only one size of label or card (if a sheet contains more than one size of item, it can be split into multiple templates for multiple pass printing)

</item> <item>

Distances can be expressed in units of `pt`, `in`, `mm`, `cm`, or `pc`. For example: "`1.0in`" or "`2.54cm`". If no units are specified, computer points (`pt`) will be assumed (1 pt = 1/72 in = 0.352778 mm).

</item> </list>
Template Files

A template file contains a single `Glabels-templates` top-level node.

`<?xml version="1.0"?> <Glabels-templates> ...templates... </Glabels-templates>`

          Example Template
          <desc>Example <app>gLabels</app> template file containing a single
                Template node.</desc>

    <?xml version="1.0"?>
    <Glabels-templates>

      <Template brand="Avery" part="8160" size="US-Letter" description="Mailing Labels">
        <Meta category="label"/>
        <Meta category="mail"/>
        <Meta product_url="http://www.avery.com/avery/en_us/"/>
        <Label-rectangle id="0" width="189pt" height="72pt" round="5pt">
          <Markup-margin size="5pt"/>
          <Layout nx="3" ny="10" x0="11.25pt" y0="36pt" dx="200pt" dy="72pt"/>
        </Label-rectangle>
      </Template>

    </Glabels-templates>

<span its:translate="no">Template</span> Node

A `Template` node describes a single stationery product. It must contain one instance of any type of Label node (`Label-rectangle`, `Label-round`, or `Label-cd`).

Property | Description
`brand` | Brand or manufacturer of stationery product. E.g. "Avery"
`part` | Part number or name of stationery product. E.g. "8160"
`size` | Size of sheet. E.g., "`US-Letter`", "`A4`", ...
`description` | Description of stationery product. E.g, "Mailing Labels."
`_description` | Translatable description of stationery product. E.g, "Mailing Labels." (Only useful for predefined templates)
`width` | Page width. Only valid if size="Other"
`height` | Page height. Only valid if size="Other"
`equiv` | Equivalent part number. If this property is present, the template is a clone of another template of the same brand. The template will inherit all properties, except brand and name from the other template. This equiv property must refer to a previously defined template - <app>gLabels</app> does not currently support forward references.

<span its:translate="no">Meta</span> Node

A `Meta` node contains some additional information about the template. A `Template` node may contain zero or more `Meta` nodes.

Subnode | Description

`category`

A category for the template. A template can belong to multiple categories by simply adding multiple `Meta` nodes to the parent `Template` node. Template categories are used by the <app>gLabels</app> <gui>New Label Dialog</gui> to filter the results of template searches.

The value of this category must match a predefined category ID defined in the file <file>${prefix}/libglabels-3.0/templates/categories.xml</file>. Currently defined category IDs include:

<list> <item>

`label`

</item> <item>

`round-label`

</item> <item>

`elliptical-label`

</item> <item>

`square-label`

</item> <item>

`rectangle-label`

</item> <item>

`card`

</item> <item>

`business-card`

</item> <item>

`media`

</item> <item>

`mail`

</item> <item>

`foldable`

</item> <item>

`photo`

</item> </list>

`product_url` | A URL pointing to the vendor's webpage for the specific product, if available.

<note>

Suggestions for additional categories can be sent to the <app>gLabels</app> developer's mailing list.

Product URLs may be of limited use, because they may not be permanent.

<span its:translate="no">Label-rectangle</span> Node

A `Label-rectangle` node describes the dimensions of a single label or business card that is rectangular in shape (may have rounded edges).

Property | Description
`id` | Reserved for future use. Should always be 0.
`width` | Width of label/card
`height` | Heigth of label/card
`round` | Radius of corners. For items with square edges (business cards), the radius should be 0.
`x_waste` | Amount of horizontal waste (over-print) to allow. This is useful for minimizing alignment problems when using non-white backgrounds (e.g. images).
`y_waste` | Amount of vertical waste (over-print) to allow. This is useful for minimizing alignment problems when using non-white backgrounds (e.g. images).

<desc>Label-rectangle parameters</desc>

Label-rectangle parameters

<span its:translate="no">Label-ellipse</span> Node

A `Label-ellipse` node describes the dimensions of a single label or business card that is elliptic in shape.

Property | Description
`id` | Reserved for future use. Should always be 0.
`width` | Width of the ellipse
`height` | Heigth of the ellipse
`waste` | Amount of waste (over-print) to allow. This is useful for minimizing alignment problems when using non-white backgrounds (e.g. images).

<desc>Label-ellipse parameters</desc>

Label-ellipse parameters

<span its:translate="no">Label-round</span> Node

A `Label-round` node describes the dimensions of a simple round label (not a CD).

Property | Description
`id` | Reserved for future use. Should always be 0.
`radius` | Radius (1/2 diameter) of label
`waste` | Amount of waste (over-print) to allow. This is useful for minimizing alignment problems when using non-white backgrounds (e.g. images).

<desc>Label-ellipse parameters</desc>

Label-ellipse parameters

<span its:translate="no">Label-cd</span> Node

A `Label-cd` node describes the dimensions of a CD, DVD, or business card CD.

Property | Description
`id` | Reserved for future use. Should always be 0.
`radius` | Outer radius of label
`hole` | Radius of concentric hole
`width` | If present, the label is clipped to the given width. (Useful for "business card CDs").
`height` | If present, the label is clipped to the given height. (Useful for "business card CDs").
`waste` | Amount of waste (over-print) to allow. This is useful for minimizing alignment problems when using non-white backgrounds (e.g. images).

<desc>Label-cd parameters</desc>

CD label parameters

<span its:translate="no">Markup</span> Nodes

Templates may contain optional markup nodes. These nodes are used to describe a simple set of markup lines that are visible in the <app>glabels</app> drawing canvas, but not visible when printed. These lines can represent margins, fold lines, center lines, special areas, or other helpful hints to the user of a template.

<span its:translate="no">Markup-margin</span> Node

A `Markup-margin` describes a margin along all edges of a label.

Property | Description
`size` | Size of the margin. I.e. the distance of the margin line from the edge of the card/label.

<span its:translate="no">Markup-line</span> Node

A `Markup-line` node describes a markup line.

Property | Description
`x1` | x coordinate of 1st endpoint of the line segment.
`y1` | y coordinate of 1st endpoint of the line segment.
`x2` | x coordinate of 2st endpoint of the line segment.
`y2` | y coordinate of 2st endpoint of the line segment.

<span its:translate="no">Markup-circle</span> Node

A `Markup-circle` describes a markup circle.

Property | Description
`x0` | x coordinate of circle origin (center).
`y0` | y coordinate of circle origin (center).
`radius` | Radius of circle.

<span its:translate="no">Markup-rect</span> Node

A `Markup-rect` describes a markup rectangle.

Property | Description
`x1` | x coordinate of upper left corner of rectangle.
`y1` | y coordinate of upper left corner of rectangle.
`w` | Width of rectangle.
`h` | Height of rectangle.
`r` | Radius of rounded corners of rectangle.

<span its:translate="no">Markup-ellipse</span> Node

A `Markup-ellipse` describes a markup ellipse.

Property | Description
`x1` | x coordinate of upper left corner of ellipse.
`y1` | y coordinate of upper left corner of ellipse.
`w` | Width of ellipse.
`h` | Height of ellipse.

<span its:translate="no">Layout</span> Node

A label node may contain multiple `Layout` children. If labels are arranged in a simple grid pattern, only one layout is needed. However, if labels are arranged in multiple grids, such as a running bond pattern, multiple `Layout` tags can be used.

A single label can always be treated as a grid of one.

Property | Description
`nx` | Number of labels/cards across in the grid (horizontal)
`ny` | Number of labels/cards across in the grid (vertical)
`x0` | Distance from left edge of sheet to the left edge of the left column of cards/labels in the layout.
`y0` | Distance from the top edge of sheet to the top edge of the top row of labels/cards in the layout.
`dx` | Horizontal pitch of grid.
`dy` | Vertical pitch of grid.

<desc>Layout parameters</desc>

Layout Parameters