@parcellab/js-plugin

parcelLab Javascript Plugin

Integrate parcelLab to your shop frontend (or any webpage). This plugin will fetch and display all important information of a given tracking and turn any webpage to a delivery status page.

Integrate delivery status page

Adding to your webpage

Just place the following snippet into the container you want the plugin to be rendered.

<div id="pl-trace"></div>

<script  type="text/javascript">
  (function (prcl) {/* Load parcelLab assets ... */
    if (window.ParcelLab) {return prcl();}function a() {var styles = document.createElement('link'); styles.rel = 'stylesheet'; styles.href = 'https://cdn.parcellab.com/css/v3/parcelLab.min.css'; document.getElementsByTagName('head')[0].appendChild(styles); }function b(cb) { var script = document.createElement('script'); script.async = true; script.src = 'https://cdn.parcellab.com/js/v3/parcelLab.min.js'; (document.getElementsByTagName('head')[0] || document.getElementsByTagName('body')[0]).appendChild(script); script.onload = cb; } a(); b(prcl);
  })(function () {/* ... plugin is ready to use: */
    var options = {};
    var pl = new ParcelLab('#pl-trace', options);
    pl.initialize();
    window._prcl = pl;
  });
</script>

This snippet will load the needed assets and render the parcelLab plugin into the div with the id "#pl-trace". If you want the plugin to be rendered to an other DOM node you just have to change the id in the snippet. Further you can customize the plugin by extending the options object (see below).

WARNING

If your webpage does not allow post hoc insertion of assets (scripts and stylesheets), you have to add the assets manually in the <header> part of your webpage.
A recent version of these scripts is always available at the parcelLab CDN:

• <link href="https://cdn.parcellab.com/css/v3/parcelLab.min.css" rel="stylesheet">
• <script src="https://cdn.parcellab.com/js/v3/parcelLab.min.js" charset="utf-8"></script>

Options

You can define options by passing an Object as second argument, when creating a new ParcelLab Object.

  <script type="text/javascript">
    ...
    var options = { rerouteButton: 'left', show_searchForm: 'true' };
    var parcelLab = new ParcelLab('#pl-trace', options);
    parcelLab.initialize();
    ...
  </script>

These are the available options:

• styles : Boolean (false will disable the default css for custom styling)
• customStyles : Object (see below)
• rerouteButton : 'left' | 'right' - default is 'right' (defines where to render the reroute button if possible)
• show_searchForm : Boolean (activates a search form, which will be rendered if tracking was not found or no trackingNo/orderNo was given, needs userId)
• show_zipCodeInput : Boolean (activates the zip code field for the search form)
• userId : String (alternative way to pass userId - instead of in url)
• trackingNo : String (alternative way to pass trackingNo - instead of in url)
• orderNo : String (alternative way to pass orderNo - instead of in url)
• zip : String (alternative way to pass zip - instead of in url)
• courier : String (alternative way to pass courier - instead of in url)
• client : String (alternative way to pass courier - instead of in url)
• selectedTrackingNo : String (alternative way to pass selectedTrackingNo - instead of in url)
• show_note : String (renders a note box on top - useful for showing important information)
• onRendered : Function (the plugin will run this function whenever it (re)renders)
• icon_theme : 'xmas' | 'easter' (activates the themed icons 🎄/🐰)
• customTranslations: Object (see below)

All options can also be set via URL search query.
Just drop the '#' from hex colors and/or encode as URI component if needed.
www.yourshop.com/tracking/page/path?trackingNo=xyz&courier=dhl-germany

Banner

The script can render an image banner link on the right, with these option parameters:

• banner_image : String (url of image or 'instagram' for your latest instagram posting)
• banner_link : String (url of link destination)

banner_link is optional if banner_image is 'instagram' where it defaults to your instagram page.

For a custom banner_image we recommend PNG or JPG with a ratio of 0.7 : 1, but any other format can be chosen as well. A recommended solution is 700 x 1000 px for optimal rendering on retina screens, with texts being at least 16px high.

⚠ instagram banners are not enabled by default. ask our support if you want this feature.

⚠ instagram banners require the u parameter with your userId to be present

Custom styling

You can customize the buttons and the boxes of the plugin by simply passing the Object 'customStyles' in the options.
Possible customStyle options:

options.customStyles = {
  borderColor: '#eeeeee', // sets border color for the boxes (default: #eeeeee)
  borderRadius: '4px', // sets the border radius for the boxes and buttons (default: 4px)
  buttonColor: '#333', // sets text color for buttons (default: #333)
  buttonBackground: '#e6e6e6', // sets background color for buttons (default: #e6e6e6)
  iconColor: '#000', // sets color for the status icons (default: #000)
  tabIconColor: '#000', // sets color for the order tab icons (default: buttonColor #333)
  activeTabIconColor: '#000', // sets color only for the active order tab icon (default: buttonColor #333)
  actionIconColor: '#000', // sets color only for the icons of the actionbox buttons
  margin: '0px 0px', // sets mnargin for #pl-main-box (default: 0px)
};

The customStyles attr can also be passed in via URL search query (without 'customStyles' parent key).
Just drop the '#' from hex colors and/or encode as URI component if needed.
For example www.versand-status.de/?trackingNo=...&borderRadius=2px&buttonColor=e6e6e6

⚠️ If you need more customizing, use a custom stylesheet.

Hook onRendered

There is another option called onRendered which expects a function (state) with state being an object describing the pulled information:

var plRenderedHook = function (state) {
  // Do something with the DOM or the information
  console.log(state);
};

var parcelLab = new ParcelLab('#pl-trace', { onRendered: plRenderedHook });
parcelLab.initialize();

Custom styling example

In this example we will set the box and button border-radius to 0px and make the buttons black.

<script type="text/javascript">
  var custom = { borderRadius: '0px', buttonBackground: '#000000', buttonColor: '#fff' };

  var parcelLab = new ParcelLab('#pl-trace', { styles: true, customStyles: custom });
  parcelLab.initialize();
</script>

Without action box

If you want to use the plugin in a non-customer facing website (e.g. internal page for customer support), it is recommended to hide the action box like so:

<style> div#pl-action-box-container { display: none; } </style>

Custom translations

You can change the static plugin text parts with your own translations. Therefor just add the attribute customTranslations to options and fill with your custom texts. You can find the full list of texts, used by the plugin here. If you don't define a language in your customTranslations, the plugin will fallback to the original text, when rendered in this language.

Custom translations example

Lets change the texts for the search form:

  ...
  options.customTranslations = {
    de: {
      searchOrder: 'Bestellnummer eingeben', // translation for search input placeholder
      zip: 'PLZ eingeben', // translation for zip input placeholder
      search: 'Suche starten', // translation for search button text
    },
    en: {
      searchOrder: 'Type order number',
      zip: 'Type zip code',
      search: 'Start search',
    },
  }
  var parcelLab = new ParcelLab('#pl-trace', options);
  parcelLab.initialize();

Integrate delivery time prediction

Please note: Delivery time prediction is currently only supported for deliveries to Germany.

Adding to your webpage

Same as above.

Initializing

After adding the script, there will be a new ParcelLabPrediction class in the global scope. This can also just be initialized, but more options are required for the script to work. Following parameters are required to be supplied in the options object:

• userId: This is your shop's parcelLab user-id and is used to map the start location.
• courier: Here, the parcelLab courier code for the planned courier has to be specified.
• location: This specifies the location of the recipient in one of two ways:
  1. Using the zip code and country, in the format <zip-code>_<country>, where <zip-code> is the pure-numerical zip code, and <country> the ISO 3166-1 alpha-3 code of the country. For example: 80331_DEU.
  2. The IP-Address of the visitor, e.g. 127.0.0.1.

Example

<head>
  ...
  <link href="https://cdn.parcellab.com/css/v2/parcelLab.min.css" rel="stylesheet">
  <link href="https://cdn.parcellab.com/css/font-awesome.min.css" rel="stylesheet">
</head>
<body>
  ...
  <script src="https://cdn.parcellab.com/js/v2/parcelLab.min.js" charset="utf-8"></script>
  <script type="text/javascript">
    var prediction = new ParcelLabPrediction('#deliveryTime', {
      // required
      userId: 122,
      courier: 'dhl-germany',
      location: '94261_DEU',

      // optional
      prefix: 'Lieferzeit:', // text to display left of the prediction
      suffix: 'Werktage', // text to display right of the prediction
      offset: 1, // offset in days to add to the predicted delivery time
      infoCaption: '#infoLabel', // where to display the info caption
      language: 'de', // language in which to display the info caption in
    });
    prediction.initialize(); // <~ this display the prediction in a dom-elem with id="#deliveryTime"
  </script>
</body>  

For developers

You will need GOOGLE_API_KEY for running the application locally. Andrej Fritz can provide it to you.

Develop

$ npm install
$ npm run start

Now, the test page is served on localhost:4000.

Build

$ npm run build

Minified index.js and index.css will be in the dist dir.

Deploy

$ npm run deploy

The index.jsand index.cssfiles will be deployed as parcelLab.min.js and parcelLab.min.css on the CDN.

Installing through NPM

If you do not want to use our brebuilt and hosted version - you can also install it yourself thtough NPM.

$ npm i @parcellab/js-plugin

Afterwards you should be able to use it like this:

import { ParcelLab } from '@parcellab/js-plugin/bundle/module.min.js';
import '@parcellab/js-plugin/bundle/module.min.css';

const options = { rerouteButton: 'left', show_searchForm: 'true' };
const plPlugin = new ParcelLab('#pl-trace', options);