J4L Barcodes 1D for Ruby is a software package that allows you to
create bar codes of virtually any type ("symbology" or system)
used nowadays for a variety of uses.
Some of its main features are:
- You have control over many relevant parameters in order to
customize the resulting bar code image to your particular needs
- You can specify the width and height of the bars, the
relation between different bars (narrow / wide bars) and the
"quite zone" (margins).
- You can specify the background color, the color of the
bars and the text color.
- You can use any True Type font for the printed text, and
specify its size, and put it at the bottom (default) or on
the top of the bars.
- You can rotate the image 90,180 or 270 degrees.
- The resulting image can be sent directly to the browser
or to a file, in several formats (PNG, JPEG, GIF, WBMP, that
is, those provided by the GD library).
- The program can calculate checksum characters if you
don't provide them.
- You can easily modify the source code to adapt your
application needs or to add a new bar code type. (Of course you
can count on us to do it, in most cases that will be more
cost-effective for you).
It also uses a few other ruby gems, see installation below.
- Ruby 1.8 or 1.9 ( tested with
1.8.7 and 1.9.2 )
- GD library. Chances are
that you already have it installed on your system. If not, it's
straightforward in most cases, see installation below.
- Optional: Some True Type font if
you don't like the default provided by GD.
Note on GD: If for some reason you prefer to use a different graphic
ImageMagick, or another different output format, e.g. SVG, please
let us know as we might include it in the next release.
Inside the ZIP distribution file you will find:
- The code packaged as a gem, file
- examples/simple_1d.rb: a sample
program (see below)
- UserGuide.html (this file)
- License file
If you don't have it already, here you have installation
instructions on some systems. Please
let us know if you have any trouble installing GD on your system.
Ubuntu 10.10 & 11.04
It's alreay installed by default
yum install gd
Mac OS X 10.6
worked for us, but if you know an easier way please tell us!.
First install Fink from
(takes a long
/sw/bin/fink index -f
/sw/bin/fink install gd2-shlibs
(takes a long time)
The software is provided as a Ruby gem with name
"j4l_barcodes" and depends on two other gems (wrappers for GD):
"ffi" and "gd2-ffij". Just install them:
gem install ffi gd2-ffij
Mac OS X 10.6 issue
If you used
Fink to install GD2 (see above), you will probably need to fix the
dependent gem "ffi" so it finds the library installed by Fink.
vi `rvm gemdir`/gems/ffi-1.?.?/lib/ffi/library.rb
libnames.each do |libname| ### search this line
### add lines below
# UGLY HACK BY J4L COMPONENTS
if libname == '/libgd.2.dylib' then libname = '/sw/lib/libgd.2.dylib' end
This should create a sample barcode in a a file with name
gem install /j4l_barcodes_ruby-2.?.?/j4l_barcodes-2.?.?.gem --local
Generating your first bar code.
We copy below the source code of simple_1d.rb that you just
exectuted. We hope it's self-explanatory :-)
# J4L Barcodes 1D for Ruby. Minimal sample file.
# There's a class for each barcode symbology. Class names:
# Codabar, Code11, Code128, Code39, Code39ext, Code93, Code93ext, Ean13, Ean8,
# Gs1128, Industrial25, Interleaved25, Matrix25, Msi, Postnet, Upca, Upce
# Require only the classes that you want to use.
# Class file names follow lowercase convention.
# Instantiate the desired class
bc = J4lBarcodes::Code128.new
# Set optional parameters
# You will normally want to set a few of them
# Create file in this directory
# This is because we want to save the image to a file,
# otherwise we would omit this call.
# Generate image & save with such file name
bc.paint 'This is a Code 128 sample', 'simple_1d.png'
Public Interface Overview
The public methods useful for normal operation of the software
are listed below, grouped by section. Each section explains the
use of the related methods, click on the section title to go to a
Usage examples are included using "preformated text" like in this line.
Symbology specific parameters
Code 39: setI()
EAN / UPC Supplement:
Creating the symbol image
setX( int )
Sets the width in pixels of a narrow bar (smallest type of bar to
represent a byte). Most barcode types use a narrow bar to
represent a bit value, for instance "0", and a wide bar to
represent the other one, for instance "1". Default 1 pixel.
setN( float )
Sets the size relation between a narrow and a wide bar. This is a
multiplication of N. The final wide bar size will be obtained as X
* N. Default 2 ( wide bar is double than narrow bar ).
setBarHeight( int )
Height of bars in pixels. Default 50 pixels.
Determines if the check character will be automatically
calculated and added to the the bar code. Otherwise the
program assumes that it will be eventually provided by your
application. Default : true (J4L Barcodes 1D will add the check
bc.setCheckCharacter ask_yn == 'Y'
setThrowExceptions( boolean )
Sets the behaviour in case of errors. If true an exception will be
thrown, therefore your application should handle it. Otherwise the
error text is drawn on the barcode image itself. Default is true.
setDrawErrors( boolean )
This is the opposite of setThrowExceptions(), they are mutually
exclusive, see above. Default is false
Codabar : setStartChar( string ) / setStopChar(
Set Codabar start/stop characters. They may be either "A", "B",
"C" or "D". Defaut are "A" & "B".
Code 39: setI( int )
Space between 2 characters. Multiplicator of X. Default 1.
EAN / UPC Supplement
- You can add a supplement to EAN & UPC barcodes. You can
specify it in three manners :
- Appending it to the code parameter, using a dash as
separator. Example: 12345678-90 (90 would be the supplement).
- Calling the EAN/UPC specific method paintWithSupp().
Example : bc.paintWithSupp '12345678' '90'
- Calling to the setSuplement() prior to the paint() call.
Example : bc.setSupplement '90'; bc.paint '12345678'
- The supplement digits can also be automatically extracted from
the code (each barcode type takes them from different
positions). To use this -let's call it automatic mode-, you must
call the setSupp2Flag() or setSupp5Flag() methods, prior to the
Example : bc.setSupp2Flag true; bc.paint '12345678'
(will print "34" as supplement for EAN-8 )
- Note that if you "manually" specify the supplement digits in
any of the three forms explained at the first paragraph above,
the "automatic mode" will be overridden for this specific
setSuppSeparation( int )
Sets the separation in pixels between the supplement and the
barcode. Default is 5.
setSuppHeight( float )
Sets the supplement height. This is a multiplicator of the bar
code height. Default is 0.8 (80%).
POSTNET : setHeightTallBar( int ) / setHeightShortBar( int )
They set the height in pixels of the tall & short bar POSTNET
uses. If you don't call to setHeightTallBar() the generic value
set by setBarHeight() -or its default- will be used.
If you don't call to setHeightShortBar(), a default value of half
of the tall bar will be used.
setQuiteZone( int )
Sets the margin in pixels of the four sides around the graphic.
You can also use setTopMargin() & setLeftMargin() instead.
setTopMargin( int )
Sets the vertical margin or empty space between the image's
border and the start of the bars. The bottom margin is se to the
same size. Default is 10 pixels.
setLeftMargin( int )
Sets the horizontal margin or empty space between the image's
border and the start of the bars. The right margin is set to the
same size. Default is 10 pixels.
setBgColor( string )
Sets the image's background color. It can have two formats :
- A descriptive name among the predefined ones. They are: WHITE
(default), RED, GREEN, BLUE, YELLOW, CYAN, ORANGE, GRAY, BLACK.
- The color's RGB values in a comma-separated string.
bc.setBgColor '255,128,255' # rose
setBarColor( string )
Sets the color of the bars. Same format that setBgColor().
Default is BLACK.
setFontColor( string )
Sets the color of the text below the bars. Same format that
setBgColor(). Default is BLACK.
When the image includes the "human readable interpretation", this
is, the content of the code as normal text, by default it is placed
below the bars. By calling putTextOnTop() you can place it above.
setTtfPath( string )
If you want to use True Type fonts to draw the text of the barcode
(the "human readable interpretation"), you can set a directory where
the font files are located. This is optional, only if you want to
use only the file name or relative path in setTextFont() (see
setTextFont( string )
Sets the Font in which the code text below the bars intended for
human reading of the code. You can specify in two ways :
Note: you can get some royalty-free True Type fonts at http://font.ubuntu.com/
setFontSize( integer )
Sets the text font size. Only works for True Type fonts, not for
GD default fonts. Default is 10 pixels.
setRotation( integer )
Sets the rotation of the barcode. Acceptable values are :
- 0 normal (default)
- 90 ( vertical, bars drawn from bottom to top )
- 180 ( inverted )
- 270 ( vertical, bars drawn from top to bottom )
Note : Default fonts only allow 90 degrees rotation. To allow 180
or 270 use a True Type font ( see setTextFont() ).
setImageType( string [, int ] )
Sets the image type in which the graphic will be generated.
Second parameter is the quality (%). It’s optional and should be
used only for JPEG.
There are four possible image formats in which the barcode can be
- PNG: default and recommended format
- JPEG: note that image size will be much higher. You can reduce
it reducing image quality ( second optional parameter in
- GIF: note that it was removed from some GD versions so maybe
it's not available in your system.
- WBMP: note that this is a
wireless format so it won’t show on most browsers.
bc.setImageType 'JPEG', 50
Creating the Symbol Image
setFilePath( string )
Sets the file path where the image files will be created. After
calling to this function, subsequent calls to paint() will create
a file instead of sending the image to the browser. If not called
it will directly output the image e.g. for direct rendering in
Returns the contents of the Content-Type HTTP
header, e.g. "image/png". Useful when the image is to be directly
provided by the script, this is, not saved as a file, which is the
default behaviour when there's no call to setFilePath().
# Rails 3 example
class BarcodeController < ApplicationController
send_data bc.paint(code), :type => bc.getMime, :disposition => 'inline'
paint( string code, [string file name] )
Creates and eventually outputs the symbol image.
- code: data string to be encoded.
- file name: if you call setFilePath() before paint(), you can
include here a name for the file to be generated. Otherwise a
name will be assigned automatically.
- The file name in which the image has been stored (if output is
sent to a file).
- An empty string if the image was sent to the browser.
GS1-128 specific behaviour
Use a space as field separator. Don't include the parentheses (),
they will be included automatically in the human readable text.
Example with two fields:
- bc.paint '11654321 3101000355'
- Human readable text that will appear below the barcode:
Output to browser
By default, if you don't call to setFilePath(), the paint()
method will directly output the image to the browser. In this mode
you will usually generate only one image at a time and you will
need to set the Content-Type HTTP header -see getMime() above-.
Output to file
Barcode images can be stored into
files. To do so you must first call setFilePath() in order to
specify a base directory in your file system where the generated
files will be stored. Please end it with a slash ("/"). If you
want to use the current directory use "./" as path. Note that this
call is mandatory as it also works as an indicator that you want
the output to a file.
You have two options for the file
name the generated image will have: You can pass the file name
that you wish as a second optional parameter to the paint()
method, or, if you omit it the program will create one.
Multiple file generation
When you send the output to a
file, you can easily create many barcode images in one program
call. Just call to the paint() method as many times as you wish.