https://github.com/chrishanzlik/zplforge
Library for generating and serializing ZPL II code with C#
https://github.com/chrishanzlik/zplforge
csharp labels lib netstandard20 price-tag zebra zpl zpl-to-xml zpl2 zplforge
Last synced: about 2 months ago
JSON representation
Library for generating and serializing ZPL II code with C#
- Host: GitHub
- URL: https://github.com/chrishanzlik/zplforge
- Owner: chrishanzlik
- License: mit
- Created: 2020-11-05T06:21:33.000Z (over 4 years ago)
- Default Branch: master
- Last Pushed: 2023-10-26T15:49:01.000Z (over 1 year ago)
- Last Synced: 2025-04-03T07:04:58.883Z (about 2 months ago)
- Topics: csharp, labels, lib, netstandard20, price-tag, zebra, zpl, zpl-to-xml, zpl2, zplforge
- Language: C#
- Homepage: https://github.com/chrishanzlik/ZPLForge
- Size: 124 KB
- Stars: 18
- Watchers: 2
- Forks: 4
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
| Package | Target framework | NuGet | CI Build |
| ----------------------------- | ----------------- | --------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------- |
| **ZPLForge** | .NET Standard 2.0 | [](https://www.nuget.org/packages/ZPLForge/) |  |
| **ZPLForge.XmlSerialization** | .NET Standard 2.0 | [](https://www.nuget.org/packages/ZPLForge.XmlSerialization/) |  |
##### What is ZPLForge?
The ZPLForge library for people who do not want to deal directly with **ZPL II** or read the
documentation for hours. ZPLForge creates ZPL code in no time with special builders that
guides the user in easy steps.
Another advantage is the XML serialization which comes with the
*ZPLForge.XmlSerialization* package. With this, the label is saved in XML format
in a file or string that is easy to read and adaptable to third parties.
##### What this library is not
This library is not intended to communicate with any kind of devices. Converting bitmaps into GRF
is also not part of ZPLForge's responsibility. The goal is to stay lightweight and free of
dependencies.
##### Which label elements are covered by ZPLForge?
- Text
- Ellipse
- Rectangle
- Barcode (Code39, Code128, EAN8, EAN13, UPC-A, UPC-E)
- QR Code
- Symbol
- Image
- Diagonal Line
*More barcode types will be added in future versions.*
## Label builder
Using the `LabelBuilder` is recommended way to build labels in ZPLForge, because all required properties
on the label (including the childs) will be covered. Additionally this brings some validation.
### Example
This example is printed on a continuous media with a total width of 60 mm on a Zebra ZD420
printer. This printer prints with a resolution of 203 dpi, so I calculated the total width in dots as
follows:
(60 mm / 25.4) * 203 dpi = 480 dots
*Remark: All sizes in ZPLForge are given in dots!*
``` csharp
Label priceLabel = LabelBuilder
.FromCuttedContinuousMedia(480, 200, 0, MediaType.ThermalTransfer)
.SetQuantity(1)
.AdjustDarknessLevel(+12)
.AddText(txt => txt
.At(15, 30)
.SetContent("Sweet Blue Shoes")
.SetFont(Font.Default, 25))
.AddText(txt => txt
.At(15, 60)
.SetContent("The Shoe Manufcaturers")
.SetFont(Font.Default, 20))
.AddSymbol(sym => sym
.At(220, 60)
.SetSymbol(SymbolKind.TradeMark, 10, 10))
.AddCode128Barcode(c128 => c128
.At(100, 105)
.SetHeight(50)
.SetContent("123456789"))
.AddRectangle(rect => rect
.At(310, 20)
.SetDimensions(165, 60)
.SetBorder(LabelColor.Black, 60))
.AddText(txt => txt
.At(310, 35)
.ApplyBlockMode(170, 1, BlockAlignment.Center)
.SetContent("$ 49.99")
.SetFont(Font.S, 20)
.InvertColors())
.AddRectangle(rect => rect
.At(5, 20)
.SetDimensions(470, 170)
.SetBorder(LabelColor.Black, 1))
.Build();
string zpl = priceLabel.ToString();
```
ZPL string generated by the builder above:
``` zpl
^XA^LL200^MNN,0^PW480^MMC^MD12^MTT^PQ1,0,0,N,Y^CI28^PR2,6,2^FO15,30,0^FDSweet Blue Shoes^A0I,25,^FS^FO15,60,0^FDThe Shoe Manufcaturers^A0N,20,^FS^FO220,60,0^GSN,10,10^FDC^FS^FO100,105,0^BY2,3.0,10^BCN,50,Y,N,N^FD123456789^FS^FO310,20,0^GB165,60,60,B,0^FS^FO310,35,0^FR^FD$ 49.99^ASN,20,^FB170,1,0,C^FS^FO5,20,0^GB470,170,1,B,0^FS^XZ
```
The printed label:
### Factory methods
Depending on the medium what is inserted into the printer, choose one of the factory methods below to create a `LabelBuilder` instance:
``` csharp
LabelBuilder.FromWebSensingMedia(int printWidth, PrintMode? printMode = null, MediaType? mediaType = null);
LabelBuilder.FromContinuousMedia(int printWidth, int labelLength, PrintMode? printMode = null, MediaType? mediaType = null);
LabelBuilder.FromCuttedContinuousMedia(int printWidth, int labelLength, int groupCutCount = 0, MediaType? mediaType = null);
LabelBuilder.FromBlackMarkSensingMedia(int printWidth, int blackMarkOffset, PrintMode? printMode = null, MediaType? mediaType = null);
```
### Builder Extensibility
All builders are extendable by common C# extension methods:
``` csharp
public static class BuilderExtensions
{
public static ImageBuilder FromBitmap(this ImageBuilder self, Bitmap bitmap)
{
ImageElement image = (self as IContextAccessor).Context;
image.Content = /* insert bitmap data */;
image.BinaryByteCount = /* insert bitmap data */;
/* ... */
return self;
}
}
```
## Usage without builders
To get full control over the label and to be able to set all properties manually, the
`Label` (including the content elements like `TextElement`) class can be used directly.
This would make it possible to create your own builders.
``` csharp
Label priceLabel = new Label {
Quantity = 1,
PrintWidth = 480,
MediaTracking = MediaTracking.Continuous,
MediaType = MediaType.ThermalTransfer,
PrintMode = PrintMode.Cutter,
MediaDarknessLevel = 12,
Content = {
new TextElement {
PositionX = 15,
PositionY = 15,
Content = "Sweet Blue Shoes",
CharHeight = 25
},
new BarcodeElement {
BarcodeType = BarcodeType.Code128
/* ... */
}
/* ... */
}
};
```
## XML Serialization
### Serialization
To save the information in a human readable format without knowing much about ZPL, take a
look at the `LabelXmlSerializer` class inside the *ZPLForge.XmlSerialization*
package.
``` csharp
using var fileStream = File.Create("priceLabel.xml");
var serializer = new LabelXmlSerializer();
serializer.Serialize(fileStream, priceLabel);
```
This will output the `Label` and its content in easy to read (and editable) XML format:
``` xml
Continuous
480
Cutter
ThermalTransfer
12
15
30
Sweet Blue Shoes
25
215
60
10
10
TradeMark
100
105
123456789
50
```
For serializing default values (disabled by default) set the `serializeDefaults`
parameter on `LabelXmlSerializer` to `true`:
```
serializer.Serialize(fileStream, priceLabel, serializeDefaults: true);
```
### Deserialization
The generated XML file above can be deserialized back into the `Label` object
with the `LabelXmlSerializer` again:
``` csharp
using var fileStream = File.OpenRead("priceLabel.xml");
var serializer = new LabelXmlSerializer();
Label priceLabel = serializer.Deserialize(fileStream);
```