Content creators sometimes need to correct errors or typos when they see them on preview of your website or app. Add edit buttons to your app to let your content creators quickly edit content in Kontent.ai.To make the authoring experience even better, set up automatic refresh for preview to see the latest changes without any hassle.
Use the Smart Link SDK in your preview environment so that your web apps automatically create clickable regions on your pages.Clicking the regions will open a specific content item in Kontent.ai. These regions are based on annotations in your HTML code. You need to annotate the HTML with data attributes so the Smart Link SDK knows where the content comes from.To create a smart edit link to a content item in Kontent.ai, the Smart link SDK needs to know several things, such as your environment ID, language, and content item ID. You can also provide details about specific elements or components within a content item in your HTML code.For example, you can annotate your HTML code like so:
In your website’s <body>, specify the environment ID using data-kontent-environment-id="1d50a0f7-9033-48f3-a96e-7771c73f9683" and language using data-kontent-language-codename="en-US".
(Optional) In a <p>, specify the codename of an element using data-kontent-element-codename="body".
When you initialize the Smart link SDK, it looks at these data attributes and uses them to create a URL such as https://app.kontent.ai/goto/edit-item/project/1d50a0f7-9033-48f3-a96e-7771c73f9683/variant-codename/default/item/af858748-f48a-4169-9b35-b10c9d3984ef/element/body.
You can also specify identifiers for content components using data-kontent-component-id so that your content creators can enjoy an even better editing experience.
In native apps that don't return HTML, you need to construct the edit links manually. The edit links are based on a pattern with variables that you fill in based on what content your app displays on preview.
To create edit links for specific content items, construct your links using the following URL pattern.
Replace YOUR_ENVIRONMENT_ID, LANGUAGE_CODENAME, and ITEM_ID with the actual values from your project.
Example URL: https://app.kontent.ai/goto/edit-item/project/8d20758c-d74c-4f59-ae04-ee928c0816b7/variant-codename/en-US/item/4d4dc14d-8c7c-471f-b797-c6694c604964
Replace YOUR_ENVIRONMENT_ID, LANGUAGE_CODENAME, ITEM_ID, and ELEMENT_CODENAME with the actual values from your project.
Example URL: https://app.kontent.ai/goto/edit-item/project/8d20758c-d74c-4f59-ae04-ee928c0816b7/variant-codename/en-US/item/4d4dc14d-8c7c-471f-b797-c6694c604964/element/related_articles
You can also link to a content item nested in a linked items or rich text element in another item. The structure of the linked relationship will be reflected in Kontent.ai in the breadcrumbs for easy navigation.
Automatic refresh in both the preview and Web Spotlight makes live editing easier for content creators. Whenever a content change is propagated to Delivery Preview API, you can have the Smart Link SDK update the content preview for you.
For your web apps to support automatic refresh for content preview, make sure that your preview environment:
Sets the X-KC-Wait-For-Loading-New-Content header to true when fetching data from the Delivery Preview API.
If these conditions are met, the preview and Web Spotlight will wait for your changes to be ready via the Delivery Preview API, and after that, the previews will be refreshed automatically.
If you want the changes to show instantly in your preview, we recommend implementing Live preview.
In some cases, refreshing the page might not be enough. For example, if you use a static site generator for your preview, you need to trigger the rebuild of the page before refreshing it. Or maybe you don’t want to refresh the entire page when a single item has been updated and would rather re-render only the affected place in the UI.
That's why the Smart Link SDK supports the custom refresh handler, which allows you to specify how your web page reacts to refresh events received from Web Spotlight.
With live preview, you can set up your app so that it instantly reacts to content changes. This real-time feedback leads to a better editing experience for content creators.
Compared to automatic refresh, the live preview doesn’t rely on updates in the Delivery Preview API. Instead, it propagates content changes from Kontent.ai to your app immediately.
For your web app to support the live preview, make sure that your preview environment:
Contains custom logic to perform content updates based on messages from iframe communication. You need to define how your app responds to the update messages. Learn how to set up the live preview with Smart Link SDK.
Once you adjust your web app, the live preview becomes automatically available in both preview and Web Spotlight. Smart Link SDK detects the upcoming update messages and triggers your custom logic to handle the changes in the live preview.
Live preview works for the following elements: asset, date & time, linked items, multiple choice, number, rich text, subpage, taxonomy, text, and URL slugs.
The live preview only returns codenames for linked items and subpages elements. You can re-fetch the content of the linked items via Delivery Preview API.Â
Rich text with linked items is also returned only as codenames in the live preview. However, the content of the components will return as usual, as they’re part of the rich text.
// Tip: Find more about JS/TS SDKs at https://kontent.ai/learn/javascriptimport KontentSmartLink, { KontentSmartLinkEvent,} from '@kontent-ai/smart-link';// Initializes the Smart Link SDK using your environment ID and language codenameconst sdk = KontentSmartLink.initialize({ defaultDataAttributes: { environmentId: 'KONTENT_AI_ENVIRONMENT_ID', languageCodename: 'default', },});sdk.on(KontentSmartLinkEvent.Refresh, (data, metadata, originalRefresh) => { // Place for your custom refresh logic originalRefresh(); // If you want to refresh the page at the end});
Edit links | Kontent.ai Learn
Explore your path to mastery
With Web Spotlight or live preview, you can set up edit links on any part of your content, such as headings, tables, embedded content, and text.
Preview doesn't support edit links inside the content item. However, edit links are supported when previewing separately in a different tab and also in Web Spotlight.
Make sure you render the data attributes and edit links only in preview environment. In most cases, you want to display the edit links only in a preview environment that your editors can access. You can also use them in production – it's up to you to limit their visibility according to your needs.
When users click the edit links, Kontent.ai checks if the user has access to the specified content item.
When users click the edit links, Kontent.ai checks if the user has access to the specified content item and element.
No edit links for content componentsYou can't link directly to elements nested in content components. You can only link to the highest-level rich text element in which the component is nested.
If you're already using Smart Link SDK in Web Spotlight, your preview will also be able to automatically refresh. Otherwise, if Smart Link SDK is not implemented, you can manually refresh your preview to see the latest content changes.
The Changes are ready status is only available in Web Spotlight. The status in Web Spotlight is displayed when the changes are available in the Delivery Preview API, not when the preview page has already been refreshed. If your custom refresh handler takes some time to finish, make sure to inform your users by displaying a loader or message inside the preview.
Live preview requires Smart Link SDK version 3.2.0 or newer.
Jan Cerman
10 minutes
Preview / Web Spotlight
in your preview environment so that your web apps automatically create clickable regions on your pages.
Clicking the regions will open a specific content item in Kontent.ai. These regions are based on annotations in your HTML code. You need to annotate the HTML with data attributes so the Smart Link SDK knows where the content comes from.
To create a smart edit link to a content item in Kontent.ai, the Smart link SDK needs to know several things, such as your environment ID, language, and content item ID. You can also provide details about specific elements or components within a content item in your HTML code.
For example, you can annotate your HTML code like so:
Add buttons in preview can be set up in a similar way to smart links:
Changes are ready status is only available in Web Spotlight. The status in Web Spotlight is displayed when the changes are available in the Delivery Preview API, not when the preview page has already been refreshed. If your custom refresh handler takes some time to finish, make sure to inform your users by displaying a loader or message inside the preview.