Skip to main content

Live preview

Users configuring a layout using Canvas can preview their changes as they work. This requires configuration in Uniform and in the front-end application.

info

These instructions assume you already have preview mode activated in your front-end application. For instructions, see Preview mode.

Activate front-end

The activation process on the front-end depends on the technology used to build the front-end. In general, however, the process involves changing the code that reads the composition from Uniform so the most recent configuration (i.e. the draft version) from Uniform is used.

Next.js

In order to make these instructions easier to follow, a specific example is used. The example activates live preview for the following page:

Sample page used in this example
import Head from 'next/head'
import {
CanvasClient,
CANVAS_DRAFT_STATE,
CANVAS_PUBLISHED_STATE,
} from '@uniformdev/canvas'
import {
UniformComposition,
UniformSlot,
} from '@uniformdev/canvas-react'

export async function getStaticProps({ preview }) {
const client = new CanvasClient({
apiKey: process.env.UNIFORM_API_KEY,
projectId: process.env.UNIFORM_PROJECT_ID,
})
const { composition } = await client.getCompositionBySlug({
slug: "/",
state: preview ? CANVAS_DRAFT_STATE : CANVAS_PUBLISHED_STATE,
})

return {
props: {
title: 'Sample app',
composition,
}
}
}

function UnknownComponent({ component }) {
return <div>[unknown component: {component.type}]</div>
}
function resolveRenderer({ type }) {
// TODO: Add your components.
return UnknownComponent
}

export default function Home({ title, composition }) {
return (
<UniformComposition data={composition} resolveRenderer={resolveRenderer}>
<div>
<Head>
<title>{title}</title>
</Head>

<main>
<UniformSlot name='body' />
</main>
</div>
</UniformComposition>
)
}

Create a new hook

  1. Add the following file:

    lib/useLivePreviewNextStaticProps.js
    import { useRouter } from 'next/router'
    import { useCallback } from 'react'
    import { useCompositionEventEffect } from '@uniformdev/canvas-react'

    export function useLivePreviewNextStaticProps(options) {
    const router = useRouter()

    const effect = useCallback(() => {
    router.replace(router.asPath, undefined, { scroll: false })
    }, [router])

    return useCompositionEventEffect({
    ...options,
    enabled: router.isPreview,
    effect,
    })
    }
    About this step

    This add a hook that updates props when the composition changes.

Edit page files

Next you must make changes to the pages that read compositions from Uniform.

  1. Import the hook in your page component

    import Head from 'next/head'
    import {
    CanvasClient,
    CANVAS_DRAFT_STATE,
    CANVAS_PUBLISHED_STATE,
    } from '@uniformdev/canvas'
    import {
    UniformComposition,
    UniformSlot,
    } from '@uniformdev/canvas-react'
    import { useLivePreviewNextStaticProps } from '../lib/useLivePreviewNextStaticProps'
    ...
    important

    Be sure to change the path to the hook to match your file's location.

  2. Use the hook:

    export default function Home({ title, composition }) {
    useLivePreviewNextStaticProps({
    compositionId: composition?._id,
    projectId: process.env.UNIFORM_PROJECT_ID,
    })
    return (
    <UniformComposition data={composition} resolveRenderer={resolveRenderer}>
    <div>
    <Head>
    <title>{title}</title>
    </Head>

    <main>
    <Slot name='body' />
    </main>
    </div>
    </UniformComposition>
    )
    }

And that's it, the composition preview page will be automatically updated when new changes are saved.

Nuxt 3

The Uniform module for Nuxt enables live preview out of the box. No front-end application modifications are needed.