Motivation

Right now if the website connected to the SDK is run inside of an iframe (other than WS), the redirect feature and Web Spotlight features (enable/disable editable elements, in-context editor, etc.) won't work. This happens because the SDK assumes that the iframe, it is being run inside of, is a Web Spotlight preview iframe and tries sending messages to this iframe which are left unprocessed. Currently, there is no way to override this behavior.

Proposed solution

First of all, we need to decide whether we want to somehow fix this issue or not. There are several possible solutions that can be used to solve it:

• We can add a boolean flag to the SDK configuration object that will allow users to disable the iframe communication. This way when someone wants to wrap a website connected to the SDK with an iframe, they can disable the iframe communication feature and smart links will always open Kontent in a new tab instead of sending iframe messages. The main disadvantage of this method is that without the iframe communication smart links will open Kontent in a new tab even in Web Spotlight because Web Spotlight requires iframe communication to work properly.
• We can add some public helpers to SDK that will help users with this problem (more information about this can be found in the Workaround section of this issue).

Workaround

If you plan on using the website (connected to the SDK) inside of an iframe, you can use this workaround to make everything work properly with Web Spotlight.

The first thing you need to do is listen to all message events on your host page window object.

window.addEventListener('message', handleMessage);

Then whenever you receive a new message, you need to check whether it is a message related to SDK. If it is related to the SDK, you need to check if you are currently inside an iframe and if you aren't, you just generate a smart link (using buildKontentLink helper from @kentico/kontent-smart-link) and open it in a new tab. If you are inside an iframe, you need to check the direction of the received message (upwards from inner iframe/downwards from parent window) by comparing the source of this event to the iframe content window. Finally, you need to resend the whole event to the parent window or inner iframe according to the event direction.

import { buildKontentLink } from '@kentico/kontent-smart-link';

function handleMessage(event) {
  const eventTypeRegex = /^kontent-smart-link:/;
  
  // check if this message is not related to the SDK
  if (!event.data || !event.data.type || !eventTypeRegex.test(event.data.type)) {
    return;
  }

  const isInsideIFrame = window.self !== window.parent;
  const message = event.data;

  if (isInsideIFrame) {
    // The iframe variable has a reference to the iframe element.
    // You don't have to use document.querySelector here, for example,
    // in React you can use `useRef` hook to save the reference and then 
    // use it here, in Vue you can use `$refs`, etc.
    const iframe = document.querySelector('#your-iframe-id');
    const isMessageGoingUpwards = event.source === iframe.contentWindow;

    if (isMessageGoingUpwards) {
      // resend this message to the parent window
      window.parent.postMessage(message, '*');
    } else {
      // resend this message to the iframe
      iframe.contentWindow.postMessage(message, '*');
    }
  } else if (message.type === 'kontent-smart-link:element:clicked') {
    const link = buildKontentLink(event.data.data);
    window.open(link, '_blank');
  }
}

Additional context

Add any other context, screenshots, or reference links about the feature request here.

Motivation

Manually adding element attributes can be rather repetitive, especially for add buttons, where multiple attributes need to be specified. This could be mitigated to some extent by including helper methods in the SDK.

Proposed solution

Add a set of helper methods which will create the required attributes for each available smartlink button based on user-provided values. See example implementation in our sample app source code.

Motivation

It would be great to have z-index CSS property of overlay (border with pencil).

I have my menu with z-index:10002 (inherited from template) , so I would appreciate being able to customize that.

Proposed solution

Make ti a part of the configuration

Additional context

Add any other context, screenshots, or reference links about the feature request here.

Motivation

Edit item is effectively a superset of Edit element, the latter being available both in WSL and standard preview. As such, it would make sense to allow Edit item to be rendered in preview as well, as a similar functionality can be achieved by using the first element of an item to render Edit element button, which seems like an unnecessary workaround.

Proposed solution

Make Edit item button available outside web spotlight context.

Brief bug description

While using SmartLink SDK in Web Spotlight, when data-kontent-language-codename is missing, the error:
Logger.js:15 [KSL][Error]: Project ID is required to handle element click.

is logged to the browser console, even if the kontent-data-project-id attribute is set correctly in the markup.

Repro steps

1. Open up a WSL project with SL SDK
2. Remove the data-kontent-language-codename attribute using Chrome DevTools
3. Click a SL SDK edit button
4. See browser console error in DevTools

Expected behavior

The console should only report that there is an issue with the language codename element, not the project ID.

Test environment

• Platform/OS: Windows 10, gatsby-starter-kontent-lumen sample site, gatsby-source-kontent 7.2.0, SL SDK v2.1.0
• Browser Chrome
• Version 96.0.4664.110

Screenshots

Brief bug description

In some cases, links are not highlighted (no dashed border and edit icon). However, they are clickable and lead to the correct place in KK admin.
Could be duplicate of #21

Expected behavior

Smart links should be highlighted.

Additional context

I implement this in the KK Docs and I experience the issue on article pages like https://docs.kontent.ai/tutorials/set-up-kontent/set-up-your-project/projects (Smart links are not on the live site. However if you try to implement Smart links on that page, you will experience the issue.) This is a classic Express.js site with full server-side rendering. Smart links JS and CSS files are loaded using CDN.

I noticed that on pages that have the issue, the "kontent-smart-link-overlay" element gets rendered twice. See the screenshot linked below. Maybe this could be related to the issue.

Screenshots

https://prnt.sc/xlg4j8

Brief bug description

When using the latest version of Kontent Smart Link (v2.1.0), the :host CSS properties will be overidden by any higher-order CSS selector. For example, Tailwind CSS's Preflight sets all border width's to 0. This causes the :host border-width to be ignored, and the border width to be set to 0. This causes the spotlight overlay to be hidden.

This can be remediated by flagging the appropriate properties as !important:

Repro steps

1. Create a page using a higher-order CSS selector (such as those used by Tailwind CSS's Preflight)
2. Observe - no spotlight overlay will show
3. Add the !important flag
4. Observe - overlay will show

Expected behavior

The overlay should display.

Test environment

• Platform/OS: Windows 10
• Browser: Firefox
• Version: 89.0.2 (64-bit)

Additional context

Add any other context about the problem here.

Screenshots

Add links to screenshots, if possible.

Brief bug description

When the add button is on the edge of the preview page inside iFrame, the tooltip and toolbar are not shown correctly.

Expected behavior

The add button and its tooltip should be fully visible even on the edge of the screen.

Screenshots

Brief bug description

Using this SDK is problematic under node.js (e.g. when using Angular universal = SSR) because SDK directly invokes browser specific API - MutationObserver (https://github.com/Kentico/kontent-smart-link/blob/e173a36628ccfb851a0f54b93a965957b3d3e309/src/lib/NodeSmartLinkProvider.ts#L44)

In such cases you get ReferenceError: MutationObserver is not defined exception.

This SDK should check whether the API is available and use Polyfills (if available for our use case) or use different API alltogether specific to Node.js. When using API specific do Node.js, be sure to "exclude" this code publicly exported API that might be used in browser where this API is not available as it might prevent you from building the library with Typescript/Webpack etc.. Careful testing is needed for this to work both in node.js & browsers.

If none of this is possible, we should add a disclaimer that node.js is not supported, but I don't think that should be our goal as this should be quite common use case.

Brief bug description

What went wrong?
When developing an application with multiple URLs endpoints for the web, we need the ability to use SmartLink on different domains. In my scenario, I'm using an Azure Function to determine which URL should be used to preview content based primarily on the collection that the content belongs to. This performs a 302 redirect to the correct URL.

The issue then arises that Smark Link forces the origin and the preview URL to match. If they do not, an error is raised and the SmartLink SDK will not render. This is not compatible with the omnichannel narrative and ties Kontent to only being capable of supporting a single web application.

Repro steps

1. Set a preview URL for a content type to link to an Azure Function (or another API endpoint) that will redirect to another domain containing the application.
2. Configure preview mode and SmartLink in the target web application
3. View page in web spotlight
4. View error in console - SmartLink does not render.

Expected behavior

SmartLink should open regardless of the different origin.

Test environment

• Platform/OS: [e.g. .NET Core 2.1, iOS]
• Browser [e.g. chrome, safari]
• Version [e.g. 22]

Additional context

Other use cases here/scenarios are being able to provide a customer support portal, consumer-facing and B2B web application from the same project in Kontent.

If the concern/reason for this restriction is related to security, I'd rather make a 'secret' available in my applications that can be validated that the current implementation or the ability to add preview URL aliases. Simply preventing it (and also not documenting that limitation as far as I can see) is making working with Web Spotlight less of a delight than it could/should be :)

Screenshots

Add links to screenshots, if possible.

My preview URL for the above image looks like this: https://gr-schedule.azurewebsites.net/api/gr-preview-url?secret=1234&cn={Codename}&col={Collection}&l={Lang}&url={URLSlug}

Motivation

In some scenarios, it would be handy to have an option to hide some of the features which are not desirable in a given context. Take these examples

• I want to show a relative add-button on an element. To do that I need to add an itemId attribute on that element. The itemId attribute will also render the edit-button, which I don’t want here. => I can’t hide the edit-button while keeping the add-button, without resorting to some wrapper and css workaround, which is cumbersome.
• by default, the edit button functionality extends to the whole area of the element it's enabled for. this can be potentially undesirable in situations where the overlaid content includes some interactive/clickable buttons, in which case smartlink needs to be disabled.

Proposed solution

Provide more configuration options, which would allow disabling unwanted features either per element basis (e.g. using an optional boolean attribute) or globally

Additional context

Add any other context, screenshots, or reference links about the feature request here.

Motivation

Some of the smartlink features are only available in WSL environment. While understandable from customer's point of view, it would make development easier if there was an option to display all buttons in a regular preview.

Proposed solution

Add a toggle in the SDK initialization or as a query parameter, which would display all buttons, regardless of the environment the site is rendered in.

Brief bug description

When the SDK is initialized inside of the main Vue component (App.vue) using lifecycle methods (mounted, destroyed), smart links are not highlighted (there is no blue border around Kontent elements), but clicking on the element still redirects you to Kontent.

Expected behavior

Smart links should be highlighted on the first load of Vue application as they are highlighted in React applications.

Additional context

I investigated it a little and found out that the problem is probably here in the relevantMutations computation condition. We used && in this condition between addedNodes and removedNodes, because we mostly tested this SDK using React application and React always tries to make as many changes to DOM in one mutation as possible, that is why there are always both removedNodes and addedNodes. But as I found out today Vue separates additions and removals into separate mutations and this condition is never met. Replacing it with something like this should fix the problem:

const relevantMutations = mutations.filter(
  (mutation) =>
    mutation.target instanceof Element &&
    mutation.type === 'childList' &&
    ![HighlighterElementTag, HighlighterContainerTag].includes(mutation.target.tagName) &&
    (Array.from(mutation.addedNodes).some((node) => (node as HTMLElement).tagName !== 
    HighlighterElementTag) ||
    Array.from(mutation.removedNodes).some((node) => (node as HTMLElement).tagName !== 
    HighlighterElementTag))
);

Motivation

In some situations, while developing data attributes, it is difficult to verify that edit buttons will show properly on the webpage: e.g. if I want to use kontent-smart-link-enabled query param in an application which does not keep query params between links/redirects, I would need to do changes in routing just for this sake.

Proposed solution

It would be nice to allow developers enable/disable edit buttons on some specific page without refresh or altering query params. E.g. some developer toolbar.

Motivation

For our website, we have a preview stage separated from the production site. On that preview stage, we want to have smart links always injected. However, as the SDK requires a query parameter to enable smart link injection, editors must add that parameter by themselves which is annoying. Another possible solution is to inject that query parameter programmatically which is annoying too.

Proposed solution

Allow the queryParam to accept an empty string which would result in the smart link injection with no query parameter. Any other reasonable type of configuration that would result in the smart link injection with no query parameter is acceptable too.

Brief bug description

What went wrong?
After adding a data-kontent-add-button & data-kontent-element-codename attributes to a div, the + button appeared next to a related items field in the preview, but clicking it greyed it out and gave a JS exception in the console:

The console suggests theres no language, project, content item or element codename set, however all are set in parent html elements.

Repro steps

1. Create a content item with a related items field.
2. Set the codename to "related_pages"
3. Create a content item, and add some pages to the related pages field from 2.
4. Note the content item id
5. Setup a page with this sample html:

<body data-kontent-language-codename="en-GB" data-kontent-project-id="YOUR PROJECT ID">

    <div class="page-container" data-kontent-item-id="<The content item id from 4. that has the related_pages field>">

          <div class="related-pages" data-kontent-element-codename="related_pages" data-kontent-add-button>
               <h1>Example related page list item 1</h1>
               <h1>Example related page list item 2</h1>
           </div>

      </div>

</body>

6. View this page on the web spotlight preview area (might require setting up the content item as a subpage of homepage)
7. Click the + button next to the example h1s
8. See the error in the console.

Note: This doesnt occur as soon as you add data-kontent-item-id="<The content item id from 4. that has the related_pages field>" to the .related-pages html element.

Expected behavior

Like the other data-kontent tags, Id expect the kontent-item-id to be inherited based on the hierarchy for use on the kontent-element's button, as per the readme:

'Although it is possible to put all previously specified data attributes on the same DOM node, you don't have to do it. We recommend you set data attributes hierarchically so that you don't have to duplicate the same attributes.'

Test environment

• Platform/OS: .NET Core 5, Windows 11
• Browser Chromium
• Version 99

Motivation

Depending on the server's settings, it might be necessary to adjust the X-Frame-Options header in order to make Web Spotlight work flawlessly.

Proposed solution

Add a Troubleshooting section to the README. This new section should explain the problem, outline the possible solutions, and refer to appropriate detailed resources.

Additional context

This was pointed out to me by @Simply007 at kontent-ai/sample-app-net@384efb0#r44481635
This can serve as an example for .NET-based solutions.

Motivation

In the product, we're using environment ID as the name of the identifier, but the Smart Link SDK still uses the data-kontent-project-id attribute, which is confusing to users.

Proposed solution

Update the SDK to use data-kontent-environment-id instead because that's what you can get in the product UI.

Brief bug description

I have tried to render the web spotlight and if I use it on pretty long article text, the border and the pencil is not rendered. The click-through is working still.

I don't see the <kontent-smart-link-element> tag in <kontent-smart-link-overlay> tag in html.

Repro steps

1. Clone https://github.com/Kentico/gatsby-starter-kontent-lumen/tree/webspotlight
2. npm i # should copy .env.template and name it .env
3. npm run develop
4. Enter http://localhost:8000/articles/humane-typography-in-the-digital-age/?preview-mode=true

Expected behavior

I expect to have a pencil and border no matter what 😄

Additional context

If I un-zoom the page the border is rendered.