Building websites with Uniform: a beginner's guide

Understanding the way DXC works

• Set up a CMS instance and application.
• Sign up for a Uniform account and integrate with a CMS.
• Design, source, and model the content.
• Build components and compositions on Uniform.
• Create a Gatsby application.
• Connect Uniform and Gatsby.
• Establish preview in Uniform.
• Personalize the website.

Considering the prerequisites

• Knowledge of HTML, CSS, JavaScript, and React.js.
• A machine fitted with Node.js and its package manager npm or the npm alternative Yarn.

Creating a Sanity application

1// genericContent.ts
2export default {
3  name: 'genericContent',
4  type: 'document',
5  title: 'Generic content',
6  fields: [
7    {
8      name: 'body',
9      title: 'Body',
10      type: 'text',
11    },
12  ],
13}
14// offering.ts
15export default {
16  name: 'offering',
17  type: 'document',
18  title: 'Offering',
19  fields: [
20    {
21      name: 'offeringName',
22      type: 'string',
23      title: 'Offering Name',
24    },
25    {
26      name: 'offeringImage',
27      type: 'image',
28      title: 'Offering image',
29    },
30    {
31      name: 'offeringSummary',
32      type: 'string',
33      title: 'Offering Summary',
34    },
35    {
36      name: 'offeringIntroduction',
37      type: 'text',
38      title: 'Offering Introduction',
39    },
40    {
41      name: 'offeringDescription',
42      type: 'text',
43      title: 'Offering Description',
44    },
45  ],
46

1// schema/index.ts
2import genericContent from './genericContent'
3import offering from './offering'
4export const schemaTypes = [genericContent, offering]

This tutorial does not cover the intricacies of publishing Sanity projects. For details on that topic, see these two articles: one on how Schemas work in Sanity and the other on how to publish content to your Sanity Studio.

Creating a Uniform account

1. Rename your project to Joyride.
2.  Navigate to the Security tab of your team dashboard to create an API key: Name the key and click Save. 
3. Note down the new API key for use in your front-end application later. 

For further reference, read about Uniform’s advanced project roles and permissions.

1. Click the Integrations tab in your project and select and add the Sanity integration (under Content). 
2. Configure the Sanity integration by authenticating your account, choosing a project, and specifying the dataset. A Sanity Entry Selector type then becomes available for selection in Components.

Crafting the design and content

• A navigation bar with menu options.
• A hero section with an image and call to action.
• A section with steps to sign up for Joyride.
• A section with a list of the Joyride features.
• A footer.

Modeling the content 

• Components in Uniform contain parameters and slots. Uniform parameters, which correspond to the fields for the actual content, are similar to component props in React, e.g., title, description, and link. Uniform slots, which are containers for other child components, are similar to the children component prop in React. 
• Compositions in Uniform, which are also components, are root components that form the basis of other components. When creating a Component, checking the Composition Component box marks that Component as a Composition. You can create Components in a different form with Variants. 

• Name: Call to Action Parameters and type
  • Title: text
  • Link: text
• Name: Generic Card
• Parameters and type
  • Title: text
  • CTA Link: text
  • CTA Title: text
  • Body: Sanity Entry Selector
    • Allowed Content Types: genericContentClick to copy
    • Searchable Fields: bodyClick to copy
• Name: Generic Grid Parameters and type
• Title: text
• Slots
  • Name: Items
    • Required Component Quantity: Minimum 3 (no maximum)
    • Allowed Components: Generic Card, Offering Card, Hero
• Name: Hero
• Parameters and type
  • Title: text
  • Description: text
  • Image: text
• Slots
  • Name: CTAs
    • Allowed Components: Call to Action
• Name: Offering Card
• Parameters and type
  • Offering: Sanity Entry Selector
    • Allowed Content Types: offering
    • Searchable Fields: offeringNameClick to copy, offeringImageClick to copy, offeringSummaryClick to copy
• Name: Offering Grid
• Parameters and type
  • Title: text
• Slots
  • Name: Offerings
    • Required Component Quantity: Minimum 2 (no maximum)
    • Allowed Components: Offering Card
• Name: Page
• Composition Component: trueClick to copy. (Check the box.)
• Parameters & type
  • Meta Title: text
    • Required: trueClick to copy
• Slots
  • Name: Content
    • Allowed Components: All except Page

homeClick to copy is a unique identifier for the Composition. You’ll fetch Compositions with a slug in the front end. 

Creating a Gatsby application 

1
2# Install Gatsby CLI
3  npm init gatsby -ts

1npm i @uniformdev/canvas @uniformdev/canvas-react @uniformdev/canvas-sanity @uniformdev/cli @uniformdev/context @uniformdev/context-react dotenv

To avoid version-mismatch errors, ensure that the Uniform packages have the same version number.

1GATSBY_UNIFORM_API_KEY=
2  GATSBY_UNIFORM_PROJECT_ID=
3  GATSBY_SANITY_PROJECT_ID=
4  GATSBY_SANITY_DATASET=
5  UNIFORM_API_KEY=
6  UNIFORM_PROJECT_ID=

Creating Components

Tip: To skip this Component-creation step, clone the branch by setting up a base project with the Components in this repository. 

1// src/components/CTA.tsx
2import * as React from "react";
3export const CTA = ({
4  title,
5  link,
6}: {
7  title: string;
8  link: string;
9}) => {
10  return (
11    <div>
12      <a href={link}>
13        <button className="px-4 py-2 bg-[#c98686] rounded">{title}</button>
14      </a>
15    </div>
16  );
17};

1// src/components/default.tsx
2import * as React from "react";
3export const Default = () => {
4  return (
5    <div>
6      <h1>Default component</h1>
7    </div>
8  );
9};

1// src/component/Footer.tsx
2import * as React from "react";
3export const Footer = () => {
4  return (
5    <div className="px-5 py-2 flex text-[#fff4ec] bg-[#2d2d34] font-light text-sm mt-10">
6      <p> Joyride &copy; 2023</p>
7    </div>
8  );
9};

1// src/components/GenericCard.tsx
2import * as React from "react";
3export const GenericCard = ({
4  title,
5  ctaLink = "#",
6  ctaTitle,
7  body,
8}: {
9  title: string;
10  ctaLink?: string;
11  ctaTitle?: string;
12  body?: string | any;
13}) => {
14  return (
15    <div className="h-full flex flex-col justify-between">
16      <h3 className="text-xl font-medium text-center mb-5">{title}</h3>
17      <p className="px-10">{body.body}</p>
18      <a href={ctaLink}>
19        <p className="text-center mt-5 text-[#c98686] font-semibold">
20          {ctaTitle}
21        </p>
22      </a>
23    </div>
24  );
25}

1// src/components/GenericGrid.tsx
2import { Slot } from "@uniformdev/canvas-react";
3import * as React from "react";
4export const GenericGrid = ({
5  title,
6  children,
7}: {
8  title: string;
9  children: any;
10}) => {
11  return (
12    <div className="border-t-2 py-[4em]">
13      <h3 className="text-3xl text-center mb-10 font-medium">{title}</h3>
14      <div className="grid grid-cols-3 gap-5">
15        <Slot name="items" />
16      </div>
17    </div>
18  );
19};

1 // src/components/Header.tsx
2    
3    import * as React from "react";
4    
5    export const Header = () => {
6      return (
7        <div className="px-5 py-2 grid gap-2 content-center grid-cols-12 text-[#fff4ec] bg-[#2d2d34] font-light text-sm">
8          <div className="col-span-4 items-center">
9            <p className="font-bold text-lg">Joyride</p>
10          </div>
11    
12          <div className="flex space-x-10 col-span-8 justify-end items-center">
13            <p>Get a ride</p>
14            <p>Drive with us</p>
15            <p>About us</p>
16            <p>Safety</p>
17            <button className="px-2 py-1 bg-[#c98686] rounded">Log in</button>
18          </div>
19        </div>
20      );
21    };

1    // src/components/Hero.tsx
2    import { Slot } from "@uniformdev/canvas-react";
3    import * as React from "react";
4    type HeroProps = {
5      title: string;
6      description: string;
7      image: string;
8      children?: any;
9    };
10    
11    export const Hero = ({ title, description, image, children }: HeroProps) => {
12      return (
13        <div className="grid grid-cols-2 py-[3em]">
14          <div className="mb-5">
15            <h1 className="text-4xl mb-5">{title}</h1>
16            <p className="mb-5">{description}</p>
17            <div>
18              <Slot name="ctas" />
19            </div>
20          </div>
21          <div>
22            <img src={image} width="500px" />
23          </div>
24        </div>
25      );
26    };

1 // src/components/Layout.tsx
2    
3    import * as React from "react";
4    import { Footer } from "./Footer";
5    import { Header } from "./Header";
6    
7    export const Layout = (props: any) => {
8      return (
9        <div className="flex flex-col h-screen justify-between">
10          <Header />
11          <div className="mb-auto">{props.children}</div>
12          <Footer />
13        </div>
14      );
15    };

1    // src/components/OfferingCard.tsx
2    
3    import * as React from "react";
4    
5    export const OfferingCard = ({
6      offering: { offeringName, offeringImage, offeringSummary },
7    }: {
8      offering: any;
9    }) => {
10      return (
11        <div className="text-center rounded-md border-2 p-3 h-full flex flex-col justify-between">
12          <p className="text-lg font-semibold">{offeringName}</p>
13    
14          <div className="min-h-150">
15            <img
16              src={offeringImage}
17              width="100px"
18              className="mx-auto"
19              height={300}
20            />
21          </div>
22          <p className="text-sm">{offeringSummary}</p>
23        </div>
24      );
25    };

1    // src/components/OfferingGrid.tsx
2    
3    import { Slot } from "@uniformdev/canvas-react";
4    import * as React from "react";
5    
6    export const OfferingGrid = ({ title }: { title: string; children: any }) => {
7      return (
8        <div className="border-t-2 py-[4em]">
9          <h3 className="text-3xl text-center mb-10 font-medium">{title}</h3>
10          <div className="grid grid-cols-4 gap-7">
11            <Slot name="offerings" />
12          </div>
13        </div>
14      );
15    };

1    // src/components/Page.tsx
2    
3    import * as React from "react";
4    import { Layout } from "./Layout";
5    
6    export const PageComponent = (props: any) => {
7      return (
8        <Layout>
9          <div className="container mx-auto">{props.children}</div>
10        </Layout>
11      );
12    };

Note the SlotComponentClick to copy from Uniform, which identifies the containers for child components with Slots with the name prop as specified in Uniform.

Creating a Composition with content in Uniform

• Component:Hero
  • Title: Let’s Take a Ride
  • Description: Wherever you want to be, let's take you there. Superfast. We put the Joy in Joyride.
  • Image: https://img.freepik.com/premium-vector/online-car-rent-people-using-mobile-application-ordering-taxi-cab-car-sharing-woman-near-smartphone-screen-with-route-location-mark-city-map_458444-996.jpg
  • CTAs
    • Component: Call to Action
      • Title: Contact us
      • Link: #
• Component:Generic Grid
  • Title: Find your joy
  • Items
• Component: Generic Card
  • Title: Get our app
  • CTA Title: Learn More 
  • Body: Pick data from Sanity by following the list as shown.
• Component: Generic Card
  • Title: Create account
  • CTA Title: Learn More 
  • Body: Pick data from Sanity by following the list as shown.
• Component: Generic Card
  • Title: About Joyride
  • CTA Title: Learn More 
  • Body: Pick data from Sanity by following the list as shown.
• Component: Offering Grid
  • Title: Our Offerings
  • Offerings
• Component: Offering Card
  • Offering: Pick data from Sanity by following the list as shown.
• Component: Offering Card
  • Offering: Pick data from Sanity by following the list as shown.
• Component: Offering Card
  • Offering: Pick data from Sanity by following the list as shown.
• Component: Offering Card
  • Offering: Pick data from Sanity by following the list as shown.

Connecting the Composition in Gatsby

1. Fetch Compositions from Uniform by Slug.
2. Enhance the Composition (more on that later).
3. Create a component-resolution function.

1. Create a function that renders a page with the code below in src/pages/index.tsxClick to copy:

   Copy to clipboard

   1 import * as React from "react";
   2  import type {
   3    PageProps,
   4  } from "gatsby";
   5  import { PageComponent } from "../components/Page";
   6  const Homepage = (props: PageProps) => {
   7    return (
   8      <PageComponent>
   9        {// component to go in here}
   10      </PageComponent>
   11    );
   12  };
   13  export default Homepage;

   Depending on your application's architecture, you can fetch Compositions from Uniform in multiple ways. For this tutorial, fetch each Composition on its corresponding page. Another flexible way is to find out the page path and fetch a Composition based on that page. For this tutorial, keep it basic and fetch Compositions based on their Slug.
2. Add the code below to index.tsxClick to copy to create a function that fetches a Composition by Slug:

   Copy to clipboard

   1import * as React from "react";
   2  import type { PageProps } from "gatsby";
   3  import { PageComponent } from "../components/Page";
   4  import { CanvasClient } from "@uniformdev/canvas";
   5  // function to get composition
   6  export const getComposition = async () => {
   7    const client = new CanvasClient({
   8      apiKey: process.env.GATSBY_UNIFORM_API_KEY,
   9      projectId: process.env.GATSBY_UNIFORM_PROJECT_ID,
   10    });
   11    const { composition } = await client.getCompositionBySlug({ slug: "home" });
   12    return composition;
   13  };
   14  const Homepage = (props: PageProps) => {
   15    return (
   16      <PageComponent>
   17        {// component to go in here}
   18      </PageComponent>
   19    );
   20  };
   21  export default Homepage;

Enhancing the Compositions 

1// Other imports go in here
2import {
3  CanvasClient,
4  ComponentInstance,
5  enhance,
6  EnhancerBuilder,
7} from "@uniformdev/canvas";
8import createSanityClient from "@sanity/client";
9import {
10  CANVAS_SANITY_PARAMETER_TYPES,
11  createSanityEnhancer,
12} from "@uniformdev/canvas-sanity";
13// function to get composition by slug
14export const getComposition = async () => {
15  // function definition goes in here
16};
17// Sanity enhancer function
18export async function enhanceComposition(composition: ComponentInstance) {
19  const sanityClient = createSanityClient({
20    projectId: process.env.GATSBY_SANITY_PROJECT_ID,
21    dataset: process.env.GATSBY_SANITY_DATASET,
22    useCdn: false,
23  });
24  // Create a modified enhancer to enhance the images and return offeringImage
25  const sanityEnhancer = createSanityEnhancer({
26    client: sanityClient,
27    modifyQuery: (options) => {
28      options.query = `*[_id == $id][0] { 
29        "offeringImage": offeringImage.asset->url,
30        ...
31      }`;
32      return options;
33    },
34  });
35  await enhance({
36    composition,
37    enhancers: new EnhancerBuilder().parameterType(
38      CANVAS_SANITY_PARAMETER_TYPES,
39      sanityEnhancer
40    ),
41    context: {},
42  });
43}
44const Homepage = (props: PageProps) => {
45  return (
46    <PageComponent>
47      {// Components to go in here}
48    </PageComponent>
49  );
50};
51export default Homepage;

1. Import all the required modules and methods. 
2. Create a new instance of the Sanity client with your project ID and dataset to leverage the Sanity enhancer. 
3. Create an enhancer with the createSanityEnhancerClick to copy function.  By default, the Sanity enhancer does not enhance images, i.e., the image reference remains as is. Instead, the modifyQueryClick to copy option modifies the enhancer. The modified query matches Sanity’s query-language syntax, fetching all the data while adding an offeringImageClick to copy field with an image URL as the value. 
4. Pass the Composition and a prebuilt Sanity enhancer to the enhance function. Calling the sanityEnhancerClick to copy function with the raw Composition as an argument enhances it. 

Rendering the enhanced Composition

1import * as React from "react";
2import type {
3  GetServerDataProps,
4  GetServerDataReturn,
5  PageProps,
6} from "gatsby";
7// Other imports go in here
8// function to get composition
9export const getComposition = async () => {
10// function definition goes in here
11};
12// Function to fetch Composition server-side
13export async function getServerData({
14  headers,
15  method,
16  url,
17  query,
18  params,
19}: GetServerDataProps): GetServerDataReturn {
20  const composition = await getComposition();
21  // Enhance composition
22  await enhanceComposition(composition);
23  // Return enhanced composition
24  return {
25    status: 200,
26    props: { composition },
27  };
28}
29// Sanity enhancer function
30export async function enhanceComposition(composition: ComponentInstance) {
31// function definition goes in here
32}
33const Homepage = (props: PageProps) => {
34  const { serverData } = props;
35  return (
36    <PageComponent>
37      {// render components here}
38    </PageComponent>
39  );
40};
41export default Homepage;

1import * as React from "react";
2import type { PageProps } from "gatsby";
3import { PageComponent } from "../components/Page";
4import { Hero } from "../components/Hero";
5import { CTA } from "../components/CTA";
6import { GenericGrid } from "../components/GenericGrid";
7import { GenericCard } from "../components/GenericCard";
8import { OfferingCard } from "../components/OfferingCard";
9import { OfferingGrid } from "../components/OfferingGrid";
10import { ComponentInstance } from "@uniformdev/canvas";
11import { ComponentProps } from "@uniformdev/canvas-react";
12import { Default } from "../components/Default";
13// function to get composition
14export const getComposition = async () => {
15 // Function definition goes in here
16};
17// Function to fetch Composition serverside
18export async function getServerData({
19  headers,
20  method,
21  url,
22  query,
23  params,
24}: GetServerDataProps): GetServerDataReturn {
25 // Function definition goes in here
26}
27// Sanity enhancer function
28export async function enhanceComposition(composition: ComponentInstance) {
29  // Definition goes in here
30}
31// Resolve Render function
32export function componentResolutionRenderer(
33  component: ComponentInstance
34): React.ComponentType<ComponentProps<any>> {
35  switch (component.type) {
36    case "hero":
37      return Hero;
38      break;
39    case "callToAction":
40      return CTA;
41      break;
42    case "genericCard":
43      return GenericCard;
44      break;
45    case "genericGrid":
46      return GenericGrid;
47      break;
48    case "offering":
49      return OfferingCard;
50      break;
51    case "offeringGrid":
52      return OfferingGrid;
53      break;
54    default:
55      return Default;
56      break;
57  }
58}
59const Homepage = (props: PageProps) => {
60  return (
61    <PageComponent>
62      {// Render components here}
63    </PageComponent>
64  );
65};
66export default Homepage;

1import * as React from "react";
2import type {
3  GetServerDataProps,
4  GetServerDataRetur
5  PageProps,
6} from "gatsby";
7import { ComponentInstance } from "@uniformdev/canvas";
8import {
9  ComponentProps,
10  Composition,
11  Slot,
12} from "@uniformdev/canvas-react";
13// function to get composition
14export const getComposition = async () => {
15  // Definition goes in here
16};
17// Function to fetch Composition serverside
18export async function getServerData({
19  headers,
20  method,
21  url,
22  query,
23  params,
24}: GetServerDataProps): GetServerDataReturn {
25  // definition goes in here
26}
27// Sanity enhancer function
28export async function enhanceComposition(composition: ComponentInstance) {
29  // Definition goes in here
30}
31// Resolve Render function
32export function componentResolutionRenderer(
33  component: ComponentInstance
34): React.ComponentType<ComponentProps<any>> {
35  // Definition goes in here
36}
37const Homepage = (props: PageProps) => {
38  const { serverData } = props;
39  const { composition } = serverData as any;
40  return (
41    <PageComponent>
42      <Composition
43        data={composition}
44        resolveRenderer={componentResolutionRenderer}
45      ></Composition>
46    </PageComponent>
47  );
48};
49export default Homepage;

Enabling contextual editing in Uniform

1import * as React from "react";
2import type {
3  GetServerDataProps,
4  GetServerDataReturn,
5  PageProps,
6} from "gatsby";
7import { PageComponent } from "../components/Page";
8import {
9  ComponentProps,
10  Composition,
11  useContextualEditing,
12} from "@uniformdev/canvas-react";
13// All other imports go here
14// Sanity enhancer function goes here
15// Function to get composition goes here
16// Function to fetch Composition serverside for use in the page component, goes here.
17// Resolve Render function goes here
18const Homepage = (props: PageProps) => {
19  const { serverData } = props;
20  const { composition: initialCompositionValue } = serverData as any;
21  const { composition } = useContextualEditing({
22    initialCompositionValue,
23    enhance: async ({ composition }) => {
24      await enhanceComposition(composition);
25      return composition;
26    },
27  });
28  return (
29    <PageComponent>
30      <Composition
31        data={composition}
32        resolveRenderer={componentResolutionRenderer}
33      ></Composition>
34    </PageComponent>
35  );
36};
37export default Homepage

1. Set up useContextualEditingClick to copy with the initial compositionClick to copy value. 
2. Specify the enhancerClick to copy function for the Composition. 
3. Pass the new compositionvalueClick to copy to the Composition component.

Specifying the enhancerClick to copy function provides Uniform with the context of what enhancers are in use. Without that information, Uniform’s contextual-editing interface renders Component references instead of the enhanced version.

Personalizing the experience with Uniform Context

1. Set up the personalization artifacts and criteria on Uniform—usually done by practitioners and business users. 
2. Set up the front end to recognize Uniform Context. 

Setting up Signals in Uniform

Be sure to publish each time you change a Context entity.

Since you specified the Personalize Component as being allowed while defining the Page Component's Slot, you can add that Component to the Content Slot.

• Component: Hero
• Title: Ride for us
• Description: We don't just move people around. We move feelings and create lasting memories for people. Come join us to deliver joy!
• Image: https://img.freepik.com/premium-vector/online-car-rent-people-using-mobile-application-ordering-taxi-cab-car-sharing-woman-near-smartphone-screen-with-route-location-mark-city-map_458444-996.jpg
• CTAs
• Component: Call to Action
  • Title: Work with us
  • Link: #
• Component: Hero
• Title: Let’s Take a Ride
• Description: Wherever you want to be, let's take you there. Superfast. We put the joy in Joyride.
• Image: https://img.freepik.com/premium-vector/online-car-rent-people-using-mobile-application-ordering-taxi-cab-car-sharing-woman-near-smartphone-screen-with-route-location-mark-city-map_458444-996.jpg
• CTAs
• Component: Call to Action
• Title: Contact us
• Link: #

The visual pane in the middle is now broken because you must design the website to render personalized components. The next section shows you how to do that.

Personalizing the front end

1{
2  [...]
3  "scripts": {
4    "dev": "yarn uniform:download-manifest && gatsby develop",
5    "build": "yarn uniform:download-manifest && gatsby build",
6    "uniform:download-manifest": "uniform context manifest download --output ./uniform-manifest.json"
7  },
8[...]
9}

Your Uniform API key needs the correct permissions to download the manifest file. In case you encounter an error on lack of authorization in step 4, update the API key’s permissions in your Uniform account. 

1// gatsby-browser.tsx
2import "./src/styles/global.css"; // tailwind required
3import { UniformContext } from "@uniformdev/context-react";
4import {
5  Context,
6  enableContextDevTools,
7  ManifestV2,
8} from "@uniformdev/context";
9import manifest from "./uniform-manifest.json";
10import { GatsbyBrowser } from "gatsby";
11import * as React from "react";
12const context = new Context({
13  defaultConsent: true,
14  plugins: [enableContextDevTools()], // Use this to enable the Chrome plugin
15  manifest: manifest as ManifestV2,
16});
17export const wrapPageElement: GatsbyBrowser["wrapPageElement"] = ({
18  element,
19}) => {
20  return <UniformContext context={context}>{element}</UniformContext>;
21};
22Footer
23// gatsby-ssr.tsx
24import "./src/styles/global.css";
25import { UniformContext } from "@uniformdev/context-react";
26import {
27  Context,
28  enableContextDevTools,
29  ManifestV2,
30} from "@uniformdev/context";
31import manifest from "./uniform-manifest.json";
32import type { GatsbySSR } from "gatsby";
33import * as React from "react";
34const context = new Context({
35  defaultConsent: true,
36  plugins: [enableContextDevTools()], // Use this to enable the Chrome plugin
37  manifest: manifest as ManifestV2,
38});
39export const wrapPageElement: GatsbySSR["wrapPageElement"] = ({ element }) => {
40  return <UniformContext context={context}>{element}</UniformContext>;
41};

Taking the next steps

1. Create Components and a Composition on Uniform.
2. Connect it to a Gatsby and Sanity project. 
3. Set up the page's personalization and contextual editing on Uniform. 

1. Create more routes, fetch the Compositions in each of the pages, and render them on the page.
2. Manage the hierarchy and structure for your pages with Uniform’s Project Map. 
3. Create more Signal criteria or Context entities. 
4. Deploy your website to a hosting provider.