@kentico/kontent-smart-link v2.3.1

Kontent Smart Link SDK

Kontent Smart Link SDK can be used to automatically inject smart links to Kentico Kontent according to manually specified HTML data attributes on your website. It also lets you connect your website with Web Spotlight (for faster editing and preview of your content).

Installation

You can install this library using npm or you can use global CDNs such as jsdelivr directly.

npm

npm i @kentico/kontent-smart-link

UMD Bundles

When using UMD bundle and including this library in script tag on your html page, you can find it under the KontentSmartLink global variable. JS bundle and its minified version are distributed in dist folder.

• kontent-smart-link.umd.min.js
• kontent-smart-link.umd.js

CDN

kontent-smart-link.umd.js

https://cdn.jsdelivr.net/npm/@kentico/kontent-smart-link@latest/dist/kontent-smart-link.umd.js

kontent-smart-link.umd.min.js

https://cdn.jsdelivr.net/npm/@kentico/kontent-smart-link@latest/dist/kontent-smart-link.umd.min.js

Usage

Kontent Smart Link SDK uses HTML data attributes to find elements that represent some content items/content components/elements from Kentico Kontent. Then it automatically injects smart links for all of those elements. Injecting smart links to Kontent means that all elements that are marked with special data attributes will be highlighted and made interactive (handle clicks/redirect to Kontent/navigates from the preview in Web Spotlight/etc.).

In order to initialize the Kontent Smart Link SDK on your website, you have to call its initialize or initializeOnLoad method. Both of the previously mentioned methods return an instance of the initialized SDK (initializeOnLoad returns a Promise resolving to instance) that has two methods:

• setConfiguration(config);
• destroy().

The main difference between the two methods is that the initializeOnLoad method will add an event listener to the window load event, and initialize the Kontent Smart Link SDK only when everything on the page has been loaded. That is why it wraps an instance of the SDK into a Promise. Therefore, if you want to initialize the Kontent Smart Link SDK inside the head tag when the page may not be loaded yet, you should probably use initializeOnLoad method.

The SDK uses a query parameter to enable/disable smart link injection. That is why, when the SDK is initialized, it starts listening to query parameters in the URL. The name of the query parameter defaults to ksl-enabled, but can be changed using the configuration argument of the initialize or initializeOnLoad methods or using the setConfiguration method. Only the presence of the query parameter is checked and its value is ignored, so all of the following options are valid: ?ksl-enabled=true, ?ksl-enabled, ?ksl-enabled=1, etc.

Configuration

You can pass the configuration object as a first argument of the initialize, initializeOnLoad or setConfiguration methods.

Data attributes

The Kontent Smart Link SDK highly depends on the data attributes in your HTML markup and it won't work as expected without them. The SDK won't add those data attributes to your HTML, you must add all of those attributes yourself. The SDK will then use those attributes as a source of data (project id, element codename, etc.) when injecting the smart links.

The SDK supports the hierarchical inheritance of data attributes, which means that you don't have to put all of those data attributes on the same item. The parsing process starts with the data-kontent-element-codename attribute and goes up the list trying to find other attributes on the same node or on all of its ancestors (up to the body element).

Usually, you will put data-kontent-project-id and data-kontent-language-codename attributes on a body node so that the project id and language codename values are the same for all elements inside of the body. Next, you will put data-kontent-item-id attributes on all HTML nodes that represent a Kontent item. Then inside of those nodes, you will find all child nodes that represent elements of the Kontent item and put data-kontent-element-codename attribute on them. The SDK will then find all elements that have data-kontent-element-codename attribute, highlight them and make those elements interactive (handle clicks/redirect to Kontent/navigates from the preview in Web Spotlight/etc.).

Content components

Content component is a single-use content, that is also sometimes referred to as one-off, channel-specific, or non-reusable. Content components exist only within a specific rich text element in your content items and become their integral part. This means you won't find components in your list of items in Content Inventory in Kontent.

You should use data-kontent-component-id attribute to specify that something represents a content component in your HTML, so that the SDK knows that this item has no separate page in the Kontent and must be opened in the context of its parent content item.

iFrame Communication

When running inside an iframe element, the Kontent Smart Link SDK will send iframe messages to the parent window instead of redirecting user to the Kontent page. This is needed for the SDK to work properly inside Web Spotlight.

Customization

The following custom CSS properties can be used to customize the visuals of the SDK output.

Examples

HTML & UMD & CDN

<html>
    <head>
        <title>Kontent Smart Link - HTML example</title>
        <script type="text/javascript" src="https://cdn.jsdelivr.net/npm/@kentico/kontent-smart-link@2.0.0/dist/kontent-smart-link.umd.min.js"></script>
        <script type="text/javascript">
            KontentSmartLink.initializeOnLoad({queryParam: 'preview'});
        </script>
    </head>
    <body data-kontent-project-id="1d50a0f7-9033-48f3-a96e-7771c73f9683" data-kontent-language-codename="default">
        <div class="home" data-kontent-item-id="af858748-f48a-4169-9b35-b10c9d3984ef">
            <img class="home__banner" data-kontent-element-codename="image" />
            <h1 data-kontent-element-codename="text">...</h1>
        </div>
    </body>
</html>

ES6

import KontentSmartLink from '@kentico/kontent-smart-link';

const kontentSmartLink = KontentSmartLink.initializeOnLoad({
    projectId: '1d50a0f7-9033-48f3-a96e-7771c73f9683',
    languageCodename: 'default',
    queryParam: 'preview',
});

Next.js

In order to use the SDK with the Next.js framework you can either initialize it separately on each page or initialize it once for the whole application using the _app.jsx file. Do not forget to destroy() SDK for it to work properly.

// _app.jsx
import KontentSmartLink from '@kentico/kontent-smart-link';

const MyApp = ({
  Component,
  pageProps,
}) => {
  useEffect(() => {
    const kontentSmartLink = KontentSmartLink.initialize({
      queryParam: 'preview-mode'    
    });
    return () => {
      kontentSmartLink.destroy();
    }; 
  });
 
  return <Component {...pageProps} />;
};

Gatsby

You can either initialize the SDK on every page or use a layout to initialize the SDK while using Gatsby. Do not forget to destroy() SDK for it to work properly.

// src/components/layout.jsx
import KontentSmartLink from '@kentico/kontent-smart-link';

export default function Layout({ children }) {
    useEffect(() => {
        const kontentSmartLink = KontentSmartLink.initialize({
          queryParam: 'preview-mode'    
        });
        return () => {
          kontentSmartLink.destroy();
        }; 
    });

    return (
      <div class="layout">{children}</div>
  );
}

Tests

Unit tests

Since this SDK highly depends on browser APIs, the unit tests are run by Karma test runner (+ Jasmine) inside Chrome browser. To run all tests in a watch mode you can use the npm run test:unit command. To run all tests only once you can use the npm run test:unit:ci command. All unit tests are located in the test-browser folder.

Visual regression tests

Visual regression testing is implemented using Storybook and Loki. Each story in Storybook represents a test case, which is then used by Loki to generate screenshots. In order to run visual regression tests you need to start Storybook using the npm run storybook command and then start loki testing using the npm run test:visual command. Or you can use the npm run test:visual:ci command to automatically start the Storybook server in a CI mode and run visual tests.

Visual regression tests use the built version of SDK, so before running them make sure you rebuild the SDK after the last change you made. You can this using the npm run build command or using the npm run dev command to start build in a watch mode.

Feedback & Contribution

Feedback & Contributions are welcomed. Feel free to take/start an issue & submit PR.