Probo Product Configurator

The Probo Product Configurator is a webcomponent that allows your customers to effortlessly customize Probo Products within your application. The configurator is a wrapper for the /products/configure endpoint of the Probo API

Features

• Dynamic Customization: Users can customize their print products by selecting different options, including materials, sizes, quantities, etc.

• Responsive Design: The application is built with a responsive design to ensure a seamless experience across different devices and screen sizes.

• Easy Integration: Probo Product Configurator can be easily integrated into existing websites and e-commerce platforms as a web component, providing a consistent user experience.

About Probo

Probo is one of the largest Printing on Demand suppliers in Western Europe and a market leader in the BeNeLux.

• Probo Nederland
• Probo Deutschland
• Probo International

Getting Started

Before you get started you need to have a Probo account and API token for the ProboAPI. You can request this on your Probo platform.

Register an account

• Probo Nederland
• Probo Deutschland
• Probo International

Request a token

• Probo Nederland API instellingen
• Probo Deutschland API Einstellungen
• Probo International API settings

Installation

Installing the component

Via GIT

Clone the repository:

git clone https://github.com/ProboConnect/product-configurator.git

And include the web component:

<script type="module" src="probo-product-configurator.js" rel="text/javascript"></script>

Via CDN

<script
  type="module"
  src="https://cdn.jsdelivr.net/gh/ProboConnect/product-configurator@v1/probo-product-configurator.js"
  rel="text/javascript"
></script>

Proxy

Due to security, you need a proxy to make calls to Probo from your front end to the Probo API. The proxy calls the Probo API https://api.proboprints.com and needs to accept the endpoints from the request body.url. See below for an example.

PHP example

• Create a folder api
• Create in the api folder a new index.php
• Put the contents of the example below in the index.php
• Update the token

<?php

$rawData = file_get_contents('php://input');

$decodedData = json_decode($rawData, true);

$baseUrl = 'https://api.proboprints.com';
$token = 'YOUR_API_TOKEN';

$curl = curl_init();

curl_setopt($curl, CURLOPT_HTTPHEADER, [
    'Accept: application/json',
    'Content-Type: application/json',
    'Authorization: Basic ' . $token
]);
curl_setopt($curl, CURLOPT_RETURNTRANSFER, true);

if ($_SERVER['REQUEST_METHOD'] === 'POST') {
    curl_setopt($curl, CURLOPT_URL, sprintf('%s%s', $baseUrl, $decodedData['url']));
    curl_setopt($curl, CURLOPT_POSTFIELDS, json_encode($decodedData['data']));
} else {
    curl_setopt($curl, CURLOPT_URL, sprintf('%s%s', $baseUrl, $_GET['url']));
}

$resp = curl_exec($curl);
curl_close($curl);

echo $resp;

Initializing first steps

Choose the variant

There are two ways to use the configurator. With product search and in a modal:

<probo-product-configurator modal></probo-product-configurator>

Just the configurator

<probo-product-configurator></probo-product-configurator>

Initialization

1. Call either the init function on the proboConfigurator client and provide the proxy URL.

await window.proboConfigurator
    .init({
        proxy: '/api',
});

Or add the props to the component, and it will call the init function within.

  <probo-product-configurator
    proxy="/api"
    product-code="banner-510"
  />

If you need deliveries you need to add an address as well. Due to web component limitations, this cannot be done by prop.

await window.proboConfigurator
    .init({
        proxy: '/api',
        address: {
            companyName: 'Probo',
            firstName: 'John',
            lastName: 'Doe',
            street: 'Fortuinweg',
            houseNumber: '17',
            postalCode: '9101 PE',
            city: 'Dokkum',
            country: 'NL',
            email: '[email protected]',
        },
});

Or set it with its method:

window.proboConfigurator.setAddress({
    companyName: 'Probo',
    firstName: 'John',
    lastName: 'Doe',
    street: 'Fortuinweg',
    houseNumber: '17',
    postalCode: '9101 PE',
    city: 'Dokkum',
    country: 'NL',
    email: '[email protected]',
})

2. When using the search functionality call the openSearch function to open the search modal. Either chained with the init function:

await window.proboConfigurator
    .init({
        proxy: '/api',
    }).openSearch();

Or after:

window.proboConfigurator.openSearch()

3. Or when using the configurator without search (or product-code prop) set the product with the setProduct function and API code:

await window.proboConfigurator
    .init({
        proxy: '/api',
    }).setProduct('banner-510');

And to get the first option call the getNextOption() function.

Language

The default language of the configurator is Dutch. If another is needed, for example English, either add it in the init function:

await window.proboConfigurator
    .init({
        proxy: '/api',
        language: 'en',
    });

or with the setLanguage function.

window.proboConfigurator.setLanguage('en')

Or as prop

  <probo-product-configurator language="en" />

The available languages are Dutch (nl), English (en) and German(de).

Price types

If another price type is needed, or you want to add VAT set it via the init function:

await window.proboConfigurator
    .init({
        proxy: '/api',
        priceType: 'sales_price',
    });

or with the setPriceType function.

window.proboConfigurator.setPriceType('sales_price', true)

The default is purchase_price, excluding VAT.

Overwriting API data

If there is a need to change a title, description or image of an option or product you can use the overwrites property.

await window.proboConfigurator
    .init({
        proxy: '/api',
        overwrites: [
          {
            "code": "walltex-pro",
            "overwrites": {
              "title": "Walltex pro",
              "description": "Naadloos behang met plaklaag",
              "image": "image.jpg"
            }
          },
      ]
    });

Or maybe not showing a product at all, then you can hide it. It will not show up in search results or options for a step.

await window.proboConfigurator
    .init({
        proxy: '/api',
        overwrites: [
          {
            "code": "outdoor-mat",
            "overwrites": {
              "hide": true
            }
          },
      ]
    });

Overwrites also have their own method, but can only be set on init.

window.proboConfigurator.init().setOverwrites()

Configuring by payload

The configurator can be set with an existing payload as follows:

window.proboConfigurator.setFromPayload(payload)

The Payload can either be just a product:

{
  "products": [
    {
      "code": "banner-510",
      "options": [
        {
          "code": "width",
          "value": 2000
        },
        {
          "code": "height",
          "value": 2000
        },
        {
          "code": "amount",
          "value": 4
        }
      ]
    }
  ]
}

Or can also contain the address, so the deliveries get fetched as well:

{
  "deliveries": [
    {
      "address": {
        "companyName": "Probo",
        "firstName": "John",
        "lastName": "Doe",
        "street": "Fortuinweg",
        "houseNumber": "17",
        "postalCode": "9101 PE",
        "city": "Dokkum",
        "country": "NL",
        "email": "[email protected]"
      }
    }
  ],
  "products": [
    {
      "code": "banner-510",
      "options": [
        {
          "code": "width",
          "value": 2000
        },
        {
          "code": "height",
          "value": 2000
        },
        {
          "code": "amount",
          "value": 4
        }
      ]
    }
  ]
}

Finishing configuration

When a configuration is complete and can be used in an order, the proboConfigurator:finished event is dispatched on the window.

Getting results

When the configuration is finished you call the window.proboConfigurator.getResult() to get the configuration and excerpt of the product.

Simple example output:

{
  "excerpt": {
    "product": {
      "description": "5x banner-510 234x234",
      "description_options": "width: 234, height: 234, amount: 5, finishing-all-sides, cut, customer-supplied-file"
    }
  },
  "configuration": {
    "products": [
      {
        "code": "banner-510",
        "options": [
          {
            "code": "width",
            "value": 234
          },
          {
            "code": "height",
            "value": 234
          },
          {
            "value": 5,
            "code": "amount"
          },
          {
            "code": "finishing-all-sides"
          },
          {
            "code": "cut"
          },
          {
            "code": "customer-supplied-file"
          }
        ]
      }
    ],
    "language": "en"
  }
}

Getting the upload data

Use proboConfigurator.needsUpload() to determine if an upload is needed.

And proboConfigurator.getUploaderData() to get the uploader data.

Getting the raw payload

proboConfigurator.getRaw() returns the whole unmapped API payload;

Clearing the config

By calling proboConfigurator.clear() all options are reset and the component should return to its initial state.

Customizing the configurator

As the configurator is a web component, styling it directly is not possible. Therefore there are several CSS ::part selectors made available to style the configurator.

By selecting the part you can change the color of the background, font, etc. For most values you'll have to add the !important property to override the default styling.

probo-product-configurator::part(configurator) {
  background-color: #324342 !important
}

Element	Part
configurator (container)	configurator
step (container)	step
step title	step-title
step subtitle	step-stubtitle
open state indicator icon	state-indicator-icon
option card (container)	option
option card selected state	option-selected
option title	option-title
option description	option-description
delivery step	delivery-step
delivery step title	delivery-step-title
delivery step subtitle	delivery-step-subtitle
delivery option day	delivery-option-day
delivery option date	delivery-option-date
delivery option cost	delivery-option-cost
delivery option no cost	delivery-option-no-cost

Reporting issues or requests

If you have issues or feature requests, please create a GitHub issue.

License

This project is licensed under the MIT License - see the LICENSE file for details.

Disclaimer

This tool is designed to assist in visually configuring a Probo product and generating the corresponding payload. As the integrator of this configurator, you are responsible for ensuring the payload remains valid when used, for example, in the order payload.

Please note that configurations may sometimes become invalid due to unforeseen changes in the product setup. While Probo strives to minimize these issues and inform you in a timely manner, it is your responsibility to revalidate the payload before use. Revalidation can be done through this tool or other available methods.

The use of this tool does not grant any rights.

---

2024 Probo.