ember-cli-barcode

ember-cli-barcode

A ember-cli addon to render barcodes using the JsBarcode library. See the demo

The addon adds accessibility attributes and elements to the generated barcodes. See the Accessibility section below.

Version Compatibility

ember-cli-barcode is compatible with Ember 2.4 onward and is passing tests for Ember 3.x.

Version 2.x onward no longer requires Bower but you need to add configuration to ember-cli-build.js - thanks @donaldwasserman

After upgrading to 2.x, if jsbarcode was your only Bower dependency you can remove bower.json from your project and delete the bower_components directory. If you have other Bower dependencies, remove the jsbarcode dependency from bower.json

Installation

  $ ember install ember-cli-barcode

By default all barcode types are added to your app. See the build configuration section for slimming your build

Usage

The simplest form to render a barcode is to pass in a value and the default options will be used to generate a CODE128 barcode:

{{bar-code value="abc123456"}}

Which renders:

 

By default, barcodes are rendered using the svg element. The element can be changed to img or canvas using the tagName property:

{{bar-code
  value="A45689"
  tagName="img"}}

{{bar-code
  value="A45689"
  tagName="canvas"}}

Use the img tag if you want the ability to right-click copy or save the displayed barcode.

Options

All JsBarcode's options are supported by the addon. See Barcode Specifications for details on each format. A few examples are below. See the demo application for more.

Change the barcode format by passing the format name into the component. To display a UPC barcode:

  {{bar-code
    value="123456789999"
    format="UPC"}}

 

The color of the barcode or it's background can be changed:

  {{bar-code
    value="abc123456"
    lineColor="red"}}

 

background color changed:

  {{bar-code
    value="abc123456"
    lineColor="#ffffff"
    background="#660033"}}

 

Any valid html or hexadecimal color can be used for the lineColor or background options. The component does not support the Ember component blockform.

If you have many options, pass an object using the options property instead of a large number of individual properties. The options will override any other properties set on the component.

  // app/controllers/application.js
  myOptions: {
    format: "UPC",
    textPosition: "top",
    lineColor: "#ff3399",
  }

  {{!-- app/templates/application.hbs --}}
  {{bar-code
    value="11223344"
    options=myOptions}}

  {{!-- options override other settings --}}
  {{!-- line color will be ##ff3399 --}}
  {{bar-code
    value="11223344"
    options=myOptions
    lineColor="blue"}}

 

Alternatively, you can globally set any option for your application using config/enviroment.js. See Runtime Configuration for details.

EAN13 and UPC

The flat option is supported for both EAN13 and UPC barcodes defaulting to false if not specified Additionally the lastChar option is supported for EAN13 barcodes with a default value of ''.

Invalid Barcode Values

If you pass an invalid value based on the format, the barcode will not render. To capture invalid values assign an action to the vaild property.

// app/templates/application.hbs
// pass invalid code for EAN8 barcodes
{{bar-code format="EAN8"  value="9638" valid=(action 'checkValid')}}

{{if validCode "Valid" "Invalid"}}

// app/controllers/application.js
import Controller from "@ember/controller";

export default Controller.extend({
  validCode: false,

  actions: {
    checkValid(status) {
      this.set("validCode", status);
    }
  }
});

IF you have have multiple barcodes in a template and want to check the validity of each individually, you need a dedicated action and controller property for each barcode.

Accessibility

ember-cli-barcode adds the alt attribute, other attributes or other elements to the barcode image for website accessibly. This Medium post by Carie Fisher discuses the whys of website accessibility.

The default text generated for accessibility is based on the barcode's value:

"Barcode value <value>";

where <value> is the value passed into the component. You can override the text used on an individual component invocation by setting the altText property. You can globally override all components and exclude the value from the text string using runtime configuration. There are additional accessibility options that can be set in runtime configuration.

{{bar-code value="9638A3" altText="Ticket barcode"}}

generates the following alternative attribute text

Ticket barcode 9638A3

Excluding the value

Each element type, img, svg and canvas requires different attributes or additional elements to meet A11Y guidelines. Assuming the component declaration

{{bar-code value="BCD10"}}

the markup generated for each "image" type would be

svg:

<svg xmlns="http://www.w3.org/2000/svg" version="1.1" style="transform: translate(0,0)" aria-labelledby="title">
  ... svg data
  <title>Barcode value BCD10</title>
</svg>

image:

<img  src="data:image/png;base64,iVBORw0KGgoAA6dOLEi..." alt="Barcode value BCD10">

canvas:

<canvas role="img" aria-label="Barcode value BCD10">
   canvas data...
</canvas>

Build Configuration

By default, this addon provides the JsBarcode.all javascript file. If you are looking to slim your build and only need a specific version provided by the upstream package, you can pass the type of file you'd like to include via the include option. If you supply all or a falsy value, the addon will include the default all package.

The example below configures the addon to include only code128 barcodes in the Ember app.

// ember-cli-build.js
const EmberApp = require("ember-cli/lib/broccoli/ember-app");

module.exports = function(defaults) {
  let app = new EmberApp(defaults, {
    "ember-cli-barcode": {
      include: "code128"
    }
  });

  return app.toTree();
};

Supported Options

• all
• codabar
• code128
• code39
• ean-upc
• itf
• msi
• pharmacode.

Runtime Configuration

Barcode options may be configured globally in config/enviroement.js. Global option properties can still be overridden on individual components by setting the property on the components invocation. See the sample configuration setting below.

See JsBarcode's options for the values that may be globally set.

The following accessibility values may also be set in runtime configuration

Value Name	Default	Description
altText	null	Globally sets text portion of the alt text attribute. Can also be set on the component
excludeAltValue	false	Do not include the barcode value in the alt text
ariaHidden	false	Adds the aria-hidden attribute to the image effectively hiding it from screen readers
addTitle	false	Adds the title to img and canvas tags so they will show the text value on hover. svgs use the title element for accessibility so it's added by default, unless you set ariaHidden

// ember-cli-barcode options
ENV["ember-cli-barcode"] = {
  altText: "Ticket", // override accessibility text
  addTitle: true, // add title to each barcode

  // jsbarcode options
  format: "code128",
  mod43: false,
  width: 3,
  height: 200,
  displayValue: false,
  fontOptions: "",
  font: "Arial",
  textAlign: "left",
  textPosition: "top",
  textMargin: 2,
  fontSize: 20,
  background: "#ffffff",
  lineColor: "#000000",
  margin: 10,
  marginTop: 20,
  marginBottom: 30,
  marginLeft: 5,
  marginRight: 13,
  flat: false,
  lastChar: "Q"
};

More

The dummy application allows you to experiment with many of the barcode options. As you select different barcode formats a predefined valid code is selected for rendering. scandit.com has a nice summary of the different barcode formats.

Running

To run the dummy application

• npm install or yarn
• ember serve
• Visit your app at http://localhost:4200.

Tests

• npm install or yarn
• npm test (Runs ember try:each to test your addon against multiple Ember versions)
• ember test
• ember test --server

For more information on using ember-cli, visit https://ember-cli.com/.

License

MIT