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

Open a terminal in the root of the repository.
Enter the following command:
- Next.js
npm install @uniformdev/canvas @uniformdev/canvas-react
About this command
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 "../lib/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 function doEnhance(composition) {
  const enhancers = new EnhancerBuilder().data("fields", dataEnhancer);
  return enhance({
    composition,
    enhancers,
  });
}

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.

Next.js

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

Next.js

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

Next.js (steps)
Next.js (complete)

tip

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

Edit the following file:

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

import content from "../lib/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.

Edit the following file:

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

import content from "../lib/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.

Edit the following file:

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

import content from "../lib/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.

Edit the following file:

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

import content from "../lib/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.

Edit the following file:

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

import content from "../lib/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.

Edit the following file:

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

import content from "../lib/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.

Edit the following file:

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

import content from "../lib/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.

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 "../lib/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.

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 "../lib/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.

tip

This section gets you to activating personalization as quickly as possible. It does not explain each line of code.

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 "../lib/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 is the completed page file.

Next steps

As a next step you can activate Live Preview.

Activate composition

Goals

Overview​

Add npm packages​

About this command

Add enhancer​

Add component resolver​

Add layout component for Canvas​

Add Canvas to the home page​

tip

About this step

About this step

About this step

About this step

About this step

About this step

About this step

About this step

About this step

tip

About this step

Next steps​

Overview

Add npm packages

Add enhancer

Add component resolver

Add layout component for Canvas

Add Canvas to the home page

Next steps