Skip to main content

Activate composition

Goals

You have configured the instructions that control composition. Next you need to update the web app to execute those instructions. This involves the following:

  • Understanding how the configuration from Canvas is used in a web app.
  • Updating a web application so that a layout is read from Canvas.

Overview

You configured a composition that defines layout instructions for the home page. The next step is to update the front-end application so it uses those layout instructions.

Add npm packages

  1. Open a terminal in the root of the repository.

  2. Enter the following commands:

    cd examples/docs/intro-to-canvas/nextjs/no-uniform
    npm install @uniformdev/canvas @uniformdev/canvas-react
    About this step

    This adds references to the packages for React apps that need to use Canvas.

Add enhancer

When you created your composition and added a component to the Body slot in the last step, you specified a content id for the component. That content ID is stored by Uniform, and the front-end application must retrieve the details for the item. To simplify that process, Uniform provides an "enhancer" API that calls the data source to fetch those details and collect them into a single object for use by front-end developers.

set-content-id

Add the following file to the root of your application:

/lib/enhancer.js
import { enhance, EnhancerBuilder } from "@uniformdev/canvas";

import content from "../content/content.json";

// Uses the parameter value from the composition
// to look up the topic from the data file. If
// the topic is found, the fields are returned.
const dataEnhancer = async ({ component }) => {
const contentId = component?.parameters?.contentId?.value;
if (contentId) {
const topic = content.find((e) => e.id == contentId);
if (topic) {
return { ...topic.fields };
}
}
};

export default async function doEnhance(composition) {
const enhancedComposition = { ...composition };
const enhancers = new EnhancerBuilder().data("fields", dataEnhancer);
await enhance({
composition: enhancedComposition,
enhancers,
});

return enhancedComposition;
}

Register your components

Your React Component must be registered within Uniform registry:

/src/components/Body.jsx
import { registerUniformComponent } from "@uniformdev/canvas-react";

export default function Body(props) {
return <p>{props.text}</p>
}

registerUniformComponent({
type: 'body',
component: Body,
});
info

For more information, see the Register your component section.

Add layout component for Canvas

Add the following file:

/src/components/LayoutCanvas.jsx
import Head from "next/head";
import { UniformSlot } from "@uniformdev/canvas-react";

import Footer from "./Footer";

export default function LayoutCanvas({ title }) {
return (
<div className="container">
<Head>
<title>{title}</title>
<link rel="icon" href="/favicon.ico" />
</Head>
<UniformSlot name="body" />
<Footer />
</div>
);
}

Add Canvas to the home page

Adding Canvas to the home page involves making changes to the front-end application. Follow the steps that match your front-end technology.

Next.js

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. Edit the following file:

    /pages/index.js
    import Layout from "../src/components/Layout";

    import content from "../content/content.json";

    async function getComposition(slug) {
    }

    export async function getStaticProps() {
    const slug = "/";
    const topic = content.find((e) => e.url == slug);
    return { props: { fields: topic.fields } };
    }

    export default function Home({ fields }) {
    return <Layout content={content} fields={fields} />;
    }
    About this step

    This adds a function that will hold the logic needed to retrieve the composition from Uniform.

  2. Edit the following file:

    /pages/index.js
    import { CanvasClient } from "@uniformdev/canvas";
    import Layout from "../src/components/Layout";

    import content from "../content/content.json";

    async function getComposition(slug) {
    const client = new CanvasClient({
    apiKey: process.env.UNIFORM_API_KEY,
    projectId: process.env.UNIFORM_PROJECT_ID,
    });
    }

    export async function getStaticProps() {
    const slug = "/";
    const topic = content.find((e) => e.url == slug);
    return { props: { fields: topic.fields } };
    }

    export default function Home({ fields }) {
    return <Layout content={content} fields={fields} />;
    }
    About this step

    This adds the client object used to make API calls to Uniform.

  3. Edit the following file:

    /pages/index.js
    import { CanvasClient } from "@uniformdev/canvas";
    import Layout from "../src/components/Layout";

    import content from "../content/content.json";

    async function getComposition(slug) {
    const client = new CanvasClient({
    apiKey: process.env.UNIFORM_API_KEY,
    projectId: process.env.UNIFORM_PROJECT_ID,
    });
    const { composition } = await client.getCompositionBySlug({
    slug,
    });
    return composition;
    }

    export async function getStaticProps() {
    const slug = "/";
    const topic = content.find((e) => e.url == slug);
    return { props: { fields: topic.fields } };
    }

    export default function Home({ fields }) {
    return <Layout content={content} fields={fields} />;
    }
    About this step

    This retrieves the composition from Uniform and returns it.

  4. Edit the following file:

    /pages/index.js
    import { CanvasClient } from "@uniformdev/canvas";
    import Layout from "../src/components/Layout";

    import content from "../content/content.json";

    async function getComposition(slug) {
    const client = new CanvasClient({
    apiKey: process.env.UNIFORM_API_KEY,
    projectId: process.env.UNIFORM_PROJECT_ID,
    });
    const { composition } = await client.getCompositionBySlug({
    slug,
    });
    return composition;
    }

    export async function getStaticProps() {
    const slug = "/";
    const topic = content.find((e) => e.url == slug);

    const composition = await getComposition(slug);

    return { props: { fields: topic.fields } };
    }

    export default function Home({ fields }) {
    return <Layout content={content} fields={fields} />;
    }
    About this step

    This adds a call to the function that retrieves the composition from Uniform.

  5. Edit the following file:

    /pages/index.js
    import { CanvasClient } from "@uniformdev/canvas";
    import Layout from "../src/components/Layout";

    import content from "../content/content.json";
    import doEnhance from "../lib/enhancer";

    async function getComposition(slug) {
    const client = new CanvasClient({
    apiKey: process.env.UNIFORM_API_KEY,
    projectId: process.env.UNIFORM_PROJECT_ID,
    });
    const { composition } = await client.getCompositionBySlug({
    slug,
    });
    return composition;
    }

    export async function getStaticProps() {
    const slug = "/";
    const topic = content.find((e) => e.url == slug);

    const composition = await getComposition(slug);

    await doEnhance(composition);

    return { props: { fields: topic.fields } };
    }

    export default function Home({ fields }) {
    return <Layout content={content} fields={fields} />;
    }
    About this step

    This runs the enhancer, which adds data to the composition.

  6. Edit the following file:

    /pages/index.js
    import { CanvasClient } from "@uniformdev/canvas";
    import Layout from "../src/components/Layout";

    import content from "../content/content.json";
    import doEnhance from "../lib/enhancer";

    async function getComposition(slug) {
    const client = new CanvasClient({
    apiKey: process.env.UNIFORM_API_KEY,
    projectId: process.env.UNIFORM_PROJECT_ID,
    });
    const { composition } = await client.getCompositionBySlug({
    slug,
    });
    return composition;
    }

    export async function getStaticProps() {
    const slug = "/";
    const topic = content.find((e) => e.url == slug);

    const composition = await getComposition(slug);

    await doEnhance(composition);

    //
    //Return props for the home page that
    //include the composition and content
    //required by the page components.
    return {
    props: {
    composition,
    fields: topic.fields,
    },
    };
    }

    export default function Home({ fields }) {
    return <Layout content={content} fields={fields} />;
    }
    About this step

    This returns the props.

  7. Edit the following file:

    /pages/index.js
    import { CanvasClient } from "@uniformdev/canvas";
    import Layout from "../src/components/Layout";

    import content from "../content/content.json";
    import doEnhance from "../lib/enhancer";

    async function getComposition(slug) {
    const client = new CanvasClient({
    apiKey: process.env.UNIFORM_API_KEY,
    projectId: process.env.UNIFORM_PROJECT_ID,
    });
    const { composition } = await client.getCompositionBySlug({
    slug,
    });
    return composition;
    }

    export async function getStaticProps() {
    const slug = "/";
    const topic = content.find((e) => e.url == slug);

    const composition = await getComposition(slug);

    await doEnhance(composition);

    //
    //Return props for the home page that
    //include the composition and content
    //required by the page components.
    return {
    props: {
    composition,
    fields: topic.fields,
    },
    };
    }

    export default function Home({ composition, fields }) {
    return <Layout content={content} fields={fields} />;
    }
    About this step

    This makes the composition available to the React component.

  8. Edit the following file:

    /pages/index.js
    import { CanvasClient } from "@uniformdev/canvas";
    import { UniformComposition } from "@uniformdev/canvas-react";
    import Layout from "../src/components/Layout";

    import content from "../content/content.json";
    import doEnhance from "../lib/enhancer";
    import resolveRenderer from "../lib/resolveRenderer";

    async function getComposition(slug) {
    const client = new CanvasClient({
    apiKey: process.env.UNIFORM_API_KEY,
    projectId: process.env.UNIFORM_PROJECT_ID,
    });
    const { composition } = await client.getCompositionBySlug({
    slug,
    });
    return composition;
    }

    export async function getStaticProps() {
    const slug = "/";
    const topic = content.find((e) => e.url == slug);

    const composition = await getComposition(slug);

    await doEnhance(composition);

    //
    //Return props for the home page that
    //include the composition and content
    //required by the page components.
    return {
    props: {
    composition,
    fields: topic.fields,
    },
    };
    }

    export default function Home({ composition, fields }) {
    return (
    <UniformComposition data={composition} resolveRenderer={resolveRenderer}>
    <Layout content={content} fields={fields} />
    </UniformComposition>
    );
    }
    About this step

    This adds the Uniform component that handles composition tasks in the app.

  9. Edit the following file:

    /pages/index.js
    import { CanvasClient } from "@uniformdev/canvas";
    import { UniformComposition } from "@uniformdev/canvas-react";

    import LayoutCanvas from "../src/components/LayoutCanvas";

    import content from "../content/content.json";
    import doEnhance from "../lib/enhancer";
    import resolveRenderer from "../lib/resolveRenderer";

    async function getComposition(slug) {
    const client = new CanvasClient({
    apiKey: process.env.UNIFORM_API_KEY,
    projectId: process.env.UNIFORM_PROJECT_ID,
    });
    const { composition } = await client.getCompositionBySlug({
    slug,
    });
    return composition;
    }

    export async function getStaticProps() {
    const slug = "/";
    const topic = content.find((e) => e.url == slug);

    const composition = await getComposition(slug);

    await doEnhance(composition);

    //
    //Return props for the home page that
    //include the composition and content
    //required by the page components.
    return {
    props: {
    composition,
    fields: topic.fields,
    },
    };
    }

    export default function Home({ composition, fields }) {
    return (
    <UniformComposition data={composition} resolveRenderer={resolveRenderer}>
    <LayoutCanvas composition={composition} fields={fields} />
    </UniformComposition>
    );
    }
    About this step

    This replaces the default layout component with one that is Canvas-aware.

Nuxt 3

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. Edit the following file:

    /nuxt.config.ts
    import { defineNuxtConfig } from "nuxt";

    // https://v3.nuxtjs.org/api/configuration/nuxt.config
    export default defineNuxtConfig({
    css: ["~/styles/globals.css", "~/styles/page.css"],
    modules: ["@uniformdev/uniform-nuxt"],
    });
    About this step

    This adds the Uniform module, which brings Uniform functionality to Nuxt.

  2. Edit the following file:

    /nuxt.config.ts
    import { defineNuxtConfig } from "nuxt";

    // https://v3.nuxtjs.org/api/configuration/nuxt.config
    export default defineNuxtConfig({
    css: ["~/styles/globals.css", "~/styles/page.css"],
    modules: ["@uniformdev/uniform-nuxt"],
    uniform: {
    projectId: process.env.UNIFORM_PROJECT_ID,
    readOnlyApiKey: process.env.UNIFORM_API_KEY,
    apiHost: process.env.UNIFORM_CLI_BASE_URL,
    },
    });
    About this step

    This sets the values the Uniform modules uses to connect to Uniform. You set the project ID and API key values as environment variables in a previous step. The API host value is optional, and is used when you want to use an alternate endpoint for the Uniform API.

  3. Edit the following file:

    /nuxt.config.ts
    import { defineNuxtConfig } from "nuxt";
    import { ManifestV2 } from "@uniformdev/context";

    // https://v3.nuxtjs.org/api/configuration/nuxt.config
    export default defineNuxtConfig({
    css: ["~/styles/globals.css", "~/styles/page.css"],
    modules: ["@uniformdev/uniform-nuxt"],
    uniform: {
    projectId: process.env.UNIFORM_PROJECT_ID,
    readOnlyApiKey: process.env.UNIFORM_API_KEY,
    apiHost: process.env.UNIFORM_CLI_BASE_URL,
    manifest: {} as ManifestV2,
    },
    });
    About this step

    The Nuxt module for Uniform requires a manifest be set in order to pass validation checks within the Nuxt module. This sets a manifest in order to meet this requirement.

  4. Edit the following file:

    /nuxt.config.ts
    import { defineNuxtConfig } from "nuxt";
    import { ManifestV2 } from "@uniformdev/context";

    // https://v3.nuxtjs.org/api/configuration/nuxt.config
    export default defineNuxtConfig({
    css: ["~/styles/globals.css", "~/styles/page.css"],
    modules: ["@uniformdev/uniform-nuxt"],
    uniform: {
    projectId: process.env.UNIFORM_PROJECT_ID,
    readOnlyApiKey: process.env.UNIFORM_API_KEY,
    apiHost: process.env.UNIFORM_CLI_BASE_URL,
    manifest: {} as ManifestV2,
    defaultConsent: true,
    },
    });
    About this step

    The Nuxt module for Uniform requires a manifest be set in order to pass validation checks within the Nuxt module. This sets a manifest in order to meet this requirement.

  5. Edit the following file:

    /pages/index.vue
    <script lang="ts" setup>
    import content from "../content/content.json";

    const slug = "/";
    const topic = content.find((e) => e.url == slug);

    const { composition } = await useUniformComposition({ slug });
    </script>

    <template>
    <Layout :content="content" :fields="topic.fields" />
    </template>
    About this step

    This uses the Uniform module to retrieve the composition using the specified slug.

  6. Edit the following file:

    /pages/index.vue
    <script lang="ts" setup>
    import content from "../content/content.json";
    import doEnhance from "../lib/enhancer";

    const slug = "/";
    const topic = content.find((e) => e.url == slug);

    const { composition } = await useUniformComposition({
    slug,
    enhance: async (c) => await doEnhance(c)
    });
    </script>

    <template>
    <Layout :content="content" :fields="topic.fields" />
    </template>
    About this step

    This applies the enhancer to the composition.

  7. Edit the following file:

    /pages/index.vue
    <script lang="ts" setup>
    import content from "../content/content.json";
    import doEnhance from "../lib/enhancer";
    import resolveRenderer from "../lib/resolveRenderer";

    const slug = "/";
    const topic = content.find((e) => e.url == slug);

    const { composition } = await useUniformComposition({
    slug,
    enhance: async (c) => await doEnhance(c)
    });
    </script>

    <template>
    <UniformComposition
    v-if="composition"
    :data="composition"
    :resolve-renderer="resolveRenderer"
    >
    <Layout :content="content" :fields="topic.fields" />
    </UniformComposition>
    </template>
    About this step

    In Canvas you added a component to a slot in a composition. The front-end application must determine which front-end component to use to render the Canvas component. The component you add in this step makes this decision.

  8. Edit the following file:

    /pages/index.vue
    <script lang="ts" setup>
    import content from "../content/content.json";
    import doEnhance from "../lib/enhancer";
    import resolveRenderer from "../lib/resolveRenderer";
    import LayoutCanvas from "../components/LayoutCanvas.vue";

    const slug = "/";
    const topic = content.find((e) => e.url == slug);

    const { composition } = await useUniformComposition({
    slug,
    enhance: async (c) => await doEnhance(c)
    });
    </script>

    <template>
    <UniformComposition
    v-if="composition"
    :data="composition"
    :resolve-renderer="resolveRenderer"
    >
    <LayoutCanvas :title="topic.fields.title" />
    </UniformComposition>
    </template>
    About this step

    This adds the layout component you created earlier.