Navbar
  • Introduction
  • Customizer Platform
  • Products Architecture and Configuration
  • Product Mixins
  • System Architecture Overview
  • Sample Data
  • Blueprints
  • Recipes
  • Developing Customization Experiences
  • JavaScript Language Versions
  • Reference Implementation
  • JavaScript API
  • Introduction

    Look for code samples on this side of the documentation.

    Welcome to Customizer!

    This document provides technical information regarding Drive Commerce Customizer technology. It gives an overview of the functional architecture and product modeling process, as well as details on deployment, integration, and maintenance activities.

    Customizer Platform

    Drive Commerce Customizer is a product configuration system providing a robust back-end management tools, a plugin-based front-end experience, and streamlined API for integrating into typical website flows.

    Conceptually, Customizer SaaS application is separated into four primary components:

    Products Architecture and Configuration

    Overview

    As a part of the Customizer implementation engagement, the Drive Commerce team will assist with defining and configuring the product model.

    Rather than completely replacing all management aspects of customizable products, Customizer aims to augment existing e-commerce systems. Products continue to be configured in the host website e-commerce environment, holding information about availability, pricing, inventory levels, etc. Customizer backend in its turn is responsible for storing detailed information about the custom product architecture — defining how products are built, which components are customizable, and potential customization options.

    Customizer flexible data model provides a way to configure a large variety of products. At the core, products are defined by following elements:

    These elements define the product taxonomy and architecture, the basic building blocks from which any customizable product can be built. These building blocks are shared among all product instances and versions.

    For example, the product model may include a list of available colors and their related part codes, such as a Pantone color that identifies a specific thread color. Typically color attributes such as identifiers, codes, names will not vary the meaning between different products (Blue is Blue everywhere), thus making it easier to maintain a single list as the source of truth for all colors.

    Component Options

    Component option definitions and component options are the most basic product elements. Definitions are a way to create groups of related options and specify some common characteristics.

    For example, an implementation of a customizable product may include option definitions for concepts like materials, colors, personalizable options, user-defined content, etc.

    Component options in turn would describe specific instances of each of definitions: materials could be one of leather, metal, plastic; colors may be one of red, blue, green, etc; personalization options could include bold or italic font styles, Arial or Times font family, etc.

    Widgets

    Component options typically describe product elements that have to be selected by consumers to create a final product. Most options would be displayed on the customization user experience, represented by buttons, sliders, toggles, file uploaders, etc. Customizer allows configuring presentation of each option using the custom attributes extensibility model.

    Component Types

    Next level in the product architecture is component types. In many cases, component options need to group to form a valid component that could be used to build a product. For example, materials and colors may exist as separate options (Canvas, Mesh, Leather materials; Red, Blue, Brown colors), product parts require some valid combination of both — Red Canvas, Blue Mesh, Brown Leather. Component types define such relationships.

    Some component types describing simple product elements can have a one-to-one correspondence to component option definitions, while complex product parts may consist of multiple definitions. For example, a product part may need to have a selection of a material and color to be valid.

    Component Placements

    Placements are the primary building block of products. While component options and component types exist mostly as separate reusable Lego pieces, placements level is where product structure defined.

    Placements serve as containers into which component options can be slotted to build a complete product. Each product must be composed of one or more placements.

    Products

    Products finally tie together all previously discussed elements and complete the product architecture:

    Products use style codes as their primary identifiers.

    Product Mixins

    In many cases, product architecture can be rather simple, with products defining available placements, component options that are allowed in each placement, etc.

    However, implementations may have unique requirements:

    A mixin is a partial product configuration, defining all or some aspects of products. For example, a mixin can outline image views, or component placement associations, or some other configuration options.

    Mixin typically cannot be viewed or configured by itself in the front-end experience. However, multiple mixins could be combined together to form a complete product. An implementation may define a number of mixins to reduce the complexity of product management and configuration.

    System Architecture Overview

    Customizer aims to provide the most lightweight and flexible approach for integration customization experiences into the host website. Customizer Administration backend and UX are responsible for metadata and product setup. Customizer API provides a method of communicating between the host website and Customizer backend. On the front-end site, the host site is responsible for integrating the Customizer widget into the PDP code. Customizer widget is a Javascript library which provides a set of tools for creating custom product experiences:

    System overview

    The typical sequence of events and communication between all involved components happens as follows:

    System flow

    Blueprints

    Blueprints are JSON data files describing a product model, which are used by the front-end experience and back-end integrations for displaying available product options, enable rendering, and can-be-built validations.

    While usually blueprints are only loaded by the Customizer widget code, an implementation also uses blueprints to customize the user experience further.

    See below for the blueprint data structure documentation.

    Recipes

    A recipe will be generated when a design is fully configured and committed back to the Customizer backend. Recipes contain the essential information about how a product was configured, and contain enough information to build it.

    A randomly generated ID identifies each recipe.

    Customizing Blueprints

    The customizer platform is designed to be flexible to accommodate a variety of possible business logic requirements, data flows, UX customizations, etc. Rather than providing hard-coded and rigid UI elements to maintain these customizations, Customizer provides a way to associate arbitrary data with most of the object types that can appear in blueprints. This data will be surfaced in blueprints using .custom JSON key-value dictionary, associated with a parent object.

    Personalization

    Many products allow consumers not only select options from a number of a preconfigured parts but also include free-form customizable messages, which could be text or even images. For example, a t-shirt product may allow placement of dynamically uploaded images into a number of personalization zones, or let customers type in a message in a number of predefined fonts and colors.

    Both image upload and personalization text entry are controlled using the custom attributes extensibility model. Note that these attributes don't have to appear all on the same component option. For example, a personalization text zone may consist of a text entry, text color, text font, and a text size option definitions, each providing the respective set of attributes controlling a part of the experience.

    Personalization Text

    Attribute Comments
    personalization-text A placeholder for the text entered by a consumer
    personalization-transform Applies a text transformation to characters entered by a consumer. May be one of the following values:

    uppercase Convert the entered text to the upper case

    lowercase Convert the entered text to the lower case.

    Leave the value empty to disable the transformation.

    personalization-validate Defines the regex to validate the entered text message. For example, ^[a-zA-Z0-9]$ would allow only uppercase and lowercase Latin characters and numbers.
    personalization-color The personalization text color, HTML-style color code.
    personalization-font The personalization font. May be a string that refers to a system font (for example, Arial. Note: system fonts are not guaranteed and may not work in all circumstances), or a file name with extension to dynamically load a TTF font file.
    personalization-bold Set to true to enable faux bold font rendering. It is recommended to use personalization-font to load the appropriate font weight file directly.
    personalization-italic Set to true to enable faux italic font rendering. It is recommended to use personalization-font to load the appropriate font weight file directly.
    personalization-size Personalization font size.
    personalization-curve-radius Allows to place the personalization text on a curve. Allows position (the text arc bending towards the bottom), and negative values.
    personalization-curve-start Rotates the personalization text arc. Use 0 to orient the text upright.
    personalization-x Defines the horizontal text position.
    personalization-y Defines the vertical text position.
    personalization-scale Allows to scale the text rendering, in addition to the text size. For example, different product views may require rendered text size adjustments while keeping the same font size.

    Dynamic Images

    Attribute Comments
    dynamic-image-allow-resize Set to yes to allow consumers to resize dynamic images using the image widget.
    dynamic-image-allow-move Set to yes to allow consumers to move dynamic images using the image widget.
    dynamic-image-allow-rotate Set to yes to allow consumers to rotate dynamic images using the image widget.
    dynamic-image-area-x Defines the center placement of the image customization area. Note: the area placement can be fine-tuned on the per-view basic using placement transformation attributes.
    dynamic-image-area-y Defines the center placement of the image customization area. Note: the area placement can be fine-tuned on the per-view basic using placement transformation attributes.
    dynamic-image-area-width The width of the image customization area.
    dynamic-image-area-height The height of the image customization area.
    dynamic-image-fit Defines the initial placement of uploaded images. Can be one of the following values:

    none Images are not scaled to fit into the area; center of the image is aligned with the center of the customization zone.

    contain The center of the uploaded image is aligned with the center of the customization zone. The image is resized to be fully contained within the customization zone

    cover The center of the uploaded image is aligned with the center of the customization zone. The image is resized to be fully cover the customization zone without gaps.

    dynamic-image-scale-min Defines the minimum image scale.
    dynamic-image-scale-max Defines the maximum image scale.
    dynamic-image-upload-limit-max-width Allows uploading of images with the size only up to the given dimensions.
    dynamic-image-upload-limit-max-height Allows uploading of images with the size only up to the given dimensions.
    dynamic-image-upload-limit-min-width Allows uploading of images with the size at least with the given dimensions.
    dynamic-image-upload-limit-min-height Allows uploading of images with the size at least with the given dimensions.
    dynamic-image-upload-limit-filesize Uploaded image file size limit, in MB.
    dynamic-image-upload-width If necessary for the uniform processing, specifies the dimensions that all uploaded image would be converted to.
    dynamic-image-upload-height If necessary for the uniform processing, specifies the dimensions that all uploaded image would be converted to.
    dynamic-image-upload-fit Defines the fit uploaded images when converting to the specified dimensions. Can be one of the following values:

    none Images are not scaled and are used as-is.

    contain The center of the uploaded image is aligned with the center of the customization zone. The image is resized to be fully contained within the customization zone

    cover The center of the uploaded image is aligned with the center of the customization zone. The image is resized to be fully cover the customization zone without gaps.

    Sample Data

    In order to make some of the examples below more visual, we are going to define a sample product: a watch. Our watch product will have a customizable case and a band with a choice of materials and colors and will allow entering a personalization text to be engraved on the back of the watch case.

    The watch will have three possible views:

    Blueprints

    A sample blueprint of the demo watch product can be found at: https://bit.ly/2sib7Zc

    Blueprint API

    Typically, construction of the blueprint URL happens behind of scenes when using the Customizer JavaScript helpers, however it might be helpful to understand the blueprint API.

    https://api.customizer.drivecommerce.com/api/v1/blueprint/products/version/site/?apikey=key

    A blueprint API request should use GET HTTP method, with a URL structure defined as following

    Arguments
    products Products is a comma-separated list of products to be loaded within the single blueprint. Usually this a single product (WATCH360 in our watch example), or may include additional product IDs to dynamically construct a product from multiple parts.
    version Product version to be loaded or _ (single underscore character) to load the currently active version.
    site Product site to be loaded or _ (single underscore character) to load the default site.
    apikey Authorization code. API keys can be created in the Account section of the Customizer administration website.

    Notable Blueprint Components

    Element
    generated Timestamp when the blueprint was generated. Blueprints are cached by the customer backend and refreshed after a period of time had elapsed or a product structure had changed.
    name Product name.
    styleCode Product ID.
    relatedProducts Represents the product composition tree if the product uses static mixins or dynamic mixins.
    packages Package definitions.
    views Product view definitions.
    groups Represents the product structure, i.e. placements with associated selectable product options.
    options A flat list of product options configured in at least one placement.

    Recipes

    A sample recipe for the demo watch product can be found at: https://cz.drrv.co/recipe/2-vBYtsQB2ndCosDcB.json

    Machine Readable

    The primary recipe is stored as machine-readable JSON data file, at a well-defined location which can be generated by concatenating http://cz.drrv.co/recipe/ URL with the recipe ID and .json extension.

    Notable Recipe Components

    Element
    id A unique recipe ID.
    created Timestamp when the recipe was generated.
    name Product name.
    styleCode Product ID.
    humanReadable A link to the human-readable version of the recipe.
    components A list of placements with a reference to the selected component for each placement.
    views Product views with rendered product image references.
    {
      "views": [
        {
          "name": "360°",
          "code": "360",
          "preview": "//img1.cohimg.net/is/image/DriveCommerce/?layer=0&scl=1&origin=0,0&src=DriveCommerce/W-SHADOW-28&layer=1&src=DriveCommerce/W-P01-SS-GD-28&origin=0,0&layer=2&src=DriveCommerce/W-P02-LE-BL-28&origin=0,0&fmt=png-alpha&.e=customizer&1",
          "previewPng": "//cz.drrv.co/recipe/2-vBYtsQB2ndCosDcB-360.png",
          "previewJpg": "//cz.drrv.co/recipe/2-vBYtsQB2ndCosDcB-360.jpg"
        },
        {
          "name": "Back",
          "code": "Back",
          "preview": "//img1.cohimg.net/is/image/DriveCommerce/?layer=0&scl=1&origin=0,0&src=DriveCommerce/W-SHADOW-16&layer=1&src=DriveCommerce/W-P01-SS-GD-16&origin=0,0&layer=2&src=DriveCommerce/W-P02-LE-BL-16&origin=0,0&fmt=png-alpha&.e=customizer&1",
          "previewPng": "//cz.drrv.co/recipe/2-vBYtsQB2ndCosDcB-Back.png",
          "previewJpg": "//cz.drrv.co/recipe/2-vBYtsQB2ndCosDcB-Back.jpg"
        },
        {
          "name": "Personalize",
          "code": "Personalize",
          "preview": "//img1.cohimg.net/is/image/DriveCommerce/?layer=0&scl=1&origin=0,0&src=DriveCommerce/W-SHADOW-40&anchor=0,0&layer=1&textPs={\\fonttbl{\\f1Arial;}}\\f1{\\iscolortbl;FFFFFF;}\\cf1\\fs120\\qc\\kerning1 TES&origin=0,0&size=200,200&pos=412,482&layer=2&src=DriveCommerce/W-P01-SS-GD-40&origin=0,0&layer=3&src=DriveCommerce/W-P02-LE-BL-40&origin=0,0&fmt=png-alpha&.e=customizer&1",
          "previewPng": "//cz.drrv.co/recipe/2-vBYtsQB2ndCosDcB-Personalize.png",
          "previewJpg": "//cz.drrv.co/recipe/2-vBYtsQB2ndCosDcB-Personalize.jpg"
        }
      ]
    }
    

    Configured Images

    One useful aspect of machine-readable recipes are images that could be used for presenting configured products in UX such as cart or checkout. These images can be found under views element, with one image generated for each configured product view. Customizer backend uploads a transparent PNG file and opaque optimized JPG image.

    Keys
    name View name.
    code View code.
    previewPng PNG version of the view image. Allows for transparency if source images also had transparent areas.
    previewJpg JPEG version of the view image.

    Human Readable

    In addition to the machine-readable JSON file, Customizer products a human-readable version of recipes in PDF format. These can be found at a well-defined location which can be generated by concatenating http://cz.drrv.co/recipe/ URL with the recipe ID and .pdf extension.

    For example: https://cz.drrv.co/recipe/2-vBYtsQB2ndCosDcB.pdf

    PDF describes the same Bill of Materials as the machine-readable format and includes rendered images of configured products.

    Creating a Recipe and Recipe API

    Recipes are usually created by using one of Customizer JavaScript components. This ensures the recipe validity, i.e. that all placement have an option selected, options are purchasable, etc.

    However, if there is a need to generate a recipe manually, this can be done by sending a POST request with a fully-configured recipe JSON the respective blueprint URL.

    Developing Customization Experiences

    Because of the complexity associated with implementing product customization, Customizer supports a few distinct approaches to integration projects:

    JavaScript Language Versions

    Reference Implementation

    Customizer experiences come in all shapes and forms: integrated with PDPs or put on standalone pages, used on e-commerce websites, or invoked as a part of a marketing campaign. At Drive Commerce, we believe that the platform tools should not impede any of the creative processes, and instead should enable customers to create unique, engaging customization tools.

    Instead of creating a rigid customizer front-end, the platform instead aims to provide a set of easy to use tools that can be quickly updated to match the creative designs. One of these tools is our reference implementation. The reference implementation is a complete customization experience delivered as both a ready-to-use widget app and the associated source code. This widget application can be easily integrated into the frontend of the target host, which could be an e-commerce website, marketing mini-site, or even inside a native mobile app.

    View it live at http://cz.drrv.co/demo/index.html.

    Access the implementation source code at Git repository https://bitbucket.org/drivecommerce/customizer-reference-implementation

    Quick Start

    Step 1

    <script lang="application/javascript" src="cz.drrv.co/demo/customize-widget.js"></script>
    

    On your target website, determine a page where you would like to show the customization experience. Load the customization widget using a script tag or a dynamic method.

    Step 2

    <div id="customize__placeholder"></div>
    

    Provide an empty placeholder DIV element that will contain the customization experience.

    Step 3

    <script type="text/javascript">
        document.addEventListener("DOMContentLoaded", function InitializeWidget() {
            CustomizeWidget.default.createWidget({
                product: 'WATCH360',
                apiKey: '62SH6h0VIbRh4kHuEkjbHiErBBQGwOmZfYfYd6miqbiABsWrgi4AhfCStHnbNUawwV8wQ2q2foWHVtaHXd5vYFIno0nxN0cT',
                container: document.querySelector('#customize__placeholder'),
    
                on: {
                    addToCart: function (recipe) {
                        alert('Recipe saved as ' + recipe.id + ' at ' + recipe.location);
                    },
                },
            });
        });
    </script>
    

    Note: the example uses a demo API key. Replace it with the one created within the Customizer administration website Account area.

    Initialize the widget by providing the target product ID and authorization API key.

    Done!

    Test out customizer experience within your site.

    What's going on here?

    The customize-widget.js JavaScript file that we loaded in the example is the Single-Page-Application (SPA) that contains the Customizer Reference Implementation code. The code for this application can be in the Git repository above. The app contains all the necessary pieces to talk to the Customizer platform and load the product blueprint, create the front end user experience by analyzing the blueprint and extracting available customization options, and provides a method for generating configured product recipes.

    Widgets

    The reference implementation provides a few out-of-the-box widgets that can be further customized to suit the host site needs. Most of these widgets are controlled using custom attributes that should be defined at the option level.

    Simple Button

    Displays a simple button with a title controlled by the respective option name.

    Attribute Comments
    widget-type Should be set to button value.

    Color Button Widget

    Displays a colored swatch button, optionally with an image based swatch.

    Attribute Comments
    widget-type Should be set to color-swatch value.
    hex HTML style color definition, i.e. six hexadecimal characters.
    pattern-image Optional, swatch image URL.

    Personalization Text

    Displays the input text box. See Personalization section for the description of personalization custom attributes and how they control the input text appearance and functionality.

    Attribute Comments
    widget-type Should be set to personalization value.

    Dynamic Image

    Displays the image upload widget. See Image Upload section for the description of image related custom attributes and how they control the widget appearance and functionality.

    Attribute Comments
    widget-type Should be set to dynamic-image value.

    Customizing the Look & Feel

    The reference app provides a minimalistic yet functional user experience. Further customization that is necessary to better integrate with the host website could happen in a couple of ways:

    Customizing the Code

    Simple CSS customization might be not enough in some cases. To implement more in-depth layout customizations, or introduce some new widget functionality, the reference application code could be modified by a developer to suit the requirements.

    The reference application is build using a number of modern web technologies:

    Building the Widget Code

    Step 1

    git clone https://bitbucket.org/drivecommerce/customizer-reference-implementation.git
    

    Clone the app code.

    Step 2

    Install dependencies

    npm install
    

    Or

    yarn install
    

    Ensure that nodejs and npm are installed, and install app dependencies. Either npm or yarn could be used.

    Step 3

    Run development version

    yarn poi
    

    Run the widget in the test mode...

    Step 4

    Build the distribution package

    yarn poi build
    

    ... or build the distribution package.

    Step 5

    Upload generated customize-widget.js file to your e-commerce or CMS system.

    JavaScript API

    In some cases, the out-of-the-box reference implementation may not be a good fit for the host site requirements. While a lot can be by tweaking and extending the reference code, some requirements may require developers to tap into the JavaScript API directly. The Customizer's JavaScript API provides many classes and helpers that can be used to enhance the app functionality, or be used as building blocks to create totally new experiences.

    Integrating the API

    Main API URL:

    https://api.customizer.drivecommerce.com/api/v2/runtime/client?type=production

    Load the Javascript API using one of the following two methods.

    Dynamic Script Loading

    const clientRoot = 'https://api.customizer.drivecommerce.com/api/v2/runtime/client?type=production';
    
    (function ClientLoader(url, onload) {
        const script = document.createElement('script');
        script.type = 'text/javascript';
        script.onload = onload;
        script.src = url;
        document.head.appendChild(script);
    }(clientRoot, () => {
        // Customizer is now ready for use.
        ...
    }));
    
    

    Dynamic loading is a preferred method of integrating Customizer JavaScript API, as it does not block page functionality while the script is loading and being initialized.

    Static Script Loading

    Add at the end of your body tag

    <script type="application/javascript" src="https://api.customizer.drivecommerce.com/api/v2/runtime/client?type=production"></script>
    

    Page initialization code

    // For example, use jQuery $.ready function to wait until DOM can be safely manipulated.
    $(function () {
        // Customizer is now ready for use.
        ...
    });
    

    The simplest method of integration comes at the cost of blocking page functionality while the script is loading, which may reduce overall page performance.

    API Objects

    The API creates a DriveCustomizer namespace in the global scope that provides following classes:

    Class Purpose
    Controller The main class that implements communication with the Customizer backend and provides product state management and manipulation.
    ImageView Implements 2D stacked-image product rendering approach.
    UndoStack A helper class that implements undo and reset functionality, if required by the UI.

    Controller Class

    Controller is a primary class in the Customizer JavaScript API. It implements communication protocol with the Customizer backend to retrieve product blueprints and save customized recipes, provides product state management and ensures configured product validity, and contains a number of utilities that may be helpful to create rich and robust customization UIs.

    Authorization

    Controller instances require an API key to communicate with the Customizer backend. New API keys can be created as needed in the Account section of the administration website.

    Creating Controller Instances

    const controller = new window.DriveCustomizer.Controller({
        product: 'WATCH360',
    });
    
    controller.load();
    

    To begin working with the controller object, create an instance using the DriveCustomizer.Controller constructor and provide initialization parameters:

    Option
    apiKey The API key that authorized the API usage.
    product The style code of a product to be loaded.
    products The array of style codes to be loaded.
    blueprint Instead of providing product style codes allows specifying the blueprint URL directly.
    currency If using Customizers price calculations provides the current currency ISO code.

    Load Product Information

    controller.load();
    

    Kick-off the customization process by invoking the load method.

    Controller Properties

    Method Comments
    blueprint The currently loaded blueprint definition.
    state The array of current component selections.

    Controller Methods

    Method Comments
    load

    options → void

    Loads product information and begins customization process.

    options Optional parameter overrides, for example a new product list.

    destroy

    void

    Destroys the controller instance and frees the resources.
    products

    [string]

    Gets a list of currently loaded products.
    findProduct

    styleCode Object

    Searches currently loaded blueprint for a product in the list of related products.

    styleCode The product id to find.

    isAvailable

    component boolean

    Checks if component is available, i.e. it is not disabled in the Customize backend, and has sufficient inventory levels.

    component Component

    getPrice

    component number

    Calculates the price of the given component code.

    component Component to calculate the price for

    statePrice

    options → Object

    Calculates the overall state price, including the range of possible prices if different component selections were made.

    options.excludePlacements A list of placement codes to be excluded from the price calculation.

    options.fixedPlacements A list of placement codes that should reflect the current component selection price rather than respective min/max component prices.

    options.ignoreOptional Ignores price of optional components when calculating min/max prices.

    options.ignorePlaceholders Ignores price of placeholder components when calculating min/max prices.

    Returns an object with the current, minimal, and maximum prices based on currently selected state.

    canBuild

    options → boolean

    Checks whether current state can be built, for example if placeholders have been replaced with actual options.

    options.ignoreOptional Allows optional placeholders to remain unfulfilled.

    options.excludePlacements A list of placements to ignore when considering whether the design can be built.

    transferCompatibleState

    from , placements → void

    Transfer a compatible state selections from another to this controller, optionally bringing over only the specified placements. A state selection is considered to be compatible is it matches a placement code and a component can be selected in that placement.
    isSelected

    code boolean

    Checks if a code is selected in the current state.
    acceptableComponents

    placementCode Array

    Finds a list of components acceptable in the placement.

    Returns a list of placement + component objects supported in the placement.

    findComponent

    code Object

    Finds a component object by the given component code.
    findPlacement

    code Object

    Finds a placement object by the given placement code.
    searchComponents

    placementCode , searchOptions → Array

    Find components in the placement that match given options.

    placementCode Placement code.

    searchOptions.code Component option code to search for.

    searchOptions.definition Option definition code to search for.

    updateComponent

    placementCode , componentCode Object

    If the selection is can be made, updates the selected component for the given placement.

    Returns a previously selected component or {} if there was no component selected for the placement.

    updateDynamicImage

    placementCode , options Promise(Object)

    Updates dynamic image reference associated with the placement.

    placementCode The placement to be updated.

    options.title The image title.

    options.title The original image file name.

    options.url The source image URL in the original image format.

    options.pngUrl The URL of the PNG version of the dynamic image.

    options.jpgUrl The URL of the PNG version of the dynamic image.

    commitCustomAttributes

    placementCode , changes Promise(boolean)

    Commits custom attribute changes to a component currently selected in the placement. Modifies .custom attributes map for the component, performs necessary validations, and updates image views as necessary.

    placementCode The placement code. Selected component must have custom attributes to begin with.

    changes The dictionary of custom attributes values changes to be applied to the component

    .

    Returns a promise that resolves into an object specifying whether any changes were actually committed.

    updatePersonalization

    placementCode , text , updateOptions → Promise(Object)

    Updates the personalization text for a placement.

    placementCode The Placement to be updated.

    text The new personalization text.

    updateOptions.noEnforceLimit Don't enforce personalization-limit when accepting new text.

    Returns a promise that resolves to an object:

    { accepted: true } if personalization is accepted as-is

    { accepted: true, as: 'filtered text'} if personalization is accepted in filtered form.

    { accepted: false, lastValid: 'last valid text' } if personalization text is rejected due to configured restrictions.

    Controller Events

    Controllers may emit a number of events that can be used to detect important changes within a controller or provide some additional data to controllers.

    Event Comments
    beforeLoadBlueprint Triggered just before the controller loads a new blueprint.
    afterInitializeState Triggered after the controller had created the initial state vector. .state property can now be used to examine the state.
    afterInitializeBlueprint Triggered after the controller has performed all actions necessary to initialize the product state using a freshly loaded blueprint. .blueprint property can now be used to examine the product blueprint.
    stateChanged Triggered whenever the product selected components, personalization, or customization attributes had changed, due to a user selection or a programmatic change.
    initializeAvailability

    resolved

    Called after the product blueprint has been loaded, but not completely initialized yet to give the host site a chance to retrieve the inventory levels for blueprint components. These inventory levels may later be used to figure out the component availability and update the state vector.

    After the availability state has been retrieved, the host site must invoke the resolve callback.

    isAvailable

    component

    Allows the host site to determine whether the given component is available for customization and selection, e.g. if the component is in stock.
    getPrice

    component

    Allows the host site to override the default price calculation, and provide a custom price for the component.
    repaint Triggered whenever the controller state had changed enough that the related product image needs to be refreshed.

    2D Image Rendering Methods

    A set of methods that assist creation of 2D stacked-image product renderings.

    Method Comments
    makeFrameUrl

    view , state , frame , options → string

    Creates an image URL that renders the product selections made for the given state.

    view Selected view.

    state The selected state vector. The state does not have to match the currently active controller state.

    frame The selected current frame.

    options.beforePlacement Only generate rendering instructions for placements before given placement. Used to create "split" renders to allow for dynamic image customizations, if the dynamic image is overlayed by an another component.

    options.afterPlacement Only generate rendering instructions for placements after given placement.

    options.baseWidth Provides the resulting image width, in case if not using background image elements.

    options.baseHeight Provides the base image height.

    ImageView Class

    ImageView class integrated with the Controller class instances and provides 2D product rendering.

    Creating Image Views

    <div class="product__image">
    </div>
    

    In order to create an image view, the host site must first obtain an instance of a Controller class, as describe above. The host site also needs to define a placement for the future image view, typically an empty DIV element that is sized appropriately to house the product rendering.

    const image = new window.DriveCustomizer.ImageView(controller, {
        container: document.querySelector('.product__image'),
    });
    

    Once the prerequisites are complete, create an instance of the image view as in the example.

    ImageView Events

    Event Comments
    imagesLoading

    state

    Notifies the host of the image view whether product images are being loaded. This allows the host to display the appropriate loading animation. The state parameter may be one of:

    loading Indicates that images are currently being loaded.

    done Loading is complete and a new product image has been rendered.

    ImageView Methods

    Method Comments
    resize Must be called whenever the image view container size is updated.
    destroy Destroys the image view and releases resources.
    selectViewByCode Activates a view with the given code.
    selectedView Returns the currently active view reference.
    selectedFrame Returns the currently active frame reference.
    updateView

    view , frame void

    Updates current image to the specified view.
    repaint Redraws the image view.