Get Started with Live Preview Utils SDK V2.0

Note: Use Live Preview Utils SDK version 3.0 or later for improved compatibility with the latest feature updates.

The Live Preview Utils SDK version 2 allows you to listen to entry change events triggered by the Contentstack app and update your website in real time. You can also configure the “Edit” button functionality to enhance collaboration and content editing workflows.

Prerequisite

• Node.js version 4.4.7 or later

Installation and Setup

To install the live-preview-utils package via npm, run the following command:

npm install @contentstack/live-preview-utils

Alternatively, include the live-preview-utils package directly in your website’s HTML code:

<script type='module'>
  import ContentstackLivePreview from 'https://esm.sh/@contentstack/live-preview-utils@2.0.0';
  ContentstackLivePreview.init({
      stackDetails: {
          apiKey: "your-stack-api-key",
      },
  });
</script>

Initialize the SDK

To initialize the Live Preview Utils SDK, import and execute the following command:

import ContentstackLivePreview from "@contentstack/live-preview-utils";
ContentstackLivePreview.init({
    stackDetails: {
        apiKey: "your-stack-api-key",
    },
});

Alternatively, initialize the SDK inside the HTML tag using the ContentstackLivePreview.init() method:

<script>
    ContentstackLivePreview.init({
        stackDetails: {
            apiKey: "your-stack-api-key"
        },
    });
</script>

init(config: IConfig)

The init() method initializes the Live Preview Utils SDK by setting up the necessary event listeners. It accepts a configuration object with the following properties:

enable

The enable property determines enablement or disablement of Live Preview communications.

ssr

The ssr property defines the data update strategy for previewed content based on your app's rendering approach (Server-Side Rendering or Client-Side Rendering).

• ssr: true: For SSR apps, requests a fresh HTML page on each content edit.
• ssr: false: For CSR apps, the app listens to entry changes and updates the page content dynamically.

Note: In CSR mode, the stackSdk property is required. Passing this object will automatically switch the mode to CSR, allowing you to override the default behavior.

editButton

The editButton object lets you manage the "Edit" button. It includes the following properties:

enable

The enable property displays or hides the "Edit" button.

exclude

The exclude property provides an option to exclude the "Edit" button from either inside or outside the Live Preview portal.

The array accepts the following string values:

• insideLivePreviewPortal: Used when you want to remove the "Edit" button from within the Live Preview portal.
• outsideLivePreviewPortal: Used when you want to remove the "Edit" button from outside the Live Preview portal.

Note: Although you have excluded the "Edit" button for Live Preview, you can add the cslp-buttons query parameter in your website URL to display the "Edit" button outside of your Live Preview-enabled website.

includeByQueryParameter

The includeByQueryParameter property overrides the cslp-buttons query parameter to enable/disable the "Edit" button.

position

The position property places the "Edit" button in predefined positions (e.g., top-right, bottom-center).

Note: The default position of the "Edit" button is set to "top". In a collaborative work environment, you can manually position the “Edit” button on your website using the data-cslp-button-position attribute.

Example Configuration:

ContentstackLivePreview.init({
    editButton: {
        enable: true,
        position: "top-right",
    },
});

cleanCslpOnProduction

The cleanCslpOnProduction object removes data-cslp attributes from the website if enable is set to false.

stackDetails

The stackDetails object contains stack-specific information for redirection to the corresponding entry whenever you use edit tags within your website.

stackDetails: {
    apiKey: "string", //api_key of the stack
    environment: "string",
    branch: "string"
}

Note: If you do not use live edit tags, then you don't need to use the stackDetails property.

clientUrlParams

The clientUrlParams object specifies the stack's URL details for your webpage content. By default, it is configured for the North American (NA) region.

//For North American Region
{
    protocol: "https",
    host: "app.contentstack.com",
    port: 443
}
//For European Region
{
    protocol: "https",
    host: "eu-app.contentstack.com",
    port: 443
}
//For Azure EU Region
{
    protocol: "https",
    host: "azure-eu-app.contentstack.com",
    port: 443
}
//For Azure NA Region
{
    protocol: "https",
    host: "azure-na-app.contentstack.com",
    port: 443
}
//For GCP NA Region
{
    protocol: "https",
    host: "gcp-na-app.contentstack.com",
    port: 443
}

Note: Use the clientUrlParams object only when you need to customize the URL.

stackSdk

The stackSdk object represents the Stack class obtained by executing the Contentstack.Stack() method. It is essential for Client-Side Rendering (CSR) to inject the Live Preview hash and content type UID into the Stack class.

Properties and Methods

This section explains the essential properties and methods provided by the Live Preview Utils SDK to handle real-time content updates.

onLiveEdit(callback: () => void)

The onLiveEdit method updates the content displayed in the Live Preview panel whenever an entry is modified. It sends a single API request to retrieve the draft content and reflect the changes in real time.

Note: The onLiveEdit method is designed exclusively for Client-Side Rendering (CSR) and does not fetch published content.

To use the onLiveEdit method in a CSR setup, create a function (e.g., updateData()) to fetch and process data. Pass this function to the onLiveEdit method, which will execute it whenever new data is available.

// utils.js
import ContentstackLivePreview from '@contentstack/live-preview-utils';
export const onLiveEdit = ContentstackLivePreview.onLiveEdit;

Here’s how you can use the onLiveEdit method in a React component:

// Footer.js
import React from "react";
import { onLiveEdit } from "./utils.js";
const Footer = () => {
    const [data, setData] = React.useState({});
    // Function to fetch data and update the state
    const updateData = () => {
        const fetchedData = SomeCallToGetData();
        setData(fetchedData);
    };
    // Set up the onLiveEdit method to execute the updateData function
    React.useEffect(() => {
        onLiveEdit(updateData);
    }, []);
    return <div>{data.company_name}</div>;
};

onEntryChange(callback: () => void)

The onEntryChange method is designed for Client-Side Rendering (CSR) applications, where the framework manages data collection and rendering. This method triggers a specified callback function, such as updatePage(), whenever new content is available, ensuring real-time updates.

Note: The onEntryChange method only works when SSR is set to false, indicating that the application is using CSR.

// utils.js
import ContentstackLivePreview from '@contentstack/live-preview-utils';
// Export the onEntryChange method for use in components
export const onEntryChange = ContentstackLivePreview.onEntryChange;

To use the onEntryChange method, create a function (e.g., updateData) that fetches and stores updated data. Pass this function to onEntryChange to execute it whenever new data is available.

// Footer.js
import React from "react";
import { onEntryChange } from "./utils.js";
const Footer = () => {
    const [data, setData] = React.useState({});
    // Define a function to fetch and update data
    const updateData = () => {
        const fetchedData = SomeCallToGetData(); // Replace with actual data fetch logic
        setData(fetchedData);
    };
    // Use the onEntryChange method to trigger updates
    React.useEffect(() => {
        onEntryChange(updateData);
    }, []);
    return <div>{data.company_name}</div>;
};

You can enhance the onEntryChange method by using the optional skipInitialRender: true parameter. This prevents an unnecessary initial API call, ensuring the function only executes when new data is available.

Example:

onEntryChange(fetchData, { skipInitialRender: true })

hash

The hash property retrieves the live preview hash of the entry. If the page is not opened in the Live Preview pane, it returns an empty string.

Note: In SSR mode, the hash may not populate automatically. You may need to pass it explicitly using the setConfigFromParams() method.

Example:

console.log(ContentstackLivePreview.hash); //"hash"

getGatsbyDataFormat(sdkQuery: IStackSdk, prefix: string)

Gatsby primarily fetches data using the gatsby-source-contentstack plugin. However, Live Preview is compatible only with the Contentstack SDK. To enable Live Preview in Gatsby, follow these steps:

1. Fetch the data using the Contentstack SDK.
2. Store the fetched data in a React state.
3. Re-render the page using the onEntryChange() method.

Since the data format returned by gatsby-source-contentstack differs from the Contentstack SDK, you can use the getGatsbyDataFormat() method to adjust the entry names to match Gatsby's expectations. This method accepts two parameters:

• The Contentstack Stack object (returned by Contentstack.Stack()).
• The prefix defined in the gatsby-config.js file (default: contentstack).

Example:

const query = Stack.ContentType("your-contentype").Entry("entry-uid");
const formattedData = ContentstackLivePreview.getGatsbyDataFormat(
    query,
    "contentstack" // Prefix defined in gatsby-config.js
);
setData(formattedData);

Before using getGatsbyDataFormat():

{
  "footer_lib": {
    "title": "footer",
    ...
  }
}

After using getGatsbyDataFormat() with the prefix contentstack:

{
  "contentstackFooterLib": {
    "title": "footer",
    ...
  }
}