Published on

Getting Started With Composable Experience Platform

Authors
Uniform

The use of the Jamstack allows developers to develop fast and reliable web applications by generating static web pages for faster performance. With this in place, frontend pages might be static; however, that doesn't imply that the data cannot be dynamic.



What is Uniform ?

In this tutorial, We'll take a look at Uniform, a composable Digital Experience Platform (DXP) that allows you to create your web fundamental building blocks, such as headless content management, headless commerce, modern CDNs, front-end frameworks, and personalization, everything under one powerful roof.

With this in place, developers can build front-end applications using their preferred libraries and frameworks whereas marketers and merchandisers can use no-code tools to design personalized, omnichannel digital experiences that blend content from multiple sources, including content management and commerce systems, without having to depend on developers to build custom integrations, enabling the fastest delivery across all channels.

Getting started

We'll demonstrate how to personalize a NextJS landing page by retrieving content from Uniform and showing it to our audience in this tutorial.

You'll need a free Uniform account to get started.

Scaffolding the NextJS application

NextJS is a React.js framework that improves developers' productivity by being simple and powerful. We will use the create-next-app utility to set up our project. Ensure you have yarn or npm installed on your local machine.

Navigate cd to the directory where you'd like to create the project and run the following command:

npx create-next-app uniform-landingpage --use-npm --example "https://github.com/musebe/Uniform-Application"

The command above runs the create-next-app tool, which bootstraps a Next.js application for you.It is going to use the landing page template through the --example flag.

After the installation, You will have a new directory called uniform-landingpage. Let’s navigate into it and spin up the development server by running the following command:

npm run dev
# or
yarn dev

This starts your Next.js app’s "development server" on port 3000.Let’s check to see if it’s working. Open http://localhost:3000 from your browser.

In order to make this tutorial easy to understand, we will focus on fetching data (content) from Uniform on the `Hero.js component found in the components folder of our application. The component contains dummy static data as shown below.

import React from 'react';
import { Container, Row, Col } from 'reactstrap';

const Hero = () => {
  return (
    <section className="section position-relative">
      <Container>
        <Row className="align-items-center">
          <Col lg={6}>
            <div className="pr-lg-5">
              <p className="text-uppercase text-primary font-weight-medium f-14 mb-4">Lorem Ipsum</p>
              <h1 className="mb-4 font-weight-normal line-height-1_4">Simply dummy text of the printing <span className="text-primary font-weight-medium">Name</span></h1>
              <p className="text-muted mb-4 pb-2">Lorem Ipsum has been the industry's standard dummy text ever since the 1500s, when an unknown printer took a galley of type and scrambled it to make a type specimen book. It has survived not only five centuries, but also the leap into electronic typesetting, remaining essentially unchanged.</p>
              <a href="#" className="btn btn-warning">
                Find Out How <span className="ml-2 right-icon">&#8594;</span>
              </a>
            </div>
          </Col>
          <Col lg={6}>
            <div className="mt-5 mt-lg-0">
              <img src="/images/Group Members.png" alt="" className="img-fluid mx-auto d-block"/>
            </div>
          </Col>
        </Row>
      </Container>
    </section>
  );
}

export default Hero;

Its time to fetch data dynamically from Uniform.

Creating a Uniform Project

Upon signing up, you will be redirected to create a new project. For this tutorial, name the project landingPage then select the Guided setup tab as we use some already configured steps to set up the architecture of our application. Press the continue button to go to the next step as illustrated below :

Uniform-start

Next, select Contentful and Sanity as the content management systems from which we will obtain data in a future tutorial. Select Next.js as the frontend framework of your choice, and click on the continue button to proceed.

The next step involves connecting Uniform to the Content management systems(CMS) you selected. You can either link them at this stage or a later stage. For this tutorial, all the data will be fetched directly from Uniform. Watch out for more content on retrieving data from different CMSs.

Uniform-selection

To finalize the first step of the setup, copy your environment variables and create a .env.local file inside your NextJS project and paste them there as they will act as our project's dependencies. Finally, click the take me to dashboard button.

Uniform-selection

Components And Compositions setup

As a first step, we need to create the Uniform Canvas. In Uniform, A Canvas allows business users to have complete control over the presentation layer and build compositions from components sourcing data from different headless platforms and content management systems.

On the Navbar section, select the Canvas button. You will find a menu with different options on the left side of the Canvas dashboard.

First, we need to create the Hero Component Library structure as described in the Hero.js component in our application. A component library is where you define all your application components in Uniform. As a general rule, the definitions of the components are mapped to the components in your frontend frameworks.

To start building the components select Canvas then Component Library as shown below.

Canvas

At this point we need to define the following configurations for the Hero component:

  • Component Name : Hero
  • Public ID : hero (This is automatically generated)
  • Component Icon : Choose an icon of your choice

Next, we need to add the parameters that will go into the component. In a react context, parameters can be thought of as props. For our case we will need the following :

  • Caption : Text
  • Paragraph : Text
  • Headline : Text

As illustrated below :

component

Next, we are going to create a composition by the name Page that is going to house other components such as the Hero component we created above.

To create a composition, we'll first create a component just like we did above but this time, we will need to check the composition box inside the component library to be able to give this component the power to house other components as highlighted below

composition

On the Page composition we are going to enable slots, This is going to enable child components added to it. Navigate to the slots and click the red button. Then select the components and configurations you will need. For our application we shall name the slot Home then under the home we shall select the Hero component as shown below :

slots

Once done click the OK then the `Save & close button to save the configurations. After that, we'll add our new Composition. Click the big red plus button in the Compositions area of the sidebar.

We'll create our real Composition here. To begin, choose the 'Hero' Composition Component type, name the Composition 'Homepage,' and then click Create as highlighted below :

fstage

When you click the Create button, you'll be redirected to the Composition editor, sometimes known as the "Canvas."

Click the plus button on the page and select the hero component on the screen that will appear. We can now see fields that represent the parameters we created in the previous phase.

Copy and paste the data from the Hero component in the NextJS application as highlighted below. Once done click the save button and we are now ready to start pulling data from our uniform Canvas to the NextJS application.

final-comp

Setting up Uniform Canvas in NextJS

To interact with the Uniform platform on our Next application, we will first need to install the Uniform Canvas SDK dependencies on our project. Run the following command on your projects directory terminal to do the installation :

  npm install @uniformdev/canvas @uniformdev/canvas-react @uniformdev/cli

After the installation is complete open your applications pages/index.js file and import the following Canvas client at the top of the page :

import { CanvasClient } from '@uniformdev/canvas';
import { Composition, Slot } from '@uniformdev/canvas-react';

Data fetching from Uniform

To pull data from uniform to our application we will use the getStaticProps function. This will enable NextJS to pre-render this page at build time using the props returned by getStaticProps.

Under the Index function, paste the following code :


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

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

  // set `composition` as a prop to the route
  return {
    props: {
      composition,
    },
  };
}

In the above code, we first configured the CanvasClient. In the configurations we set up the 'UNIFORM_API_KEY' and 'UNIFORM_PROJECT_ID'. Since we had already created a .env.local file the data is being read from the file securely.

Then in the next function, we use the getCompositionById method to access the composition we created above in Uniform. Remember to replace the section with your projects ID which can be accessed through navigating to the project you created in the Uniform Dashboard, click on the three dots and select settings, then scroll down to the bottom of the page and you'll view your projects Id.

The next step is to pass the composition we get from the props into the applications state. This can be achieved with the following code :


const Index = ({ composition }) => {
  return (
    <Layout pageTitle='Landing Page Nextjs'>
      <Header />
      <Composition data={composition} resolveRenderer={resolveRenderer}>
        <Slot name='content' />
      </Composition>
    </Layout>
  );
};


At the top of the page, we earlier imported the Composition and Slot components from uniformdev/canvas-react'. We use the components nicely to format the data we receive on our application. To view the raw data before passing it down to the Hero component you can use the following :

 <pre>{JSON.stringify(composition, null, 2)}</pre>

At this point all the data from uniform is available in our applications state. Lets pass it down to the Hero.js component so that the components data can be fully controlled by the Uniform Canvas.

Navigate to the components/Hero.js file and change it to this :


import React from 'react';
import { Container, Row, Col } from 'reactstrap';

const Hero = ({ caption, paragraph, headline }) => {
  return (
    <section className='section position-relative'>
      <Container>
        <Row className='align-items-center'>
          <Col lg={6}>
            <div className='pr-lg-5'>
              <p className='text-uppercase text-primary font-weight-medium f-14 mb-4'>
                {caption}
              </p>
              <h1 className='mb-4 font-weight-normal line-height-1_4'>
                {headline}{' '}
                <span className='text-primary font-weight-medium'>Name</span>
              </h1>
              <p className='text-muted mb-4 pb-2'>{paragraph}</p>
              <a href='#' className='btn btn-warning'>
                Find Out How <span className='ml-2 right-icon'>&#8594;</span>
              </a>
            </div>
          </Col>
          <Col lg={6}>
            <div className='mt-5 mt-lg-0'>
              <img
                src='/images/Group Members.png'
                alt=''
                className='img-fluid mx-auto d-block'
              />
            </div>
          </Col>
        </Row>
      </Container>
    </section>
  );
};

export default Hero;

With all this done am sure you wondering why you aren't able to view the Hero.js component data in your application. Time to change that !!!

After importing the Hero.js in the index.js component. Add the following above the index.js function

const resolveRenderer = (component) => {
  // choose the component based on the Canvas component type
  // (you can also use a Map, switch, next/dynamic, etc here)
  if (component.type === 'hero') {
    return Hero;
  }

  return null;
};

Uniform uses the resolveRenderer function to conditionally render components. With all this done your application should look like this :

finally

Conclusion

From the above simple demo, we can view how simple it is to integrate the Uniform canvas with Next.js applications. Feel free to fork the final application on Github and add other components to the composition then render them in the other components inside the application.

In the next tutorial, we will be continuing with the build now fetching data from Headless CMS's such as Sanity and Contentful.