UGC Widgets
    Preparing search index...

    Interface PlacementSDK

    The Placement SDK provides methods for interacting with the widget's placement, including DOM access, custom styles, templates, and component management. Use this SDK to access placement DOM nodes, inject styles or templates, manage loaded components, and interact with the widget's shadow DOM.

    interface PlacementSDK {
        addCSSImportUrl: (url: string) => Promise<void>;
        addCSSToComponent: (css: string, componentName: string) => void;
        addLoadedComponents: (components: string[]) => void;
        addSharedCssCustomStyles: (
            key: string,
            content: string,
            componentNames: string[],
        ) => void;
        addTemplateToComponent: (template: Template, componentName: string) => void;
        addWidgetCustomStyles: (content: string) => void;
        getCustomTemplate: (component: string) => undefined | Template;
        getElement: () => undefined | HTMLElement;
        getExpandedTiles: () => HTMLElement;
        getLoadedComponents: () => string[];
        getNodeId: () => undefined | string;
        getPlacement: () => Placement;
        getShadowRoot: () => ShadowRoot;
        getWidgetId: () => string;
        getWidgetTemplateSettings: () => MyWidgetSettings;
        isComponentLoaded: (component: string) => boolean;
        loadTemplate: (
            templateType: string,
            scope?: TemplateScope,
        ) => Promise<void>;
        storeWidgetTemplateSettings: (settings: MyWidgetSettings) => void;
    }
    Index

    Properties

    addCSSImportUrl addCSSToComponent addLoadedComponents addSharedCssCustomStyles addTemplateToComponent addWidgetCustomStyles getCustomTemplate getElement getExpandedTiles getLoadedComponents getNodeId getPlacement getShadowRoot getWidgetId getWidgetTemplateSettings isComponentLoaded loadTemplate storeWidgetTemplateSettings

    Properties

    addCSSImportUrl: (url: string) => Promise<void>

    Allows the addition of CSS at the root of the widget

    // Import an external CSS file
    // await sdk.addCSSImportUrl('https://example.com/styles.css');
    addCSSToComponent: (css: string, componentName: string) => void

    Allows the addition of CSS to a particular component This allows for custom styling of components

    // Add custom CSS to the 'shopspots' component
    // sdk.addCSSToComponent('.shopspot { color: blue; }', 'shopspots');
    addLoadedComponents: (components: string[]) => void

    Allow loading of local UGC components or third-party components

    // Add a custom component to the placement
    sdk.addLoadedComponents(['shopspots']);
    addSharedCssCustomStyles: (
        key: string,
        content: string,
        componentNames: string[],
    ) => void

    Allows injection of css styles into all the shadow root of the widget container This avoids duplicating individual injection into each custom components Used for css styles that are shared across all the nested shadow DOMs ref: https://developer.mozilla.org/en-US/docs/Web/API/Web_components/Using_shadow_DOM#constructable_stylesheets

    // Add shared CSS to multiple components
    // sdk.addSharedCssCustomStyles('shared', 'span { color: red; }', ['shopspots', 'products']);
    addTemplateToComponent: (template: Template, componentName: string) => void

    Allows the addition of a template to a particular component This overrides the existing template of the component provided.

    // Add a custom template to the 'products' component
    // sdk.addTemplateToComponent('<div>My Product</div>', 'products');
    addWidgetCustomStyles: (content: string) => void

    Allows injection of css styles above the shadow DOM under placement div Used only for special cases where certain styles like @font-face don't work in shadow DOM

    // Inject a custom font-face style
    // sdk.addWidgetCustomStyles(`@font-face { font-family: 'MyFont'; src: url('myfont.woff2'); }`);
    getCustomTemplate: (component: string) => undefined | Template

    Get the custom template for a component

    // Get the custom template for the expanded-tiles component
    // This would generally be used for debugging, to see that your custom template is registered correctly.
    const template = sdk.getCustomTemplate('expanded-tiles');
    console.log('template registered', template);
    getElement: () => undefined | HTMLElement

    Get the element of the placement

    // Get the placement element and add a class
    const el = sdk.getElement();
    if (el) el.classList.add('my-widget');
    getExpandedTiles: () => HTMLElement

    Type declaration

      • (): HTMLElement

      • Returns HTMLElement

        HTMLElement

    Get the expanded tiles in DOM

    // Get the expanded tiles container element
    const expanded = sdk.getExpandedTiles();
    expanded.querySelectorAll('.ugc-tile').forEach(tile => tile.classList.add('highlight'));
    getLoadedComponents: () => string[]

    Type declaration

      • (): string[]

      • Returns string[]

    Get loaded components

    // List all loaded components
    const loaded = sdk.getLoadedComponents();
    loaded.forEach(c => console.log(c));
    getNodeId: () => undefined | string

    Type declaration

      • (): undefined | string

      • Returns undefined | string

    Get the node id of the placement in use. This is helpful when accessing the placement in the ugc globals

    Get the node id and use it to find the widget
    const nodeId = sdk.getNodeId();
    const widget = window.ugc.getWidgetBySelector(nodeId);
    getPlacement: () => Placement

    Type declaration

      • (): Placement

      • Returns Placement

    Get the placement object - please note that this object may change so it is recommended to use the methods provided by this SDK

    // Access the raw placement object
    const placement = sdk.getPlacement();
    getShadowRoot: () => ShadowRoot

    Get the shadow root inside the placement

    // Access the shadow root and append a style
    const root = sdk.getShadowRoot();
    root.appendChild(document.createElement('style'));
    getWidgetId: () => string

    Get the current widget id

    // Log the widget id
    console.log(sdk.getWidgetId());
    getWidgetTemplateSettings: () => MyWidgetSettings

    Type declaration

      • (): MyWidgetSettings

      • Returns MyWidgetSettings

    Get the widget template settings

    // Retrieve template settings and log them
    const settings = sdk.getWidgetTemplateSettings();
    console.log(settings);
    isComponentLoaded: (component: string) => boolean

    Check if a component is loaded

    Check if 'shopspots' is loaded
    if (sdk.isComponentLoaded('shopspots')) {
      // do something
    }
    loadTemplate: (templateType: string, scope?: TemplateScope) => Promise<void>

    Load a template into the placement, i.e. carousel, quadrant, etc.

    // Load the 'carousel' template for the widget
    // await sdk.loadTemplate('carousel');
    storeWidgetTemplateSettings: (settings: MyWidgetSettings) => void

    Store the widget template settings

    // Save custom template settings
    // This utility is used in widget-utils to merge settings with defaults.
    sdk.storeWidgetTemplateSettings(({
       features: {
         showTitle: true,
         preloadImages: true,
         disableWidgetIfNotEnabled: true,
         addNewTilesAutomatically: true,
         handleLoadMore: true,
         hideBrokenImages: true,
         loadTileContent: true,
         loadTimephrase: true,
         ...settings?.features
       },
       callbacks: {
         ...callbackDefaults,
         ...settings?.callbacks
       },
       templates: settings?.templates ?? {},
       config: settings?.config ?? {}
       }
     );

    Settings

    Member Visibility

    On This Page

    Properties