Overview

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).

Requirements

• 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.
  

Distribution Files

• The code packaged as a gem, file j4l_barcodes-2.x.x.gem
• examples/simple_1d.rb: a sample program (see below)
  
• UserGuide.html (this file)
• License file
  

Installation

GD Library

Ubuntu 10.10 & 11.04

CentOS 5.6

yum install gd

Mac OS X 10.6

 ./bootstrap

 /sw/bin/pathsetup.sh

 /sw/bin/fink selfupdate
 /sw/bin/fink index -f

 /sw/bin/fink install gd2-shlibs

Dependent Gems

gem install ffi gd2-ffij

Mac OS X 10.6 issue

           
vi `rvm gemdir`/gems/ffi-1.?.?/lib/ffi/library.rb

          libnames.each do |libname| ### search this line
            begin

 ### add lines below
              # UGLY HACK BY J4L COMPONENTS
              if libname == '/libgd.2.dylib' then libname = '/sw/lib/libgd.2.dylib' end

Barcodes Gem

unzip j4l_barcodes_ruby-2.?.?.zip
gem install /j4l_barcodes_ruby-2.?.?/j4l_barcodes-2.?.?.gem --local
ruby /j4l_barcodes_ruby-2.?.?/examples/simple_1d.rb

Basic Operation

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 'rubygems'

# Require only the classes that you want to use.
# Class file names follow lowercase convention.
require 'j4l_barcodes/code128'

# Instantiate the desired class
bc = J4lBarcodes::Code128.new

# Set optional parameters
# You will normally want to set a few of them
bc.setX 2
bc.setBarHeight 60

# Create file in this directory
# This is because we want to save the image to a file,
# otherwise we would omit this call.
bc.setFilePath './'

# 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 section.

Usage examples are included using "preformated text" like in this line.

setX()
setN()
setBarHeight()
setCheckCharacter()

setThrowExceptions()
setDrawErrors()

Codabar:
setStartChar()
setStopChar()

Code 39: setI()

EAN / UPC Supplement:
setSuppSeparation()
setSuppHeight()

POSTNET:
setHeightTallBar()
setHeightShortBar()

setQuiteZone()
setTopMargin()
setLeftMargin()
setBgColor()
setBarColor()
putTextOnTop()
setTextFont()
setFontSize()
setRotation()
setImageType()

setFilePath()
getMime()
paint()

Generic Parameters

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.

bc.setX 2

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 ).

bc.setN 2.5

setBarHeight( int )

Height of bars in pixels. Default 50 pixels.

bc.setBarHeight 80

setCheckCharacter( boolean )

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 character).

bc.setCheckCharacter ask_yn == 'Y'

setThrowExceptions( boolean )

bc.setThrowExceptions true

setDrawErrors( boolean )

bc.setDrawErrors true

Symbology Specific Parameters

Codabar :    setStartChar( string ) / setStopChar( string )

Set Codabar start/stop characters. They may be either "A", "B", "C" or "D". Defaut are "A" & "B".

bc.setStartChar 'C'

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 paint() call.
  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 paint() call.

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.

Image Parameters

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.

bc.setTopMargin 20

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.

bc.setLeftMargin 20

setBgColor( string )

Sets the image's background color. It can have two formats :

1. A descriptive name among the predefined ones. They are: WHITE (default), RED, GREEN, BLUE, YELLOW, CYAN, ORANGE, GRAY, BLACK.
   
2. The color's RGB values in a comma-separated string.

bc.setBgColor 'YELLOW'
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.

putTextOnTop()

setTtfPath( string )

bc.setTtfPath '/path/to/fonts/'

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 :

• Use any of the five GD default fonts. Use DEFAULT-1, DEFAULT-2, DEFAULT-3 (default), DEFAULT-4 or DEFAULT-5 values for this.
• Use a True Type font that you have in your system. Then you should specify the font's file path. If the font file is not found, nothing will be done, the previously defined or default font will be used. Unless you called setTtfPath(), you should include the full file path.
  
• Examples:

  bc.setTextFont 'DEFAULT-5'
  bc.setTextFont '/path/to/fonts/arial.ttf'

Note: you can get some royalty-free True Type fonts at http://font.ubuntu.com/ or  http://sourceforge.net/projects/corefonts/

setFontSize( integer )

Sets the text font size. Only works for True Type fonts, not for GD default fonts. Default is 10 pixels.

bc.setFontSize 14

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() ).

bc.setRotation 270

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 generated:

• 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 setImageType() ).
• 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.

Examples:

bc.setImageType 'GIF'
bc.setImageType 'JPEG', 50

Creating the Symbol Image

Related functions

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 browser.

bc.setFilePath './images'

getMime()

# Rails 3 example

class BarcodeController < ApplicationController

   def image

         ...

         send_data bc.paint(code), :type => bc.getMime, :disposition => 'inline'

paint( string code, [string file name] )

Creates and eventually outputs the symbol image.

Parameters:

• 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.
  

Returns:
- 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

• bc.paint '11654321 3101000355'
• Human readable text that will appear below the barcode:  (11)654321 (3101)000355

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

Activation

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.

File names

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.