Skip to main content

Overview

Prerequisites

This tutorial assumes you have the following:

  • Next.js knowledge - You only need basic-level experience with Next.js.
  • Uniform account - If you don't already have one, you can sign up for a free community tier account.
  • Uniform project - We recommend creating a new empty project in Uniform. This tutorial was written using an empty project. Depending on your account, you might not be able to create a new project. In this case you can use an existing project.
  • Uniform API key - This key must be assigned to your project and have rights to read and write to Canvas.

Repository

A repository is available that serves as a starting point for this tutorial. This saves you from having to write a lot of boilerplate code. You must clone the following reposity:

https://github.com/uniformdev/examples

The repository is set up using npm workspaces. The rest of this provides descriptions of the packages in the repository that you will build or use in this tutorial.

info

The files from this repository that are referenced in this tutorial are located under the following path:

/examples/docs/custom-integrations/basic/nextjs/no-uniform

Configuration app

In order for a Canvas user to select content from your data source you must provide an application for the user. You have complete control over this app. These instructions use Next.js, but you can build the application with any technology you like as long the app can be accessed using HTTP.

This configuration app is a basic Next.js app with the following changes:

tip

The configuration app only needs to be accessible to people who need to configure component parameters that use the custom integration. This means it does not have to be accessible from the internet. It can run within your own network. Uniform Canvas creates an iframe for the configuration app, so you can even run your configuration app locally.

Repository path

This package is located under apps/mesh-monsterpedia

Demo app

The demo app is a sample app that uses the custom integration. This includes the components and compositions defined in Canvas, along with a Next.js app that uses them.

Repository path

This package is located under apps/demo-monsterpedia

Components

The demo app uses the following front-end components:

  • Landing page layout - The main component in the Next.js page.
    • Canvas slot - Uniform component in the landing page layout component. This component enables Canvas editors to add components to the page without having to involve a developer.
      • Monster details - Component that expects an object that describes a monster in its props. It uses other components to display most of the information about the monster.
        • Ability scores - Component that visualizes the monster's ability scores.
        • Monster properties - Component that lists properties that describe the monster.
demo-app-components
tip

You don't have to build or modify these components. They are fully functional. However, Uniform Canvas provides the props that they use for content, so having a basic understanding of how these components work is helpful when completing this tutorial.

Storybook

You can test these components using Storybook. To start storybook,

  1. Open a terminal in the root of the repository.

  2. Run the following command:

    npm run storybook:basic
storybook-intro

Monsterpedia API client

Often times when you are working with an external system, a client library will be available for you to use. This is not always the case, however. For example, if your organization built an internal system, you may not have built a client library.

Another case is what we are faced with in this example: an external system whose API is so basic that there isn't a need for a client library. The D&D API is a simple REST API. However, in order to make this example as realistic as possible, we provide a client library for this API.

tip

During the tutorial you will not make any changes to this package. It is already fully implemented. However, you will use this package.

Repository path

This package is located under packages/monsterpedia

createClient()

- Parameters
baseUrlstring (optional)
Base URL used to make calls to the external system. If not specified, https://www.dnd5eapi.co is used.
- Return
ApiClientAn object that can be used to make calls to the D&D API.

ApiClient

- Functions
getMonster(index)
Gets details about a single monster.
  • indexstring - Identifier for the monster to retrieve.
Returns: object
getMonsters(filter)
Gets a list of all monsters.
  • filterstring (optional)- Only include monsters whose names match this value.
Returns: object[]
getUrl()
Gets the base URL used to make calls to the D&D API.
    Returns: string

    Enhancers

    In this example, a Canvas user will select a monster from an external system with the expectation that details about the monster will be displayed in the web app. Canvas only stores a value that identifies the monster that was selected, but the front-end requires the monster's details.

    The front-end developer shouldn't have to have any experience with the external system in order to use it. The goal of an enhancer is to make it as easy as possible for the front-end developer to retrieve the required data from the external system.

    Repository path

    This package is located under packages/canvas-monsterpedia