Skip to main content

Activation

Create API key​

  1. Click the Uniform logo at the top of the page to return to the Uniform team home page.

  2. Create an API key with the following custom permissions:

    Uniform Canvas > Compositions > Read Published
    About this step

    If you already have an API key with these permissions, you can skip this step.

  3. Add the following values to your .env file. You collected these values when you created the Uniform API key:

    Uniform valueEnvironment variable
    API Key
    UNIFORM_API_KEY
    Project ID
    UNIFORM_PROJECT_ID
    About this step

    Technically you do not need to set these values in environment variables. You could hard-code the values into your app, but using environment variables is a "best practice".

Update front-end app​

The changes needed to the front-end depends on the technology used to build the front-end.

Next.js​

In order to make these instructions easier to follow, a specific example is used. The example activates Canvas for the following page, where the presentation logic in the <main> tag will be controlled by a user with Canvas:

import Head from 'next/head'

export async function getStaticProps() {
  return {
    props: { 
      title: "Sample app",
      message: "Hello",
    }
  }
}

export default function Home({ title, message }) {
  return (
    <div>
      <Head>
        <title>{title}</title>
      </Head>

      <main>
        <h1>
          {message}
        </h1>
      </main>
    </div>
  )
}
tip

This section guides you through the process of activating Canvas by explaining each step. It takes longer to go through, but it will help you understand why each line of code is needed.

  1. Add the following packages to your app:

    @uniformdev/canvas
    @uniformdev/canvas-react

  2. Add the following code:

    import Head from 'next/head'
    import { 
      CanvasClient,
    } from '@uniformdev/canvas'
    ...

  3. Add the following code:

    export async function getStaticProps() {
      const client = new CanvasClient({
        apiKey: process.env.UNIFORM_API_KEY,
        projectId: process.env.UNIFORM_PROJECT_ID,
      })
      return {
        props: { 
          title: "Sample app",
          message: "Hello",
        }
      }
    }

  4. Add the following code:

    export async function getStaticProps() {
      const client = new CanvasClient({
        apiKey: process.env.UNIFORM_API_KEY,
        projectId: process.env.UNIFORM_PROJECT_ID,
      })
      const { composition } = await client.getCompositionBySlug({
        slug: "/",
      })
      return {
        props: { 
          title: "Sample app",
          message: "Hello",
        }
      }
    }

  5. Add the following code:

    export async function getStaticProps() {
      const client = new CanvasClient({
        apiKey: process.env.UNIFORM_API_KEY,
        projectId: process.env.UNIFORM_PROJECT_ID,
      })
      const { composition } = await client.getCompositionBySlug({
        slug: "/",
      })
      return {
        props: { 
          title: "Sample app",
          message: "Hello",
          composition,
        }
      }
    }

  6. Add the following code:

    import Head from 'next/head'
    import { 
      CanvasClient,
    } from '@uniformdev/canvas'
    import { 
      Composition,
    } from '@uniformdev/canvas-react';
    ...

  7. Add the following code:

    export default function Home({ title, message, composition }) {
      return (
        <div>
          <Head>
            <title>{title}</title>
          </Head>
          ...

  8. Add the following code:

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

  9. Add the following code:

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

            <main>
              <h1>
                {message}
              </h1>
            </main>
          </div>
        </Composition>
      )
    }

  10. Add the following code:

    import Head from 'next/head'
    import { 
      CanvasClient,
    } from '@uniformdev/canvas'
    import { 
      Composition,
      Slot,
    } from '@uniformdev/canvas-react';
    ...

  11. Add the following code:

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

            <main>
              <Slot name='body' />
            </main>
          </div>
        </Composition>
      )
    }
    About this step

    You add the Slot component in the places that match where you defined slots in your composition component.