#Sidebar extension quickstart

#Introduction

Sidebar UI Extensions allows you to add custom widgets to Hygraph content editor sidebar.

You can add widgets to interact with specific fields on your editor like translations, to display information from 3rd party services, or to just display read-only information such as analytics data.

#What you will build

We will be building Google SERP Preview Sidebar UI Extension. It will display a preview of how your content would appear on Google Search Results.

You will also learn how to add custom configurations, like an API Key to connect to a 3rd party service provider, or a configuration to the widget instance like Background Color.

#Prerequisites

To complete this tutorial:

• You need the latest LTS version of Node.js installed on your machine. If you don't have it, you can download it here
• You should be comfortable using a command line tool and any IDE or text editor of your choice
• You should be familiar with JavaScript and React
• You need a free Hygraph account and a project. You can signup here.

#What you will learn

In this tutorial, you will learn:

• How to create a Sidebar UI Extension
• How to run and test Sidebar Extension UI Extension on your local development environment
• How to add Sidebar UI Extension to your Schema
• How to add custom configuration to your Extension, like an API Key
• How to deploy your Sidebar UI Extension to Vercel
• How to install and use your Sidebar UI Extension in production

#Step 1: Creating a UI extension

1. Create React project

# create a project with npm
npx create-react-app uix-google-serp-preview

# change directory
cd uix-google-serp-preview

Now, open the project in the code editor of your preference.

2. Create a new React component

// src/extensions/GoogleSerpPreview.js

const SerpPreview = () => {
  return <div>Google Serp Preview</div>;
};

const GoogleSerpPreview = () => {
  return <SerpPreview />;
};

export default GoogleSerpPreview;

3. Import the component into your app

// src/App.js

import GoogleSerpPreview from './extensions/GoogleSerpPreview';

function App() {
  return <GoogleSerpPreview />;
}

export default App;

4. Run the app locally

npm run start

By visiting http://localhost:3000 on your browser, you should see a very basic HTML input field.

Now, let's transform it into a Hygraph UI Extension!

#Step 2: Using Hygraph React SDK

1. Installing the React SDK

In order to transform it into a UI Extension, you must install Hygraph React SDK as a dependency on your project. You can do it running the following command on your Terminal:

yarn add @graphcms/uix-react-sdk

2. Adding React SDK

Now, let's import some SDK components and hooks from Hygraph SDK.

Start with importing the Wrapper component and useFormSidebarExtension hook from the library inside your React application.

You should add the following code at the top of the GoogleSerpPreview.js file.

// src/extensions/GoogleSerpPreview.js

import { Wrapper, useFormSidebarExtension } from '@graphcms/uix-react-sdk';

Then, add useFormSidebarExtension hook into SerpPreview and adjust the code accordingly, like the following example:

import { Wrapper, useFormSidebarExtension } from '@graphcms/uix-react-sdk';

const SerpPreview = () => {
  const { extension } = useFormSidebarExtension();

  return (
    <>
      <h3>{extension.name}</h3>
      <div>{extension.description}</div>
    </>
  );
};

Then, we need to add the extension declaration:

const declaration = {
  extensionType: 'formSidebar',
  name: 'Google SERP Preview',
  description: 'Preview your content on Google',
};

Finally, let's wrap our custom input field with the Wrapper component. Remember to pass in declaration:

const GoogleSerpPreview = () => {
  return (
    <Wrapper declaration={declaration}>
      <SerpPreview />
    </Wrapper>
  );
};

export default GoogleSerpPreview;

Your complete custom UI Extension code should look like this:

// src/extensions/GoogleSerpPreview.js

import { Wrapper, useFormSidebarExtension } from '@graphcms/uix-react-sdk';

const SerpPreview = () => {
  const { extension } = useFormSidebarExtension();

  return (
    <>
      <h3>{extension.name}</h3>
      <div>{extension.description}</div>
    </>
  );
};

const declaration = {
  extensionType: 'formSidebar',
  name: 'Google SERP Preview',
  description: 'Preview your content on Google',
};

const GoogleSerpPreview = () => {
  return (
    <Wrapper declaration={declaration}>
      <SerpPreview />
    </Wrapper>
  );
};

export default GoogleSerpPreview;

// App.js

import GoogleSerpPreview from './extensions/GoogleSerpPreview';

function App() {
  return (
    <div className="App">
      <GoogleSerpPreview />
    </div>
  );
}

export default App;

3. Testing UI extension on Localhost

At this point, you should see the "SDK connection error, check logs" message in your browser. The reason is that it's expected to be running from Hygraph application. So, you should just ignore this message for now.

Now, let's install and test your new Sidebar UI Extension on localhost by following these steps:

1. Go to https://app.hygraph.com and open any existing project

   If you don't have a project yet, use the Blog starter

2. Navigate to Project Settings > UI Extensions

3. Click on Add UI Extension button

4. On Extension URL field, enter http://localhost:3000

5. Click on Run compatibility test button

6. Finally, click on Authorize & Install.

If everything went well, you should see something like this:

UI Extension Install

#Step 3: Adding your sidebar UI extension to a schema

Now, it's time to use your new Sidebar UI Extension.

Follow these steps:

1. Go to Schema
2. On the left, click on the model you want to add the new Sidebar UI Extension
3. Now, click on Sidebar tab
4. On the right, under Custom Widgets section, you should see your new Sidebar UI Extension
5. Click on Google Serp Preview to add the widget to the sidebar
6. Enter the display name (Optional)
7. Finally, click on Create button

#Step 4: Using your sidebar UI extension

1. On the left navigation, go to Content
2. Select the model you've added the Sidebar UI extension in the previous step
3. Click on Create Item button on the top right corner or Edit and existing one

You should see Google Serp Preview in the sidebar. Now, let's add some funcionality to that!

#Step 5: Adding interaction between widget and content editor

First, let's add some styling to the widget, so that it looks like Google Search Results.

Go back to your Code Editor, open src/extensions/GoogleSerpPreview.js, and change SerpPreview component like so:

// src/extensions/GoogleSerpPreview.js

const SerpPreview = () => {
  const { extension } = useFormSidebarExtension();

  return (
    <div
      style={{
        padding: '10px',
        backgroundColor: '#fff',
      }}
    >
      <div
        style={{
          fontSize: '12px',
          marginBottom: '5px',
        }}
      >
        website.com
      </div>
      <div
        style={{
          fontSize: '16px',
          fontWeight: 'bold',
          color: 'blue',
          marginBottom: '5px',
        }}
      >
        Title here
      </div>
      <div>This is the description</div>
    </div>
  );
};

The widget should look like this: Google SERP Preview Sidebar Widget

Now, we need to display three information from the current content: Site URL, title, and description. Therefore, we should do two things:

1. Pick site URL
2. Map content title and description to be displayed in the widget

For that, we'll add custom settings to our Sidebar UIX: global and instance settings. Both should be added to extension declaration.

#Step 5.1: Displaying site URL

Once site URL is the same for the whole website, we'll add it to the extension declaration as a global configuration.

On your code editor, add the following code to extension declaration:

// src/extensions/GoogleSerpPreview.js

const declaration = {
  extensionType: 'formSidebar',
  name: 'Google SERP Preview',
  description: 'Preview your content on Google',
  config: {
    SITE_URL: {
      type: 'string',
      displayName: 'Site URL',
      required: true,
    },
  },
};

Then, change SerpPreview component like so:

const SerpPreview = () => {
  const { extension } = useFormSidebarExtension();
  const siteUrl = extension.config.SITE_URL;

  return (
    <div
      style={{
        padding: '10px',
        backgroundColor: '#fff',
      }}
    >
      <div
        style={{
          fontSize: '12px',
          marginBottom: '5px',
        }}
      >
        {siteUrl}
      </div>
      <div
        style={{
          fontSize: '16px',
          fontWeight: 'bold',
          color: 'blue',
          marginBottom: '5px',
        }}
      >
        Title here
      </div>
      <div>This is the description</div>
    </div>
  );
};

1. Go back to your browser and open your project dashboard
2. Go to Project Settings > UI Extension
3. On Google Serp Preview, click on the three dots and then click on Edit
4. Click Refresh next to the Edit button

Now, you should see the new Site URL field. Once it's a required one, enter any URL and hit the Update button.

Finally, go to any content and the URL should appear in the widget.

#Step 5.2: Displaying content title and description

Now, you should map the content fields that you want to display in the widget as Title and Description. Therefore, we'll add sidebar instance configuration, which you allow you to set these fields for each model.

Go back to GoogleSerpPreview.js in your code editor and do the following steps:

Import useState and useEffect hooks at the top of the file:

import { useState, useEffect } from 'react';

Then, change SerpPreview component like the following code:

const SerpPreview = () => {
  const {
    extension,
    form: { subscribeToFieldState },
  } = useFormSidebarExtension();
  const [title, setTitle] = useState('This is the title');
  const [description, setDescription] = useState('This is the description');

  const siteUrl = extension.config.SITE_URL;
  const sidebarConfig = extension.sidebarConfig;

  useEffect(() => {
    const unsubscribe = async () => {
      await subscribeToFieldState(
        sidebarConfig.TITLE_FIELD,
        (state) => {
          setTitle(state.value);
        },
        { value: true }
      );
    };
    return () => unsubscribe();
  }, [subscribeToFieldState, sidebarConfig.TITLE_FIELD]);

  useEffect(() => {
    const unsubscribe = async () => {
      await subscribeToFieldState(
        sidebarConfig.DESCRIPTION_FIELD,
        (state) => {
          setDescription(state.value);
        },
        { value: true }
      );
    };
    return () => unsubscribe();
  }, [subscribeToFieldState, sidebarConfig.DESCRIPTION_FIELD]);

  return (
    <div
      style={{
        padding: '10px',
        backgroundColor: '#fff',
      }}
    >
      <div
        style={{
          fontSize: '12px',
          marginBottom: '5px',
        }}
      >
        {siteUrl || 'website.com'}
      </div>
      <div
        style={{
          fontSize: '16px',
          fontWeight: 'bold',
          color: 'blue',
          marginBottom: '5px',
        }}
      >
        {title || 'Title here'}
      </div>
      <div>{description?.substring(0, 155) || 'Description here'}...</div>
    </div>
  );
};

Finally, change extension declaration like so:

const declaration = {
  extensionType: 'formSidebar',
  name: 'Google SERP Preview',
  description: 'Preview your content on Google',
  config: {
    SITE_URL: {
      type: 'string',
      displayName: 'Site URL',
      required: true,
    },
  },
  sidebarConfig: {
    TITLE_FIELD: {
      type: 'string',
      displayName: 'Title Field',
      required: true,
    },
    DESCRIPTION_FIELD: {
      type: 'string',
      displayName: 'Description Field',
      required: true,
    },
  },
};

Let me explain the code above:

• sidebarConfig is the object that stores sidebar configuration data. By declaring that, you should see two fields on sidebar widget dialog, where you will be able to enter the field names for title and description, respectively.
• form.subscribeToFieldState is a method from the Hygraph SDK to interact with form fields in the content editor. In this case, we'll update Google Serp Preview widget while user update information in the fields that stores Title and Description. You'll see that happening in a moment.

Once we've updated extension declaration again, we need to refresh UI Extension installation.

1. On Hygraph app, go to Project Settings > UI Extension
2. On Google Serp Preview, click on the three dots and then click on Edit
3. Click Refresh next to the Edit button
4. Finally, click on Update

Now, let's map Schema fields to the sidebar widget:

1. Go to Schema
2. Click on the model you've added the widget
3. Click in the pencil icon to edit widget

You should see 2 new fields: Title and Description. You just need to enter the appId of the fields you want to display as Title and Description, respectively. Then, click Update.

Finally, go to Content and click on any existing content to edit it or click on Create Item.

As you type in the Title or Description fields, you should see it being updated in realtime on Google Serp Preview widget!

#Step 6: Deploying your UI extension

To use your UI Extension in a live website or application, you should host it somewhere on the internet. For the sake of this tutorial, we will deploy it on Vercel. But you can use any hosting service.

Do the following steps:

1. Open your Terminal
2. Navigate into your project root directory and run npx vercel

cd google-serp-preview-uix
npx vercel

1. Follow the step-by-step guide on your Terminal
2. Once it's deployed, the extension URL will be automatically copied to your clipboard
3. Open your project dashboard on your browser
4. Go to Project Settings > UI Extension
5. On Hello UIX World, click on the three dots, then click on Edit
6. Click on Edit button next to the Extension URL field
7. Replace Extension URL field with the new URL
8. Click on the OK button
9. Finally, click on the Update button

#Congratulations!

You've just learned how to build Sidebar UI Extensions for Hygraph!

Take a look into these UI extensions examples for inspiration.

Additional resources

• React SDK
• Extension declaration
• Interacting with the form and other fields