{"id":24559253,"url":"https://github.com/parcellab/parcellab-js-plugin","last_synced_at":"2025-04-19T12:08:54.745Z","repository":{"id":10082011,"uuid":"64418699","full_name":"parcelLab/parcelLab-js-plugin","owner":"parcelLab","description":"JavaScript plugin used to retrieve and display trackings from parcelLab on any given webpage.","archived":false,"fork":false,"pushed_at":"2024-05-24T14:43:24.000Z","size":3728,"stargazers_count":8,"open_issues_count":1,"forks_count":2,"subscribers_count":13,"default_branch":"main","last_synced_at":"2025-01-02T04:52:22.539Z","etag":null,"topics":["courier","deliveries","ecommerce","javascript-plugin","parcellab","parcels","prediction","team-frontend","webpage"],"latest_commit_sha":null,"homepage":"https://how.parcellab.works/docs/integration-quick-start/track-and-trace-page","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/parcelLab.png","metadata":{"files":{"readme":"Readme.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":"CODEOWNERS","security":null,"support":null,"governance":null}},"created_at":"2016-07-28T18:27:13.000Z","updated_at":"2024-11-26T15:17:03.000Z","dependencies_parsed_at":"2023-09-30T21:02:59.552Z","dependency_job_id":null,"html_url":"https://github.com/parcelLab/parcelLab-js-plugin","commit_stats":{"total_commits":493,"total_committers":24,"mean_commits":"20.541666666666668","dds":"0.32251521298174446","last_synced_commit":"2700639059f604dbe46a25aea5cff64f48acc43f"},"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/parcelLab%2FparcelLab-js-plugin","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/parcelLab%2FparcelLab-js-plugin/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/parcelLab%2FparcelLab-js-plugin/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/parcelLab%2FparcelLab-js-plugin/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/parcelLab","download_url":"https://codeload.github.com/parcelLab/parcelLab-js-plugin/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":235233256,"owners_count":18957066,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["courier","deliveries","ecommerce","javascript-plugin","parcellab","parcels","prediction","team-frontend","webpage"],"created_at":"2025-01-23T06:16:02.255Z","updated_at":"2025-01-23T06:16:04.712Z","avatar_url":"https://github.com/parcelLab.png","language":"JavaScript","readme":"# parcelLab JavaScript Plugin v3\n\n*v4 available on [v4 branch](https://github.com/parcelLab/parcelLab-js-plugin/tree/v4).*\n\n![parcelLab JS Plugin](./mockup.jpg)\n\nIntegrate 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.\n\n## Integrate delivery status page\n\n### Adding to your webpage\nJust place the following snippet into the container you want the plugin to be rendered.\n\n```html\n\u003cdiv id=\"pl-trace\"\u003e\u003c/div\u003e\n\n\u003cscript  type=\"text/javascript\"\u003e\n  (function (prcl) {/* Load parcelLab assets ... */\n    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);\n  })(function () {/* ... plugin is ready to use: */\n    var options = {};\n    var pl = new ParcelLab('#pl-trace', options);\n    pl.initialize();\n    window._prcl = pl;\n  });\n\u003c/script\u003e\n```\n\nThis 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).\n  \n#### WARNING\nIf your webpage does not allow post hoc insertion of assets (scripts and stylesheets), you have to add the assets manually in the `\u003cheader\u003e` part of your webpage.  \nA recent version of these scripts is always available at the parcelLab CDN:\n- `\u003clink href=\"https://cdn.parcellab.com/css/v3/parcelLab.min.css\" rel=\"stylesheet\"\u003e`\n- `\u003cscript src=\"https://cdn.parcellab.com/js/v3/parcelLab.min.js\" charset=\"utf-8\"\u003e\u003c/script\u003e`\n\n### Options\nYou can define options by passing an Object as second argument, when creating a new ParcelLab Object.\n```html\n  \u003cscript type=\"text/javascript\"\u003e\n    ...\n    var options = { rerouteButton: 'left', show_searchForm: 'true' };\n    var parcelLab = new ParcelLab('#pl-trace', options);\n    parcelLab.initialize();\n    ...\n  \u003c/script\u003e\n```\n\nThese are the available options:\n- `styles`: Boolean (`false` will disable the default css for custom styling)\n- `customStyles`: Object (see below)\n- `rerouteButton`: `'left' | 'right'` - default is `'right'` (defines where to render the reroute button if possible)\n- `show_searchForm`:  Boolean (activates a search form, which will be rendered if tracking was not found or no trackingNo/orderNo was given, needs userId)\n- `show_zipCodeInput`: Boolean (activates the zip code field for the search form)\n- `userId`: String (alternative way to pass userId - instead of in url)\n- `trackingNo`: String (alternative way to pass trackingNo - instead of in url)\n- `orderNo`: String (alternative way to pass orderNo - instead of in url)\n- `zip`: String (alternative way to pass zip - instead of in url)\n- `courier`: String (alternative way to pass courier - instead of in url)\n- `client`: String (alternative way to pass courier - instead of in url)\n- `selectedTrackingNo`: String (alternative way to pass selectedTrackingNo - instead of in url)\n- `show_note`: String (renders a note box on top - useful for showing important information)\n- `onRendered`: Function (the plugin will run this function whenever it (re)renders)\n- `icon_theme`: `'xmas' | 'easter'` (activates the themed icons 🎄/🐰)\n- `customTranslations` Object (see below)\n- `lang`: Language ISO code, if not provided, user browser language will be used. (It can be 2 letters code `en` or 4 `en-us`)\n\nAll options can also be set via URL search query.  \nJust drop the '#' from hex colors and/or encode as URI component if needed.  \n`www.yourshop.com/tracking/page/path?trackingNo=xyz\u0026courier=dhl-germany`  \n\n### Banner\n\nThe script can render an image banner link on the right, with these option parameters:\n\n- `banner_image` : *String* (url of image or `'instagram'` for your latest instagram posting)\n- `banner_link` : *String* (url of link destination)\n\n`banner_link` is optional if `banner_image` is `'instagram'` where it defaults to your instagram page. \n\nFor 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.\n\n\n⚠ *instagram banners are not enabled by default. ask our support if you want this feature.*\n\n⚠ *instagram banners require the `u` parameter with your userId to be present*\n\n### Custom styling\nYou can customize the buttons and the boxes of the plugin by simply passing the Object 'customStyles' in the options.  \nPossible customStyle options:\n```javascript\noptions.customStyles = {\n  borderColor: '#eeeeee', // sets border color for the boxes (default: #eeeeee)\n  borderRadius: '4px', // sets the border radius for the boxes and buttons (default: 4px)\n  buttonColor: '#333', // sets text color for buttons (default: #333)\n  buttonBackground: '#e6e6e6', // sets background color for buttons (default: #e6e6e6)\n  iconColor: '#000', // sets color for the status icons (default: #000)\n  tabIconColor: '#000', // sets color for the order tab icons (default: buttonColor #333)\n  activeTabIconColor: '#000', // sets color only for the active order tab icon (default: buttonColor #333)\n  actionIconColor: '#000', // sets color only for the icons of the actionbox buttons\n  margin: '0px 0px', // sets mnargin for #pl-main-box (default: 0px)\n};\n```\n\nThe customStyles attr can also be passed in via URL search query (without 'customStyles' parent key).  \nJust drop the '#' from hex colors and/or encode as URI component if needed.  \nFor example  `www.versand-status.de/?trackingNo=...\u0026borderRadius=2px\u0026buttonColor=e6e6e6`\n\n#### ⚠️  If you need more customizing, use a custom stylesheet.\n\n### Hook onRendered\n\nThere is another option called `onRendered` which expects a `function (state)` with `state` being an object describing the pulled information:\n\n```javascript\nvar plRenderedHook = function (state) {\n  // Do something with the DOM or the information\n  console.log(state);\n};\n\nvar parcelLab = new ParcelLab('#pl-trace', { onRendered: plRenderedHook });\nparcelLab.initialize();\n```\n\n## Custom styling example\nIn this example we will set the box and button border-radius to 0px and make the buttons black.\n```html\n\u003cscript type=\"text/javascript\"\u003e\n  var custom = { borderRadius: '0px', buttonBackground: '#000000', buttonColor: '#fff' };\n\n  var parcelLab = new ParcelLab('#pl-trace', { styles: true, customStyles: custom });\n  parcelLab.initialize();\n\u003c/script\u003e\n```\n\n### Without action box\n\nIf 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:\n\n```html\n\u003cstyle\u003e div#pl-action-box-container { display: none; } \u003c/style\u003e\n```\n\n## Custom translations\nYou 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](https://github.com/parcelLab/parcelLab-js-plugin/blob/master/src/js/lib/static.js#L253). If you don't define a language in your customTranslations, the plugin will fallback to the original text, when rendered in this language.\n\n### Custom translations example\nLets change the texts for the search form:\n```javascript\n  ...\n  options.customTranslations = {\n    de: {\n      searchOrder: 'Bestellnummer eingeben', // translation for search input placeholder\n      zip: 'PLZ eingeben', // translation for zip input placeholder\n      search: 'Suche starten', // translation for search button text\n    },\n    en: {\n      searchOrder: 'Type order number',\n      zip: 'Type zip code',\n      search: 'Start search',\n    },\n  }\n  var parcelLab = new ParcelLab('#pl-trace', options);\n  parcelLab.initialize();\n```\n\n## Integrate delivery time prediction\n*Please note: Delivery time prediction is currently only supported for deliveries to Germany.*\n\n### Adding to your webpage\nSame as above.\n\n### Initializing\nAfter 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:\n\n* `userId`: This is your shop's parcelLab user-id and is used to map the start location.\n* `courier`: Here, the parcelLab courier code for the planned courier has to be specified.\n* `location`: This specifies the location of the recipient in one of two ways:\n  1. Using the zip code and country, in the format `\u003czip-code\u003e_\u003ccountry\u003e`, where `\u003czip-code\u003e` is the pure-numerical zip code, and `\u003ccountry\u003e` the [ISO 3166-1 alpha-3](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-3) code of the country. For example: `80331_DEU`.\n  2. The IP-Address of the visitor, e.g. `127.0.0.1`.\n\n### Example\n```html\n\u003chead\u003e\n  ...\n  \u003clink href=\"https://cdn.parcellab.com/css/v2/parcelLab.min.css\" rel=\"stylesheet\"\u003e\n  \u003clink href=\"https://cdn.parcellab.com/css/font-awesome.min.css\" rel=\"stylesheet\"\u003e\n\u003c/head\u003e\n\u003cbody\u003e\n  ...\n  \u003cscript src=\"https://cdn.parcellab.com/js/v2/parcelLab.min.js\" charset=\"utf-8\"\u003e\u003c/script\u003e\n  \u003cscript type=\"text/javascript\"\u003e\n    var prediction = new ParcelLabPrediction('#deliveryTime', {\n      // required\n      userId: 122,\n      courier: 'dhl-germany',\n      location: '94261_DEU',\n\n      // optional\n      prefix: 'Lieferzeit:', // text to display left of the prediction\n      suffix: 'Werktage', // text to display right of the prediction\n      offset: 1, // offset in days to add to the predicted delivery time\n      infoCaption: '#infoLabel', // where to display the info caption\n      language: 'de', // language in which to display the info caption in\n    });\n    prediction.initialize(); // \u003c~ this display the prediction in a dom-elem with id=\"#deliveryTime\"\n  \u003c/script\u003e\n\u003c/body\u003e  \n```\n\n## For developers\n\nYou will need GOOGLE_API_KEY for running the application locally. Andrej Fritz can provide it to you.\n### Develop\n```bash  \n$ npm install\n$ npm run start\n```\n\nNow, the test page is served on `localhost:4000`.\n\n### Build\n```bash\n$ npm run build\n```\nMinified `index.js` and `index.css` will be in the `dist` dir.\n\n### Deploy\nAutomatically deployed via GitHub Actions.\nThe `index.js` and `index.css` files will be deployed as parcelLab.min.js and parcelLab.min.css on the CDN.\n\n## Installing through NPM\nIf you do not want to use our brebuilt and hosted version - you can also install it yourself thtough NPM.\n\n```bash\n$ npm i @parcellab/js-plugin\n```\n\nAfterwards you should be able to use it like this:\n\n```javascript\nimport { ParcelLab } from '@parcellab/js-plugin/bundle/module.min.js';\nimport '@parcellab/js-plugin/bundle/module.min.css';\n\nconst options = { rerouteButton: 'left', show_searchForm: 'true' };\nconst plPlugin = new ParcelLab('#pl-trace', options);\n```\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fparcellab%2Fparcellab-js-plugin","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fparcellab%2Fparcellab-js-plugin","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fparcellab%2Fparcellab-js-plugin/lists"}