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:

  • Understand how the configuration from Canvas is used in a web app.
  • Update a web application so 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 command:

    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

In this example, the business user specifies the content id for the component. You did this when you added the component to the slot and set the parameter value. The front-end also needs the fields from the data file. An enhancer is the component that reads that additional data and makes it available to the front-end component.

Add the following file:

/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;
}

Add component resolver

When you configure personalization, Uniform Context determines which component is appropriate. Context provides the front-end with the name of the component as it is defined in Uniform. This means the front-end must map the Uniform component name to React components.

Add the following file:

/lib/resolveRenderer.js
import Body from "../src/components/Body";

function UnknownComponent({ component }) {
return <div>[unknown component: {component.type}]</div>;
}

export default function resolveRenderer({ type }) {
if (type == "defaultBody") {
return Body;
}
return UnknownComponent;
}

Add layout component for Canvas

Add the following file:

/src/components/LayoutCanvas.jsx
import Head from "next/head";
import { Slot } 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>
<Slot 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 { Composition } 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 (
    <Composition data={composition} resolveRenderer={resolveRenderer}>
    <Layout content={content} fields={fields} />
    </Composition>
    );
    }
    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 { Composition } 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 (
    <Composition data={composition} resolveRenderer={resolveRenderer}>
    <LayoutCanvas composition={composition} fields={fields} />
    </Composition>
    );
    }
    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 { $useComposition } = useNuxtApp();
    const { data: compositionData } = await $useComposition({ 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 { $useComposition } = useNuxtApp();
    const { data: compositionData } = await $useComposition({ slug });

    const composition = await doEnhance(compositionData.value.composition);
    </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 { $useComposition } = useNuxtApp();
    const { data: compositionData } = await $useComposition({ slug });

    const composition = await doEnhance(compositionData.value.composition);
    </script>

    <template>
    <Composition
    v-if="composition"
    :data="composition"
    :resolve-renderer="resolveRenderer"
    >
    <Layout :content="content" :fields="topic.fields" />
    </Composition>
    </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 { $useComposition } = useNuxtApp();
    const { data: compositionData } = await $useComposition({ slug });

    const composition = await doEnhance(compositionData.value.composition);
    </script>

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

    This adds the layout component you created earlier.

Next steps

As a next step you can activate Live Preview.