API Version | 1.1.0 |
Date | 2023-08-21 |
This document describes how to integrate a product catalog or configurator into pCon.basket. External catalogs are embedded using an HTML IFrame. Thus a public HTTPS URL for the catalog has to be provided.
The communication between pCon.basket and the catalog is done using postMessage
. More information can be found here: Window.postMessage()
The basic sequence for the catalog integration looks like this:
For an external catalog to be visible in pCon.basket, it must be registered. This can be done as part of the OFML data registration. Please follow the DSR
specification for further information. If you are integrating pCon.basket it is also possible to register catalogs using the integration API.
Catalogs which are specified in DSR
have to provide a logo image. This image has to be a JPEG
with the name catalog-logo.jpg
that is hosted in the root folder of the catalog website.
For example the image URL for the catalogs https://www.example.com
and https://www.example.com/my-catalog.html
will be https://www.example.com/catalog-logo.jpg
.
If you are using the integration API to register the catalog you may specify a custom logo URL. Please check the Integration Example
for an example.
pCon.basket will send messages to the catalog by calling postMessage
on the iframe's contentWindow. To send a message to the basket, postMessage
has to be called on the parent window of the catalog.
The actual message and its parameters are stored in the data of the message event. Every message data has the following structure:
interface MessageData { /** message identifier */ type: string; /** optional parameter of the message */ parameter?: string | object; }
To initialize the product catalog/configurator with the correct language, currency and other settings the catalog has to request the catalog parameters upon startup. This is done using the wbk.externalCatalog.getCatalogParameters
message. The basket will respond with the a wbk.externalCatalog.catalogParameters
message. The parameter of the received message has the following structure.
interface CatalogParameters { /** preferred locale for the external catalog UI */ locale: string; /** preferred currency for article prices */ currency: string; /** preferred language for article data in order of priority */ language: Array<string>; /** currently active tax scheme */ taxScheme: TaxScheme; /** active color scheme of the basket */ theme: Theme; } ///// subtypes ///// interface TaxScheme { id: string; country: string; region: string; taxTypes: Array<TaxType>; } interface TaxType { id: string; rateUnit: string; taxCategories: Array<TaxCategory>; } interface TaxCategory { id: string; rate?: number; } interface Theme { primaryColor: string; textColor: string; fontFamily: string; }
The following JavaScript code snippet demonstrates how the catalog parameters can be requested:
//register event handler for incoming messages window.addEventListener("message", onMessage); //request catalog parameters window.parent.postMessage({ type: "wbk.externalCatalog.getCatalogParameters" }, "*"); //function which handles all incoming messages function onMessage(pEvent) { if (pEvent.data.type === "wbk.externalCatalog.catalogParameters") { //... process the catalog parameters here console.dir(pEvent.data.parameter); } }
When the user is finished selecting or configuring the articles in the catalog the selected articles have to be sended to the basket. This is done using the wbk.externalCatalog.insertArticles
message. The message expects an array of articles as parameter. pCon.basket supports two kinds of articles, Custom
and Ofml
.
Custom articles are user defined articles and usually do not exist in any OFML catalog. The data structure of a custom article looks like this:
interface CustomArticle { type: "Custom"; manufacturerId?: string; seriesId?: string; baseArticleNumber?: string; finalArticleNumber?: string; variantCode?: string; /** * Quantity of the article * @defaultValue 1 */ quantity?: number; /** short text as simple string or as multi language map (language code -> text) */ shortText?: string | { [language: string]: string }; /** long text as simple string or as multi language map (language code -> text) */ longText?: string | { [language: string]: string }; /** feature text as simple string or as multi language map (language code -> text) */ featureText?: string | { [language: string]: string }; /** Additional comments/notes for this article. */ comments?: string; purchasePrice?: Money; salesPrice?: Money; packagingInfo?: PackagingInfo; /** Map from tax type to tax category for the active tax scheme. */ taxes?: { [type: string]: string }; /** * Url or data-URI for the article image. * Currently only jpg and png images are supported. */ imageUrl?: string; } ///// subtypes ///// interface Money { value: number; currency: string; } interface Value { value: number; unit: string; } interface PackagingInfo { width?: Value; height?: Value; depth?: Value; volume?: Value; tareWeight?: Value; netWeight?: Value; itemsPerPackUnit?: number; packUnitsPerArticle?: number; }
OFML articles are predefined articles which can only be inserted if the user has access to the corresponding OFML catalog. The data structure of an OFML article looks like this:
interface OfmlArticle { type: "Ofml"; manufacturerId: string; seriesId: string; baseArticleNumber: string; variantCode?: string; ofmlVariantCode?: string; /** * Quantity of the article * @defaultValue 1 */ quantity?: number; }
The following JavaScript code snippet demonstrates how to send two custom articles to the basket:
window.parent.postMessage({ type: "wbk.externalCatalog.insertArticles", parameter: [ { type: "Custom", manufacturerId: "TEST", seriesId: "OFFICE", baseArticleNumber: "office-chair", shortText: "Office Chair", salesPrice: { value: 100, currency: "EUR" } }, { type: "Custom", manufacturerId: "TEST", seriesId: "OFFICE", baseArticleNumber: "office-tabel", shortText: "Office Table", salesPrice: { value: 200, currency: "EUR" } } ] }, "*");
Version 1.1.0
quantity
field to OFML articlesVersion 1.0.0
© EasternGraphics GmbH | Albert-Einstein-Straße 1 | 98693 Ilmenau | GERMANY
This work (whether as text, file, book or in other form) is copyright. All rights are reserved by
EasternGraphics GmbH. Translation, reproduction or distribution of the whole or parts thereof is permitted only with the prior agreement in writing of EasternGraphics GmbH.
EasternGraphics GmbH accepts no liability for the completeness, freedom from errors, topicality or continuity of this work or for its suitability to the intended purposes of the user. All liability except in the case of malicious intent, gross negligence or harm to life and limb is excluded.
All names or descriptions contained in this work may be the trademarks of the relevant copyright owner and as such legally protected. The fact that such trademarks appear in this work entitles no-one to assume that they are for the free use of all and sundry.