From 3c1144c8fde4da94e2a65a52fdf2e32de2c2fa47 Mon Sep 17 00:00:00 2001 From: Michael King Date: Wed, 16 Oct 2019 12:06:55 -0400 Subject: [PATCH 1/3] update readme & add contributing doc --- CONTRIBUTING.md | 45 +++++++++++++ README.md | 168 ++++++++++++++++++++++++++++++------------------ 2 files changed, 152 insertions(+), 61 deletions(-) create mode 100644 CONTRIBUTING.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..7e207a8 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,45 @@ +## Contributing + +Check [open issues](https://github.com/bbulpett/zebra-zpl/issues) for things that need work. +Also check any [open pull requests](https://github.com/bbulpett/zebra-zpl/pulls) to make sure any changes you want to make haven't already been made by someone else. + +### Fork & clone the repository + +``` +git clone git@github.com:/zebra-zpl.git +cd img2zpl +git remote add upstream git@github.com:bbulpett/zebra-zpl.git +bundle install +``` + +Then check out a working branch: + +``` +git checkout -b +``` + +### Write tests + +This project uses `rspec`. After writing your tests, you can run tests with the following command: + +`bundle exec rspec` + + +### Write code + +Write your code to make your tests pass. + +### Commit & Push your changes + +Commit and push your changes to your working branch. + +``` +git commit -am 'Add some feature' +git push origin +``` + +### Open a pull request + +Open a pull request against upstream master and your working branch. Give a brief description of what your PR does and explain what the code changes do. + +Thank you! diff --git a/README.md b/README.md index 8dc6984..2b307dc 100644 --- a/README.md +++ b/README.md @@ -1,11 +1,28 @@ -#### This is a gem based on a terrific older gem by Cassio Marques. Although the new printers are mostly compatible with old Eltron (Epl) code, my needs require many of the new Zebra (ZPL) functions. - # Zebra::Zpl -### ToDo: Update documentation with instructions for new features such as font sizing, margins, and text alignment +[![gem](https://img.shields.io/gem/v/zebra-zpl?color=orange)](https://rubygems.org/gems/zebra-zpl) +[![downloads](https://img.shields.io/gem/dt/zebra-zpl?color=brightgreen)](https://rubygems.org/gems/zebra-zpl) Zebra::Zpl offers a Ruby DSL to design and print labels using the ZPL programming language. +## Contents + + - [Installation](#installation) + - [Usage](#usage) + - [Building Labels](#building-labels) + - [Printing Labels](#printing-the-labels) + - [Elements](#available-elements) + - [Text](#text) + - [Barcodes](#barcodes) + - [QR Codes](#qr-codes) + - [Boxes](#boxes) + - [Options](#options) + - [Rotation](#elements-rotation) + - [Justification](#elements-justification) + - [Contributing](#contributing) + - [References](#references) + + ## Installation Add this line to your application's Gemfile: @@ -14,11 +31,11 @@ Add this line to your application's Gemfile: And then execute: - $ bundle + bundle install Or install it yourself as: - $ gem install zebra-zpl + gem install zebra-zpl ## Usage @@ -34,9 +51,15 @@ You create new labels with an instance of the `Zebra::Zpl::Label` class. It acce With a label, you can start adding elements to it: - label = Zebra::Zpl::Label.new :print_speed => 3 - text = Zebra::Zpl::Text.new :data => "Hello, printer!", :position => [100, 100], :font_size => Zebra::Zpl::FontSize::SIZE_2 - label << text +```ruby +label = Zebra::Zpl::Label.new print_speed: 3 +text = Zebra::Zpl::Text.new( + data: "Hello, printer!", + position: [100, 100], + font_size: Zebra::Zpl::FontSize::SIZE_2 +) +label << text +``` You can add as many elements as you want. @@ -44,68 +67,51 @@ You can add as many elements as you want. You need to have your printer visible to CUPS (or shared on the network in Windows). Once your printer is configured and you know its name on CUPS (or the Windows shared printer name), you can send the labels to the printer using a `Zebra::PrintJob` instance. - label = Zebra::Zpl::Label.new( - :width => 200, - :length => 200, - :print_speed => 3 - ) +```ruby +label = Zebra::Zpl::Label.new( + width: 200, + length: 200, + print_speed: 3 +) + +barcode = Zebra::Zpl::Barcode.new( + data: '12345678', + position: [50, 50], + height: 50, + print_human_readable_code: true, + narrow_bar_width: 4, + wide_bar_width: 8, + type: Zebra::Zpl::BarcodeType::CODE_128_AUTO +) - barcode = Zebra::Zpl::Barcode.new( - :data => "12345678", - :position => [50, 50], - :height => 50, - :print_human_readable_code => true, - :narrow_bar_width => 4, - :wide_bar_width => 8, - :type => Zebra::Zpl::BarcodeType::CODE_128_AUTO - ) +label << barcode - label << barcode +print_job = Zebra::PrintJob.new '' - print_job = Zebra::PrintJob.new "" +ip = '' # can use 'localhost', '127.0.0.1', or '0.0.0.0' for local machine - print_job.print label +print_job.print label, ip +``` -This will persist the label contents to a tempfile (using Ruby's tempfile core library) and copy the file to the printer using either `lpr -P -o raw ` (if you're on Mac OSX) or `lp -d -o raw ` (if you're on Linux). All the tempfile creation/path resolution, as well as which command has to be used, are handled by the `PrintJob` class. +This will persist the label contents to a tempfile (using Ruby's tempfile core library) and copy the file to the printer using either `rlpr -H -P -o ` (for Windows systems, see [section](#printing-directly-to-windows-lpd) below) or `lp -h -d -o raw ` (for Unix systems). All the tempfile creation/path resolution, as well as which command has to be used, are handled by the `PrintJob` class. -### Printing to directly to Windows LPD +#### Printing directly to Windows LPD This gem also supports printing directly to shared printer on Windows using LPD. In order to print directly to a LPD on a Windows machine you need two things: - [rlpr](http://manpages.ubuntu.com/manpages/xenial/man1/rlpr.1.html) installed on the (UNIX) system running your app that uses this gem.[1](#fn1) - LPD Print Service and LPR Port Monitor features enabled on the Windows machine.[2](#fn2)

- +

-1. On a distro such as Ubuntu simply do: `sudo apt-get install rlpr` -If using OSX then you will have to manually build it from source and add it to your `$PATH` environment variable. - -2. The printer name that you pass in must correspond with the **shared printer name** on the Windows machine. - -### Printing QR codes - - label = Zebra::Zpl::Label.new( - :width=>350, - :length=>250, - :print_speed=>3 - ) - - qrcode = Zebra::Zpl::Qrcode.new( - :data=>"www.github.com", - :position=>[50,10], - :scale_factor=>3, - :correction_level=>"H" - ) +1. On a distro such as Ubuntu simply do: `sudo apt-get install rlpr` +If using OSX then you will have to manually build it from source and add it to your `$PATH` environment variable. - label << qrcode - - print_job = Zebra::PrintJob.new "your-qr-printer-name-on-cups" - - print_job.print label +2. The printer name that you pass in must correspond with the **shared printer name** on the Windows machine. ### Available elements @@ -154,14 +160,55 @@ The available barcode types are: You can create QR Codes elements to print using instances of the `Zebra::Zpl::Qrcode` class. It accepts the following options: * `position`: An array with the coordinates to place the QR code, in dots. -* `scale factor`: Crucial variable of the QR codes's size. Accepted values: 1-99. -* `error correction level`: Algorithm enables reading damaged QR codes. There are four error correction levels: L - 7% of codewords can be restored, M - 15% can be restored, Q - 25% can be restored, H - 30% can be restored. +* `scale_factor`: Crucial variable of the QR codes's size. Accepted values: 1-99. +* `correction_level`: Algorithm enables reading damaged QR codes. There are four error correction levels: L - 7% of codewords can be restored, M - 15% can be restored, Q - 25% can be restored, H - 30% can be restored. + +##### Printing QR codes + +```ruby +label = Zebra::Zpl::Label.new( + width: 350, + length: 250, + print_speed: 3 +) + +qrcode = Zebra::Zpl::Qrcode.new( + data: 'www.github.com', + position: [50,10], + scale_factor: 3, + correction_level: 'H' +) + +label << qrcode + +print_job = Zebra::PrintJob.new '' + +print_job.print label, '' +``` #### Boxes You can draw boxes in your labels: - box = Zebra::Zpl::Box.new :position => [20, 20], :end_position => [100, 100], :line_thickness => 39 +* `position`: An array with the coordinates to place the QR code, in dots. +* `box_width`: The width of the box in dots +* `box_height`: The height of the box in dots +* `color`: The color if the lines. `B` for black, `W` for white. +* `line_thickness`: The thickness of the border in dots +* `rounding_degree`: The degree which to round the corners. (0-8) + +```ruby +box = Zebra::Zpl::Box.new( + position: [20,20], + box_width: 5, + box_height: 4, + color: 'B', + line_thickness: 3, + rounding_degree: 6 +) +``` + +### Options #### Elements Rotation @@ -181,12 +228,11 @@ There are four ZPL-supported `:Justification` parameters. "LEFT" (left-justified * `Zebra::Zpl::Justification::CENTER` ~ centered * `Zebra::Zpl::Justification::JUSTIFIED` ~ full-width-justifed _(YMMV)_ +### Contributing +See [CONTRIBUTING.md](CONTRIBUTING.md) -## Contributing +## References -1. Fork it -2. Create your feature branch (`git checkout -b my-new-feature`) -3. Commit your changes (`git commit -am 'Add some feature'`) -4. Push to the branch (`git push origin my-new-feature`) -5. Create new Pull Request +###### This is a gem based on a terrific older gem by Cassio Marques. Although the new printers are mostly compatible with old Eltron (Epl) code, our needs require many of the new Zebra (ZPL) functions. +* [Zebra Technologies Corporation, _"ZPL II Programming Guide."_ 2019 PDF](https://www.zebra.com/content/dam/zebra/manuals/printers/common/programming/zpl-zbi2-pm-en.pdf) From 77585d3fc1bc532af28786905fd8c49cec783e23 Mon Sep 17 00:00:00 2001 From: Michael King Date: Wed, 16 Oct 2019 12:09:03 -0400 Subject: [PATCH 2/3] fix header size on readme --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 2b307dc..85823a3 100644 --- a/README.md +++ b/README.md @@ -228,7 +228,7 @@ There are four ZPL-supported `:Justification` parameters. "LEFT" (left-justified * `Zebra::Zpl::Justification::CENTER` ~ centered * `Zebra::Zpl::Justification::JUSTIFIED` ~ full-width-justifed _(YMMV)_ -### Contributing +## Contributing See [CONTRIBUTING.md](CONTRIBUTING.md) From 2c09e6c5d8b4f41029fc386008d738fe1a19de7c Mon Sep 17 00:00:00 2001 From: Michael King Date: Wed, 16 Oct 2019 12:10:00 -0400 Subject: [PATCH 3/3] typo --- CONTRIBUTING.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 7e207a8..08141fc 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -7,7 +7,7 @@ Also check any [open pull requests](https://github.com/bbulpett/zebra-zpl/pulls) ``` git clone git@github.com:/zebra-zpl.git -cd img2zpl +cd zebra-zpl git remote add upstream git@github.com:bbulpett/zebra-zpl.git bundle install ```