Skip to main content

Adding GatherContent data

tip

This tutorial assumes you have completed the basic tutorial and have the artifacts from that already present in Uniform.

Let's add some content data from GatherContent into your Uniform Canvas-powered Next app. To do this we will need to add a new GatherContent-powered parameter to your component type, and then tell your Next app how to fetch and parse the GatherContent data to display it. Canvas provides a framework for enhancing data in your Canvas composition with data from other tools, like CMSes, DAMs, commerce, and search indexes. This enhancement is done on the app side, leaving full flexibility to the developer as to the best and most efficient way to get the data.

First let's connect Uniform to GatherContent by installing the integration. You'll need a GatherContent account to do this (a free one is fine).

  1. Go to Settings on your on https://uniform.app project, then click Integrations
  2. Find the GatherContent integration and add it
  3. Provide the Project ID, Project Access URL, API Username, and API Key for the GatherContent project that you want to bring content from into Canvas

Now that we're connected to GatherContent, we can add a new parameter to our Canvas component type that links to one or more GatherContent items.

  1. Go to your Component Library settings
  2. Open your component type (there should be only one, if you've been following along)
  3. Click (+) next to Parameters
  4. Name your parameter something like 'GatherContent Items', choose GatherContent Items as the type, pick GatherContent templates(s) that can be linked, and as before choose a public ID to use as the name in code. (e.g. gatherContentItems)

Now that the parameter is added to the component type, we need to link the composition we have been rendering to an actual GatherContent item:

  1. Click Compositions, then open your composition from earlier
  2. You should see a GatherContent parameter alongside the text parameter we created before
  3. Choose a GatherContent item to link to and save your composition
  4. That's it - you've linked to a GatherContent item in your composition

With the data schema setup complete, now let's set up Next.js. Right now we're doing nothing with the GatherContent data - the Next app will look exactly the same as it did before, except it has a new parameter we're doing nothing with. To get the GatherContent data, we need to add an enhancer to the Next app's data fetching so that Canvas knows what to do with GatherContent parameters.

  1. Install the @uniformdev/canvas-gatherContent package, which contains the Canvas GatherContent enhancer and the GatherContent Client.

  2. Open your pages/index.js file and import the GatherContent enhancer, and add enhance to the existing canvas import:

    import {
    GatherContentClientList,
    GatherContentClient,
    createGatherContentEnhancer,
    CANVAS_GATHERCONTENT_PARAMETER_TYPES,
    } from '@uniformdev/canvas-gathercontent';
    import { enhance, CanvasClient, EnhancerBuilder } from '@uniformdev/canvas';
  3. In getStaticProps, create the enhancer and configure it to connect to GatherContent and enhance your composition data:

    // ...fetching the composition here

    // NOTE: for production code ensure you use environment variables to
    // configure GatherContent, not hard-coded values.

    // Project Id can be found in your GatherContent Settings page, or in the GatherContent URL:
    // Example: https://yourteam.gathercontent.com/content/{projectId}
    const gatherProjectId = `GATHERCONTENT-PROJECT-ID`;

    // GatherContent API Key can be found/created via the Settings > API page in your GatherContent personal settings.
    // https://help.gathercontent.com/en/articles/369871-generating-an-api-key-the-api-documentation
    const gatherContentApiKey = `GATHERCONTENT-API-KEY`;

    // GatherContent API Username refers to the email address used to log into GatherContent.
    const gatherContentApiUsername = 'GATHERCONTENT-API-USERNAME';

    const client = new GatherContentClient({
    apiKey: gatherContentApiKey,
    apiUsername: gatherContentApiUsername,
    projectId: gatherContentProjectId,
    });

    const clients = new GatherContentClientList({ client });

    // apply the enhancers to the composition data, enhancing it with external data
    // In this case, the _value_ of the GatherContent parameter you created is enhanced
    // with data from the GatherContent item(s) you selected in the GatherContent item selector.
    // You can create your own enhancers easily; they are a simple function.
    await enhance({
    composition,
    enhancers: new EnhancerBuilder().parameterType(
    CANVAS_GATHERCONTENT_PARAMETER_TYPES,
    createGatherContentEnhancer({ clients })
    ),
    context: {},
    });

    // ...returning the props

    The Next app should still be working, but we're not rendering any of the GatherContent data yet. Let's do that!

  4. In the Home component implementation, get the GatherContent parameter value and pick a field from it:

    export default function Home({ composition }) {
    return (
    <Composition data={composition}>
    {/* note: `gatherContentItems` is the "public id" value you provided for
    the GatherContent Item parameter. */}
    {({ greeting, gatherContentItems }) => (
    <article>
    <p>{greeting}</p>
    {/* We assume the item template has a field named 'title' on it */}
    {/* We're also only displaying the title from the first selected item. Your actual code should handle multiple items.*/}
    <p>{gatherContentItems?.[0].mappedContent?.title}</p>
    </article>
    )}
    </Composition>
    );
    }
  5. That's it - now you're rendering data from GatherContent! The default structure of the enhancer result is that of a single GatherContent item fetched from the GatherContent REST API.

tip

Use TypeScript? So do we. Here's the same code with TypeScript.

TypeScript Code
import { enhance, CanvasClient, EnhancerBuilder, ComponentInstance } from '@uniformdev/canvas';
import { Composition } from '@uniformdev/canvas-react';
import {
GatherContentEnhancerResult,
GatherContentClientList,
GatherContentClient,
createGatherContentEnhancer,
CANVAS_GATHERCONTENT_PARAMETER_TYPES,
} from '@uniformdev/canvas-gatherContent';
import { GetStaticProps } from 'next';

type HomeProps = {
composition: ComponentInstance;
};

type MyCanvasComponentType = {
greeting: string;
gatherContentItems: GatherContentEnhancerResult;
};

export default function Home({ composition }: HomeProps) {
return (
<Composition<MyCanvasComponentType> data={composition}>
{({ greeting, gatherContentItems }) => (
<article>
<p>{greeting}</p>
{/* We're only displaying the title from the first selected item. Your actual code should handle multiple items.*/}
<p>{gatherContentItems?.[0].mappedContent?.title}</p>
</article>
)}
</Composition>
);
}

export const getStaticProps: GetStaticProps<HomeProps> = async () => {
// create the Canvas client
const canvasClient = new CanvasClient({
// if this weren't a tutorial, ↙ should be in an environment variable :)
apiKey: 'your-api-key-here',
// if this weren't a tutorial, ↙ should be in an environment variable :)
projectId: 'your-project-id-here',
});

// fetch the composition from Canvas
const { composition } = await canvasClient.getCompositionBySlug({
// if you used something else as your slug, use that here instead
slug: '/',
});

// Project Id can be found in your GatherContent Settings page, or in the GatherContent URL:
// Example: https://yourteam.gathercontent.com/content/{projectId}
const gatherProjectId = `GATHERCONTENT-PROJECT-ID`;

// GatherContent API Key can be found/created via the Settings > API page in your GatherContent personal settings.
// https://help.gathercontent.com/en/articles/369871-generating-an-api-key-the-api-documentation
const gatherContentApiKey = `GATHERCONTENT-API-KEY`;

// GatherContent API Username refers to the email address used to log into GatherContent.
const gatherContentApiUsername = 'GATHERCONTENT-API-USERNAME';

const client = new GatherContentClient({
apiKey: gatherContentApiKey,
apiUsername: gatherContentApiUsername,
projectId: gatherContentProjectId,
});

const clients = new GatherContentClientList({ client });

// apply the enhancers to the composition data, enhancing it with external data
// In this case, the _value_ of the GatherContent parameter you created is enhanced
// with data from the GatherContent item you selected in the GatherContent item selector.
// You can create your own enhancers easily; they are a simple function.
await enhance({
composition,
enhancers: new EnhancerBuilder().parameterType(
CANVAS_GATHERCONTENT_PARAMETER_TYPES,
createGatherContentEnhancer({ clients })
),
context: {},
});

return {
props: {
composition,
},
};
};