digital-link.js
is a JavaScript library for creating, verifying, and representing/transferring GS1 Digital Links in JavaScript frontend and backend applications. It can be used to create UIs for Digital Link creation, as well as a validation step for data storage/processing systems.
This is the library powering the EVRYTHNG GS1 Digital Link Tools project, which allows easy generation and validation of GS1 Digital Links via a UI.
Installation
The library is installed via npm
:
npm i --save digital-link.js
Once installation is completed, include the library using require
(for web applications, a modern bundler such as Webpack or Parcel is recommended):
const { DigitalLink, Utils } = require('digital-link.js');
Usage Examples
Create a DigitalLink
using the setter functions, useful if the UI handles each set of elements separately, or the elements come from different sources/datasets:
const { DigitalLink } = require('digital-link.js');
const dl = DigitalLink();
dl.setDomain('https://dlnkd.tn.gg');
dl.setIdentifier('01', '9780345418913');
dl.setKeyQualifier('21', '43786');
dl.setAttribute('thngId', 'UMwxDXBdUbxgtyRaR2HBrc4r');
Alternatively, create from an object describing individual elements:
const { DigitalLink } = require('digital-link.js');
const dl = DigitalLink({
domain: 'https://dlnkd.tn.gg',
identifier: {
'01': '9780345418913',
},
keyQualifiers: {
'21': '43786',
},
attributes: {
thngId: 'UMwxDXBdUbxgtyRaR2HBrc4r',
},
});
Finally, create from an existing (possibly user input) URI string:
const { DigitalLink } = require('digital-link.js');
const uri = 'https://dlnkd.tn.gg/01/9780345418913/21/43786?thngId=UMwxDXBdUbxgtyRaR2HBrc4r';
const dl = DigitalLink(uri);
Once created, a DigitalLink
can validate itself:
const { DigitalLink } = require('digital-link.js');
const uri = 'https://dlnkd.tn.gg/01/9780345418913';
const dl = DigitalLink(uri);
console.log(`Is this Digital Link valid? ${dl.isValid()}`);
Lastly, it can also generate URI string and JSON string representations as results:
const { DigitalLink } = require('digital-link.js');
const uri = 'https://dlnkd.tn.gg/01/9780345418913';
const dl = DigitalLink(uri);
console.log(dl.toWebUriString());
console.log(dl.toJsonString());
There are also some utility functions available for specific use-cases (see Function Reference below). Also, see the README.md
file for more usage examples.
Function Reference
Creation
A DigitalLink
object can be created using multiple input representations.
DigitalLink(); // Create empty object to be populated with setters
DigitalLink(string); // Create from URI string
DigitalLink(object); // Create from object (see examples)
Once created, all the functions below apply to each instance.
Setters
Use setters to add/change one part of the overall Digital Link object.
.setDomain(domain); // Set the URI domain
.setIdentifier(key, value); // Set the identifier
.setKeyQualifier(key, value); // Set a single key qualifier
.setAttribute(key, value); // Set a single attribute
Getters
Use getters to retrieve one part of the Digital Link object. Useful if the input was a raw URI string.
.getDomain(); // Get the domain
.getIdentifier(); // Get the identifier
.getKeyQualifier(key); // Get a single key qualifier
.getKeyQualifiers(); // Get the list of key qualifiers
.getAttribute(key); // Get a single attribute
.getAttributes(); // Get the list of attributes
Outputs
The outputs of a DigitalLink
object after construction allow easy conversion to multiple output formats, as well as validation with trace details.
.toWebUriString(); // Output a GS1 Digital Link URI string
.toJsonString(); // Output a JSON representation of the DigitalLink that
// can be used to construct a modified version directly
.isValid(); // Outputs true if the URI string is valid.
.getValidationTrace(); // Output an object containing an array of major
// validation steps. Useful for debugging purposes
Utilities
There are a couple of utility functions also available for specific use-cases such as HTML generation and validation of individual rules according to the underlying grammar scheme. First, make sure to import Utils
:
const { DigitalLink, Utils } = require('digital-link.js');
Then, use each utility function directly from the Utils
import:
Utils.Rules // Object of rules available to use with
// the testRule() function
Utils.testRule(rule, value) // Test a single rule from Rules
Utils.generateStatsHtml(uriString) // Generate apglib HTML for stats
Utils.generateTraceHtml(uriString) // Generate apglib HTML for validation
// trace results
Utils.generateResultsHtml(uriString) // Generate apglib HTML for validation
// results details
Updated about a year ago