Welcome back everyone😃 Here we are with a new Contentful post. Today we are going to build a new integration using the App Framework 😁.

## Intro

Why do we build integrations? My answer, and probably the most common one is ... _**simplify the job to our final users/customers**_. The idea to help people in their daily job is satisfying to me.
What we are going to build is very simple and maybe an overkill but I want to demonstrate that even a small application can be useful to speed up your workflow (plus it has been fun to build it 🤓).
I'll skip some configuration steps so if you want to know how to setup a local environment you can follow this [guide](https://www.contentful.com/developers/docs/extensibility/app-framework/) or take a look at my [previous series](https://dev.to/wiommi/how-i-built-a-contentful-app-combined-with-commerce-js-i-5a77) on Contentful.

---

## The Concept

I work in the e-commerce business and the most exciting part is helping customers create and organise their content. In every project, there are always a few components that need to render a video and usually, it is a youtube video.
The most straightforward solution is to create a component with a simple text field in which the user needs to add the code or the embedded URL of the video. Here I see a few problems:

- Not every final user is technical, so you need to teach how to find the code/url. Maybe you need to write a guide with a few steps too.

- When you save this code, after a few days/weeks (maybe hours 😢) how can you understand easily which video it is?

- How many times a bad "copy&paste" leads to a bug opened in your board saying "the component is not working, I can't see the video" 🙄.

So the idea here is to build something that:

- It allows your customer not to leave the CMS interface.
- Provide a simple UI where you can search and preview your video.
- Once the video is saved, you give an overview of your selection.

Enough talking...Let's get it done 🥳 🚀

---

## YouTube Data API

We are going to use the YouTube Data API, so first, we need a valid API key that will be configured inside our Contentful App on the ConfigScreen location.

At the following [link](https://developers.google.com/youtube/v3/getting-started#before-you-start) you can find a guide on how to create your key. 
For our use case the key is enough. We don't need user authentication since we are retrieving only public data.

The last thing to keep in mind is the [Quota usage](https://developers.google.com/youtube/v3/getting-started#quota). We have access to a default 10,000 units per day which should be enough for us, but remember that every single search costs 100 units while every call to retrieve information about the selected video costs 1 + 1 units (one for the video endpoint and the other for the channel endpoint).

---

## Contentful: App Definition

The app definition is very simple. The idea is to extend the `short text` field type with our integration.


![Contentful: App Definition](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/m2zr4mjy16zbq6dkhtgt.jpg)

---

## Contentful: Config Screen

Now we can start with our first custom location. Inside the Config Screen, we can save our API key that would be accessible across our app as an installation parameter.


![Contentful: Config Screen](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/u7vejkeygdayrmn19teg.jpg)

---

## Contentful: Dialog

The Dialog location will be used as a container for our search.
The Modal will be triggered inside your Field location showing to our user a basic input text and a search button.

![Contentful: Dialog](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/go8j92uou1qrora8j7bi.jpg)

As soon as you search for a valid term a grid of results is shown. If more than 50 results are available for your search term a load more cta will be available at the bottom of the grid (every 'load more' click counts as a search so 100 units in our quota usage)


![Contentful: Dialog Results](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/b8w6l2mlusokds26lx6q.jpg)


![Contentful: Dialog Load More](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/u931zzjrkzslg14w7uw7.jpg)


If you hover with your mouse on a single result, two ctas will appear. The 'preview' cta allows you to see the video before selecting it. The 'select' cta lets you save the video in your field.


![Contentful: Dialog Mouse over](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/hz3gosl2hm60mwqm2o5n.jpg)

---

## Contentful: Field

Now our final location...
The Field lets you select/change/delete a video showing a preview card with some information about your selection.


![Contentful: Field - Empty](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/m0wz3j4w15kc9y9b41ll.jpg)


![Contentful: Field - Selected](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/52ocwe4oca2gz5yvl88h.jpg) 

---

## Conclusion

That's all folks! I hope you enjoyed the content.
Here you can find the repo with the project (https://github.com/williamiommi/contentful--youtube)

Thanks for reading!

See ya 🤙



Welcome back everyone😃 Here we are with a new Contentful post. Today we are going to build a new...

How to YouTubing 🏄 in Contentful

William Iommi

I’m a Tailwind CSS enthusiast even if I’m not using it (at the moment) in my daily work. I can’t give a proper answer but I see potential and I’m curious.

Are you using it within your team? Do you see some benefits during tech reviews?

👇👇👇

I’m a Tailwind CSS enthusiast even if I’m not using it (at the moment) in my daily work. I can’t give...

Can 'Tailwind CSS' improve your review process?

What is your workflow when you have to do a tech review and there are a bunch of CSS-like files?
Do you follow some guidelines? Do you build the feature branch somewhere? Or you just close your eyes 🙈, click on the 'Viewed' checkbox and let the QA guys do the rest? 😬

👇👇👇


What is your workflow when you have to do a tech review and there are a bunch of CSS-like files? Do...

discuss

How do you review CSS?

I did it!!! My website is live and I'm happy to share it with you all!
I hosted it on [Vercel](https://vercel.com) and you can reach it at the following URL:

[williamiommi.me](https://williamiommi.me)

I consider it other than a personal side project, a place where to share who am I and my beautiful pictures too 😂 😇.
I’m happy with the current status and it is definitely a version 1.0 but I’m already thinking of adding some extra sections soon.

The design is simple and minimal. I’m not a designer, but it was fun using Figma during the design process.

---

## The Stack 

Let's talk about what we have under the hood...

I used [Next.js](https://nextjs.org/) (w/ Typescript) as React framework. I like this product and I thought it was the right place to put my current knowledge into practice. Except for the gallery page, which is Server Side Rendered, all the other pages are statically generated and one of them has Incremental Static Regeneration too.

For styling, I used [Tailwind CSS](https://tailwindcss.com/), and well...it's amazing. I know, this topic could open a discussion about pros and cons but with my personal experience (a.k.a. my 2 cents) and If I see this tool applied in my daily job, I think the pros are greater than the cons.

Apart from these 2 'pillars', for animations I'm using [Framer Motion](https://www.framer.com/motion/), [Lodash](https://lodash.com/) for some utility methods and [react-masonry-css](https://github.com/paulcollett/react-masonry-css#readme) for the gallery grid.

---

### Special mentions

The writing page uses the [api](https://developers.forem.com/api/) provided by dev.to to retrieve all my posts. This is the page that uses Incremental Static Regeneration.

I host my pictures on Google Photos at the moment and the gallery pages are Server Side Rendered.
In the beginning, also these pages were statically generated and optimized with the Image optimization provided by Next. But I had some ‘data usage’ issues with Vercel because of my basic plan, so I removed the Image optimization and switch to SSR because of another issue related to Google Photos. They cache the URLs of every image for 1 hour and then the URL change, so I always need a fresh version of the image.
The cons, of course, is that I have to give up on a fast page load.

Last but (definitely) not least, a special thanks 🙏🏻 to [Lee Robinson](https://twitter.com/leeerob) [Spotify's Snippet](https://leerob.io/snippets/spotify) that I used in the footer with a custom UI. The snippet shows your current song playing on Spotify...Thanks, Lee 😃

---

## What Next?

As mentioned before, I would like to add a few extra sections but apart from that, the idea is to move all the copy to a CMS, improve performance on the gallery section and add also the Italian language, which is my native language 😃.


That's all folks! Thanks for reading!

Ciao / See ya 🤙

I did it!!! My website is live and I'm happy to share it with you all! I hosted it on Vercel and you...

Welcome to my website

Welcome back to my backyard lab, where I do my experiments drinking a lot of coffee to keep the pace 😂.

Currently, in my spare time, I'm working on my personal website and I want to share with you my process on how I built and animate the hamburger menu of the header.

---

#Preface

Animations are cool!! So why not complicate your life by animating some sections of your personal website? There is no better place to do it...

But...since I'm not an animation Guru, I asked for help from [Framer Motion](https://www.framer.com/motion), a React animation library by [Framer](https://www.framer.com).

My animation is pretty simple, the SVG has two lines (one is wider), on click/tap, the shorter one stretches reaching the max length and then I rotate both lines and create the X shape.

In this article I will show you 2 solutions that I implemented, called respectively:

* '**I don't know Framer Motion' solution (a.k.a. It works solution).**
* **'(Maybe) I know Framer Motion a little bit more' solution.**

---

#Design

Since I want to use SVG, firstly I created 3 shapes in [Figma](https://www.figma.com), representing my animation states. Every shape is inside a 24 x 24 box.

The first shape represent the 'closed' state:

![Hamburger - Closed](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/xh62wotmf5bvss0q1fqw.png)

The second, represent the middle state:

![Hamburger - Animating](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/jcp18osuv7otzkjzgl19.png)

The last one, represent the 'open' state, when animation is completed:

![Hamburger - Open](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/jivn3ze292ob5da7tu9j.png)

The following are the 3 SVG exported from Figma.

```xml

<svg width="24" height="24" viewBox="0 0 24 24" fill="none" xmlns="http://www.w3.org/2000/svg">
 <line y1="9.5" x2="24" y2="9.5" stroke="#FFFFFF"/>
 <line y1="14.5" x2="15" y2="14.5" stroke="#FFFFFF"/>
</svg>
```

```xml

<svg width="24" height="24" viewBox="0 0 24 24" fill="none" xmlns="http://www.w3.org/2000/svg">
 <line y1="9.5" x2="24" y2="9.5" stroke="#FFFFFF"/>
 <line y1="14.5" x2="24" y2="14.5" stroke="#FFFFFF"/>
</svg>
```

```xml

<svg width="24" height="24" viewBox="0 0 24 24" fill="none" xmlns="http://www.w3.org/2000/svg">
 <path d="M3.06061 2.99999L21.0606 21" stroke="#FFFFFF"/>
 <path d="M3.00006 21.0607L21 3.06064" stroke="#FFFFFF"/>
</svg>
```

---

#Tuning

The first problem I faced was about the line tags used in the first two SVG and the path used on the third.
So I decided to align everything with the path tag and I used this 'formula' that I found online:

```xml
d="Mx1 y1Lx2 y2"
```

So the first 2 SVG have become:

```xml

<svg width="24" height="24" viewBox="0 0 24 24" fill="none" xmlns="http://www.w3.org/2000/svg">
 <path d="M0 9.5L24 9.5" stroke="#FFFFFF"/>
 <path d="M0 14.5L15 14.5" stroke="#FFFFFF"/>
</svg>
```

```xml

<svg width="24" height="24" viewBox="0 0 24 24" fill="none" xmlns="http://www.w3.org/2000/svg">
 <path d="M0 9.5L24 9.5" stroke="#FFFFFF"/>
 <path d="M0 14.5L24 14.5" stroke="#FFFFFF"/>
</svg>
```

---

#Defining Variants

So, now that every SVG is aligned, I can start tuning the variants needed by Framer Motion in order to work.

[Variants](https://www.framer.com/docs/animation/#variants), combined with the motion component, let you define animations in a declarative way.
I created two objects where each key represents the state of the animation and every value contains the information about it, in my case the *d* attribute of the SVG path.

### Path 1
This is the top line/path. This line doesn't have a middle state so the object represents only the initial and final state.

```ts
const path01Variants = {
 open: { d: 'M3.06061 2.99999L21.0606 21' },
 closed: { d: 'M0 9.5L24 9.5' },
}
```

### Path 2
This line is the bottom one and since it is the only one that has a middle state, the following object contains three keys/states.

```ts
const path02Variants = {
 open: { d: 'M3.00006 21.0607L21 3.06064' },
 moving: { d: 'M0 14.5L24 14.5' },
 closed: { d: 'M0 14.5L15 14.5' },
}
```

---

#The 'I don't know Framer Motion' solution

Okay...what I've to do is pretty straightforward:

- click on the SVG
- start the animation
- repeat!


The problem I faced with variants and the animate property was that I was not able to create a sequence between animation states.
I couldn't start from 'closed', switch to 'moving' and finally reach the 'open' state.
Since I'm using React, I thought that my component state could have more than a boolean-like (open/close) value so I created an 'animation' state with 3 possible values: 'closed', 'moving' and 'open'.

But how to sequence them? Well...a good old setTimeout came to my rescue...

```tsx
const [animation, setAnimation] = useState('closed');
const onClick = () => {
  setAnimation('moving');
  setTimeout(() => {
    setAnimation(status === 'closed' ? 'open' : 'closed');
  }, 200);
};
```

and my return statement is:

```tsx
<button onClick={onClick}>
  <svg width='24' height='24' viewBox='0 0 24 24'>
    <motion.path
      stroke='#FFFFFF'
      animate={animation}
      variants={path01Variants}
    />
    <motion.path
      stroke='#FFFFFF'
      animate={animation}
      variants={path02Variants}
    />
  </svg>
</button>
```

Here the `animate={animation}` changes its state with the value inside my React state and then the proper variant inside 'pathXXVariants' is used.
I start with the 'moving' state and after 200ms I switch to open or closed (it depends on the previous state).

---

#The '(Maybe) I know Framer Motion a little bit more' solution

The previous solution works, but I find the 'setTimeout' as a loophole to do something that probably the library can handle in some different way and most important, even if probably this is not the case, using setTimeout and React come with some caveats so I could have used also something more 'React' as well.

Anyway, diving into the documentation a little bit more I found a React hook that could be helpful for my scenario.

The [useAnimation](framer.com/docs/animation/#component-animation-controls) hook creates an [AnimationControls](https://www.framer.com/docs/utilities/#animationcontrols)
object that has some utility methods which I can use to fine-tune my animation.
With AnimationControls I can start an animation and since this method returns a Promise I can also *await* that the animation ends and start the following one. So as you can imagine we have more control 😎.

I changed the React state back to a boolean and created 2 AnimationControls, one for each path.

```tsx
const [isOpen, setOpen] = useState(false);
const path01Controls = useAnimation();
const path02Controls = useAnimation();
```

our *onClick* handler now is a little bit more complicated but more Framer Motion friendly:

```tsx
const onClick = async () => {
  // change the internal state
  setOpen(!isOpen);
  
  // start animation
  if (!isOpen) {
    await path02Controls.start(path02Variants.moving);
    path01Controls.start(path01Variants.open);
    path02Controls.start(path02Variants.open);
  } else {
    path01Controls.start(path01Variants.closed);
    await path02Controls.start(path02Variants.moving);
    path02Controls.start(path02Variants.closed);
  }
};
```

I decided to tune the duration of the animation directly on the JSX but I could have also inserted it as the second argument of the *start* method or in the variant itself.

So the final JSX...

```tsx
<button onClick={onClick}>
  <svg width='24' height='24' viewBox='0 0 24 24'>
    <motion.path
      {...path01Variants.closed}
      animate={path01Controls}
      transition={{ duration: 0.2 }}
      stroke='#FFFFFF'
    />
    <motion.path
      {...path02Variants.closed}
      animate={path02Controls}
      transition={{ duration: 0.2 }}
      stroke='#FFFFFF'
    />
  </svg>
</button>
```

and here a little demo 😇

{% codesandbox silly-parm-u70gt runonclick=1 %}

---

#Final Thoughts

This is it!

I hope you enjoyed this little tutorial and if you found it helpful, drop a like or a comment.

If you know Framer Motion and you want to share your thoughts or an alternative/better solution...please do it!!!

If you think that Framer Motion is an overkill for this little animation...yeah you are probably right but it was fun learning something new 😉.

Thanks for reading!

See ya 🤙

Welcome back to my backyard lab, where I do my experiments drinking a lot of coffee to keep the pace...

Animate a Hamburger Menu with Framer Motion

The road so far...   It's time folks! The end of our journey through a Contentful App is...

How I built a Contentful App combined with Commerce.js (IV)

## Previously on...

In the first two parts of this series, we have talked about the App Framework, we defined our App and created a sample content type with a single JSON object field using our custom appearance.  If you missed them, click on the links above :point_up_2:.

In this part, we'll start with a step away from Contentful. With our free Commerce.js account, we are going to define some sample products and jot down the given public key.
After this, we'll be back on Contentful, working on the App Configuration location in order to see why and how to use the key provided by Commerce.js.

---

## An intro to Commerce.js

Commerce.js in a nutshell is a headless e-commerce backend platform that provides a set of API for products, categories, carts and so on. Of course, I simplified, however, since it's not the main scope of our series, if you want to know more about it, you can visit their  [website](https://commercejs.com/).

So why did I choose it? A JSON file with an array of products would have been enough for my customization on Contentful. However, I wanted to have something more realistic but still free (free for my needs of course).
Commerce.js with its free plan, give me access to a web application where I can create my dummy products and with its javascript SDK (more on that later) I can retrieve the data for my App.
&nbsp;
#### Commerce.js: Creating a merchant sandbox

I'm skipping the part about how to create a Commerce.js account, let's assume we have it already.
So at first login, we need to define a merchant providing a name, an email and a currency:

![Commerce.js - Merchant Form](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/6w3e9mnfvp6d5x9jtjmj.png)
&nbsp;
#### Commerce.js: Creating sample products

With a merchant created we have access to the Commerce.js dashboard that looks like this:

![Commerce.js Dashboard](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/9cgdduw179dg995jtv6k.png)
&nbsp;
In order to add some products, we need to click first on the _Products_ menu voice on the sidebar and then click the _add_ button.
&nbsp;
![Commerce.js Products View](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/cecoq0whbqf225osniga.png)

As you can see I have already created some dummy products but let's create a new one just to understand what information will be used by the Contentful App.

For our scenario we need to define the following attributes:

- Name
- SKU
- Price (only because is mandatory for Commerce.js)
- An image
- A Custom permalink (this will be used as our URL for the product)

![Commerce.js - Adding Product info - 01](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/e5kfdanj9h91021ae5a3.png)

![Commerce.js - Adding Product info - 02](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/lwsvqg3n4yeuhmhn1i9y.png)

When all fields are filled, leave the product as _active_ and click save.
We have defined a new product on Commerce.js.
&nbsp;
#### Commerce.js: API Keys

As I mentioned before, Commerce.js provides a set of API.
In order to use their SDK, we need to use a public key.
To get our key, we need to go to the _developer_ section and take note of the public sandbox key. This value will be used in the following section.

![Commerce.js - API Keys](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/nhsvbbgif9s3ltaibqm4.png)

---

## Customizing Contentful _App Configuration_ Location

We are back on Contentful and on our (running) local environment.
Now we need to design our first location: the _App Configuration_.
What is an App Configuration, where is it used and why we do want to customize it?
You can access it by clicking directly on your previously installed application (our Commerce Selector Demo App).
The next screenshot shows the default render of our react component which contains...well...nothing yet :smile:... except for a title and a paragraph.

![Config Screen - default render](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/qg1mf5pue9xsz9n2n819.png)

The purpose of this location, which is not mandatory, is to give the customer a user-friendly interface where he can configure some global parameters needed by our application. So you need to design some sort of form where the user can insert and save some kind of information.
Unlike the instance parameters (defined in part 1), these kind of parameters (and their respective values) are accessible to every content type that has a field implementing our custom appearance.
All these parameters are saved inside an object called `parameters.installation` which is accessible thanks to the SDK provided by Contentful.
&nbsp;
So why do we want to customize this section? The idea is to save here the public key provided by Commerce.js. We should implement an input field where the user can insert the key and maybe also a button to check if the key provided is valid or not.
&nbsp;
#### App Configuration: Overview

The file to customize is the ConfigScreen.tsx, let's see the 'out of the box' implementation.

```tsx
import React, { useCallback, useState, useEffect } from "react";
import { AppExtensionSDK } from "@contentful/app-sdk";
import {
  Heading,
  Form,
  Workbench,
  Paragraph,
} from "@contentful/forma-36-react-components";
import { css } from "emotion";

export interface AppInstallationParameters {}

interface ConfigProps {
  sdk: AppExtensionSDK;
}

const Config = (props: ConfigProps) => {
  const [parameters, setParameters] = useState<AppInstallationParameters>({});

  const onConfigure = useCallback(async () => {
    // This method will be called when a user clicks on "Install"
    // or "Save" in the configuration screen.
    // for more details see https://www.contentful.com/developers/docs/extensibility/ui-extensions/sdk-reference/#register-an-app-configuration-hook

    // Get current the state of EditorInterface and other entities
    // related to this app installation
    const currentState = await props.sdk.app.getCurrentState();

    return {
      // Parameters to be persisted as the app configuration.
      parameters,
      // In case you don't want to submit any update to app
      // locations, you can just pass the currentState as is
      targetState: currentState,
    };
  }, [parameters, props.sdk]);

  useEffect(() => {
    // `onConfigure` allows to configure a callback to be
    // invoked when a user attempts to install the app or update
    // its configuration.
    props.sdk.app.onConfigure(() => onConfigure());
  }, [props.sdk, onConfigure]);

  useEffect(() => {
    (async () => {
      // Get current parameters of the app.
      // If the app is not installed yet, `parameters` will be `null`.
      const currentParameters: AppInstallationParameters | null =
        await props.sdk.app.getParameters();

      if (currentParameters) {
        setParameters(currentParameters);
      }

      // Once preparation has finished, call `setReady` to hide
      // the loading screen and present the app to a user.
      props.sdk.app.setReady();
    })();
  }, [props.sdk]);

  return (
    <Workbench className={css({ margin: "80px" })}>
      <Form>
        <Heading>App Config</Heading>
        <Paragraph>
          Welcome to your contentful app. This is your config page.
        </Paragraph>
      </Form>
    </Workbench>
  );
};

export default Config;
```

Apart from some well-known _react_  imports, I want to focus on the _AppExtensionSDK_ import, which is the Typescript definition type that lets us know how the [Contentful SDK](https://www.contentful.com/developers/docs/php/sdks/) is implemented.
The other focus is on all the imports from _@contentful/forma-36-react-components_. [Forma36](https://f36.contentful.com/) is the open-source design system created by Contentful. Using this could be helpful if you want to keep the same 'Contentful UI' also for all of your customizations without worrying too much about style. Anyway, nobody will stop you from building your UI from scratch :smile:.
&nbsp;
#### App Configuration: Commerce.js package

Before starting our customization one thing is missing. We need to download the [Commerce.js SDK](https://commercejs.com/docs/sdk/getting-started#installation) in order to check if the provided key is valid. Let's install it on our local environment with the following CLI command:

```sh
npm install @chec/commerce.js 
```

and if you are using Typescript also this:

```bash
npm install --save-dev @types/chec__commerce.js
```
&nbsp;
#### App Configuration: Update imports

Cool, we are ready to go. Let's start importing some extra components (TextField, Button and Flex) from Forma36 and the default export from Commerce.js SDK:

```tsx
import {
  Heading,
  Form,
  Workbench,
  Paragraph,
  TextField,
  Button,
  Flex,
} from "@contentful/forma-36-react-components";
import Commerce from "@chec/commerce.js";
```
&nbsp;
#### App Configuration: AppInstallationParameters Interface

Since we are using Typescript we need to change the AppInstallationParameters interface with the following new version:

```tsx
export interface AppInstallationParameters {
  publicKey?: string;
}
```

We defined a new installation parameter of type string called publicKey. Doing this, Typescript will not complain about our next lines of code. But remember, Typescript is not mandatory, you can refactor everything in plain javascript.
&nbsp;
#### App Configuration: The new (outstanding :smile:) UI
Let's jump now to the return method of our component and implement our new interface.

```tsx
<Workbench
      className={css({
        margin: "80px auto",
        display: "flex",
        alignItems: "center",
      })}
    >
      <Form className={css({ padding: "20px" })}>
        <Heading>About Commerce Selector Demo</Heading>
        <Paragraph>
          The Commerce Selector Demo app allows editors to select products from their
          Commerce account and reference them inside of Contentful entries.
        </Paragraph>
        <hr />
        <Heading>Configuration</Heading>
        <Flex className={css({ alignItems: "flex-end" })}>
          <TextField
            className={css({ width: "50%", marginRight: "20px" })}
            labelText="Commerce.js Public Key"
            name="publicKey"
            id="publicKey"
            value={parameters.publicKey || ""}
            onChange={onPublicKeyChange}
            required
          />
          <Button disabled={!parameters.publicKey} onClick={onPublicKeyCheck}>
            Check Key
          </Button>
        </Flex>
      </Form>
    </Workbench>
```
So apart from some random text and CSS :smile: let's see what we have.
We added an input field where the user can insert the key with an _'onPublicKeyChange'_  callback on the onChange event. We added also a Button (disabled if there is no key) used to check if the provided key is valid or not. For the latter, we defined an _'onPublicKeyCheck'_  callback on the onClick event.
Of course, at the moment the code is complaining because we haven't defined these callbacks yet but let's see any way how the new UI looks.

![App Configuration: UI](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/6qk1bqma8z6o9cmoklkn.png)

Awesome right?!? :joy: ... Let's implement now those callbacks.
&nbsp;
#### App Configuration: onPublicKeyChange
The first is pretty straightforward:

```tsx
const onPublicKeyChange = (e: React.ChangeEvent<HTMLInputElement>) => {
    setParameters({ ...parameters, publicKey: e.target.value });
  };
```
We are leveraging on the inner state provided by the useState hook and we are saving the new value extracted from the event object. So on every input change, we have an updated version of our parameters.publicKey attribute.
&nbsp;
#### App Configuration: onPublicKeyCheck
This is a little bit complex but not too much. Basically, we want to call Commerce.js asking if recognize the key.
We will also use another feature provided by the Contentful SDK to show a success or an error message to the user.
Let's start with a utility method that calls Commerce.js:

```ts
const checkPublicKey = async (key: string | undefined) => {
  try {
    if (!key) return false;
    const commerce = new Commerce(key);
    await commerce.merchants.about();
    return true;
  } catch (e) {
    console.error(e);
    return false;
  }
};
```

This method receives in input the key, creates an instance of the Commerce class and calls the about method from the merchants service to check if everything is ok. If no errors are thrown we return a true otherwise a false.

Now let's see the the _onPublicKeyCheck_ callback:

```ts
const onPublicKeyCheck = async () => {
    if (await checkPublicKey(parameters.publicKey)) {
      props.sdk.notifier.success("The provided key is valid");
    } else {
      props.sdk.notifier.error("The provided Key is not valid");
    }
  };
```

This method calls the previously utility function and in both cases (valid or not) we are using the *notifier* feature provided by the Contentful SDK to show a success or an error message. We can see these two notifications in the following screenshots:

![Api Key Error](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/o81wws8mwqlpwjpk9rqt.png)

![Api Key Success](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/v8k5ofiaaddpoblrcu9w.png)
&nbsp;
#### App Configuration: onConfigure
We are almost done. The only thing left is to check if the key is valid when we save/update the App. When we save the app, the _onConfigure_ method is called so we need to use our utility method also in this case. We add this check before the default return. If the key is not valid we return false (showing an error message).

```ts
const onConfigure = useCallback(async () => {
    // ...
    // out of the box code
    // ...
    if (!(await checkPublicKey(parameters.publicKey))) {
      props.sdk.notifier.error("The provided Key is not valid");
      return false;
    }
    // ...
    // out of the box code
    // ...
  }, [parameters, props.sdk]);
```
Now we are sure that every time we save our app the key is valid.
This is the final ConfigScreen.tsx after our customization:

```tsx
import React, { useCallback, useState, useEffect } from "react";
import { AppExtensionSDK } from "@contentful/app-sdk";
import {
  Heading,
  Form,
  Workbench,
  Paragraph,
  TextField,
  Button,
  Flex,
} from "@contentful/forma-36-react-components";
import { css } from "emotion";
import Commerce from "@chec/commerce.js";

export interface AppInstallationParameters {
  publicKey?: string;
}

interface ConfigProps {
  sdk: AppExtensionSDK;
}

const checkPublicKey = async (key: string | undefined) => {
  if (!key) return false;

  try {
    if (key) {
      const commerce = new Commerce(key);
      await commerce.merchants.about();
      return true;
    }
  } catch (e) {
    console.log(e);
    return false;
  }
};

const Config = (props: ConfigProps) => {
  const [parameters, setParameters] = useState<AppInstallationParameters>({});

  const onConfigure = useCallback(async () => {
    // This method will be called when a user clicks on "Install"
    // or "Save" in the configuration screen.
    // for more details see https://www.contentful.com/developers/docs/extensibility/ui-extensions/sdk-reference/#register-an-app-configuration-hook

    // Get current the state of EditorInterface and other entities
    // related to this app installation
    const currentState = await props.sdk.app.getCurrentState();

    if (!(await checkPublicKey(parameters.publicKey))) {
      props.sdk.notifier.error("The provided Key is not valid");
      return false;
    }

    return {
      // Parameters to be persisted as the app configuration.
      parameters,
      // In case you don't want to submit any update to app
      // locations, you can just pass the currentState as is
      targetState: currentState,
    };
  }, [parameters, props.sdk]);

  const onPublicKeyChange = (e: React.ChangeEvent<HTMLInputElement>) => {
    setParameters({ ...parameters, publicKey: e.target.value });
  };

  const onPublicKeyCheck = async () => {
    if (await checkPublicKey(parameters.publicKey)) {
      props.sdk.notifier.success("The provided key is valid");
    } else {
      props.sdk.notifier.error("The provided Key is not valid");
    }
  };

  useEffect(() => {
    // `onConfigure` allows to configure a callback to be
    // invoked when a user attempts to install the app or update
    // its configuration.
    props.sdk.app.onConfigure(() => onConfigure());
  }, [props.sdk, onConfigure]);

  useEffect(() => {
    (async () => {
      // Get current parameters of the app.
      // If the app is not installed yet, `parameters` will be `null`.
      const currentParameters: AppInstallationParameters | null =
        await props.sdk.app.getParameters();

      if (currentParameters) {
        setParameters(currentParameters);
      }

      // Once preparation has finished, call `setReady` to hide
      // the loading screen and present the app to a user.
      props.sdk.app.setReady();
    })();
  }, [props.sdk]);

  return (
    <Workbench
      className={css({
        margin: "80px auto",
        display: "flex",
        alignItems: "center",
      })}
    >
      <Form className={css({ padding: "20px" })}>
        <Heading>About Commerce Selector</Heading>
        <Paragraph>
          The Commerce Selector app allows editors to select products from their
          Commerce account and reference them inside of Contentful entries.
        </Paragraph>
        <hr />
        <Heading>Configuration</Heading>
        <Flex className={css({ alignItems: "flex-end" })}>
          <TextField
            className={css({ width: "50%", marginRight: "20px" })}
            labelText="Public Key"
            name="publicKey"
            id="publicKey"
            value={parameters.publicKey || ""}
            onChange={onPublicKeyChange}
            required
          />
          <Button disabled={!parameters.publicKey} onClick={onPublicKeyCheck}>
            Check Key
          </Button>
        </Flex>
      </Form>
    </Workbench>
  );
};

export default Config;
```

---

## In the next episode...

We are finally ready to customize our Entry Field. In the next and final part, we'll call again Commerce.js in order to retrieve our dummy products, show them and let the user select one.

Stay :radio:
:heart:










Previously on...   In the first two parts of this series, we have talked about the App...

How I built a Contentful App combined with Commerce.js (III)

Welcome back :wave:...this is part 2 of this series. If you missed part 1, click the link above :point_up_2:.

## Previously on...

In part one, we saw the what and the why of our App and we finished with our **_App Definition_** configuration on the Contentful web app.

Now we need to install the app in our space/environment and associate it with an entry field.

---

## Installing the app on your Space

Inside your app details, you should be able to install the app in your space by clicking on the proper CTA.

![App Installation: init](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/e8s5ijv3rjvwly7lap67.png)

Here, you need to define the space and the environment

![App Installation: space and environment setup](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/uzivrj5m00w7ntfqing1.png)
######(_Your space and environment could be different_)
&nbsp;
Don't make my mistake, since in our previous episode we defined the frontend location as http://localhost:300, you need to have the app running on your local machine otherwise the installation will fail.

![App Installation: success](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/y5j72rls4pxwm1j1l7kp.png)

Now click on the Install button and you should see a success message. You just installed the app in your space, now we can use it :partying_face: :partying_face:.

---

## Define the appearance of our field.

As a prerequisite, I'm assuming you are already familiar with Contentful and I'll skip the part of the content type creation.
I have created a sample "Test Commerce Selector" content type in which we are going to define a field of type **JSON object**.

![Field Definition: entry field type selection](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/1ll9ujrd2c40uytkesyq.png)

Selecting the right field type is important, otherwise, our app will not be visible. In part 1, in our App Definition, we defined the Entry Field location as a JSON object so we need to select this type.

Let's define now the name of our field and click on **Create and configure** button.

![Field Definition: entry field name definition](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/zskwi4zssqxrgnxox0ne.png)

I'm skipping all the possible configurations on this field, our focus is on the Appearance tab.

If the app is installed properly you should see it near the default behaviour/appearance.

We need to select it, define our instance parameter with the Url option selected and finally confirm the configuration. This is how we are saying to Contentful to use our custom app for this specific field.

![Field Definition: entry field appearance and instance parameter definition](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/mt9yrtr3eqrwlscd5pzk.png)

###### _("Type" is the instance parameter defined in our **App Definition** step.)_
&nbsp;
We can see the result of our setup if we try to create an entry for our content type.

![Entry Field: initial definition](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/kth646dj8ecdg5y3dw8o.png)

"Hello Entry Field Component" is saying :thinking: :thinking:... If you remember in our components folder we have a bunch of .tsx files, let's open the **Field.tsx** component.

```tsx
import React from "react";
import { Paragraph } from "@contentful/forma-36-react-components";
import { FieldExtensionSDK } from "@contentful/app-sdk";

interface FieldProps {
  sdk: FieldExtensionSDK;
}

const Field = (props: FieldProps) => {
  // If you only want to extend Contentful's default editing experience
  // reuse Contentful's editor components
  // -> https://www.contentful.com/developers/docs/extensibility/field-editors/
  return <Paragraph>Hello Entry Field Component</Paragraph>;
};

export default Field;
```

Let's change the return of the component and see what happens.

```tsx
const Field = (props: FieldProps) => {
  // If you only want to extend Contentful's default editing experience
  // reuse Contentful's editor components
  // -> https://www.contentful.com/developers/docs/extensibility/field-editors/
  return <Paragraph>This is my commerce selector custom field</Paragraph>;
};
```

As soon as you save you'll see the updated output on the Contentful web app.

![Entry Field: update return](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/h6upya176azefmdqaadv.png)

---

## In the next episode...

Wow...this was very quick but so far so good. We created the app, installed it and defined a field with our custom appearance.
In part 3 we'll talk about Commerce.js, define some dummy products and start working on our App Configuration location.

Stay :radio:
:heart:

Welcome back 👋...this is part 2 of this series. If you missed part 1, click the link above 👆.       ...

How I built a Contentful App combined with Commerce.js (II)

Oh Hi :wave: and welcome to my very first blog post ever :rocket: ... be nice :blush:.

---

## Why I'm here?

Interested in the [JAM stack](https://jamstack.org/) architecture, I recently started playing with [Contentful](https://contentful.com), a headless CMS. I started an e-commerce POC project and after a week or two, I felt the need to dive deeper and try to build a Custom App. This is my journey about it (or at least a part of it :smile:)...let's go.

---

## Prerequisites

- Node.js installed on your machine (Contentful suggests the latest LTS version).
- Basic CLI knowledge.
- Javascript knowledge? Of course. Typescript? Yes, but not mandatory.
- Contentful knowledge and an account on their platform.
- Contentful Apps use React, so a basic knowledge is required (Hooks and Functional Components).
- An account on [Commerce.js](https://commercejs.com/). I used it for convenience, it has a free-plan and webhooks for products and categories.

---

## Warm up...

First thing first...What is a Contentful App and why do I need it in my project? The 'need' is subjective but yeah ok let's say we need it :grin:

### The What

Even if Contentful is a great headless CMS, it can't cover all the business requirements of a real project. The [App Framework](https://www.contentful.com/developers/docs/extensibility/app-framework/) lets you customize their web app for your needs.
A customer wants a blog post with a section that shows a pin on a google map? You can build a custom field that allows your customer to work directly with the map and pin a point without inserting coordinates.
This is just a simple example, the framework lets you customize the following sections of the cms:

- Entry Field
- Entry Sidebar
- Entry Editor
- Page
- Dialog
- App Configuration

If you want to know more about every single customization, you can go directly on [this page](https://www.contentful.com/developers/docs/extensibility/app-framework/locations/) of the Contentful website.

For our scenario, we will customize: App Configuration, Dialog and Entry Field.

When your app is complete, you can deploy it directly on Contentful (there is a bundle size limitation though) or host it somewhere else providing a public URL.

### The Why

So... apart from learning purposes, why do I need it?
Like I mentioned before, I'm working on an e-commerce POC using Nextjs, Contentful and Commerce.js.

I have editorial content (pages and components) defined on Contentful, Category and Product pages that gets data directly from Commerce.js.

But, what if I want to have a link in my navigation menu or in some Hero banner that points directly to a Product or a Category page? The quick solution of course is to have maybe a Link component on Contentful with a simple text field that contains the relative path...easy...done :grin: ...

What about typos? Or maybe ... what if I'm a lazy content editor and I want to just click buttons or more realistic, I'm a restricted user and I don't have access to the e-commerce platform in order to see myself the permalink/SKU of the product.

We should make life easier for our customers, we should provide a UX that lets our customers select a category or a product without leaving the Contentful interface... :bulb: :bulb: :bulb: ... let's finally build our App...

---

## Getting Started...

Contentful has a CLI tool that lets you start very quickly.
We can create our project folder (commerce-selector) with the following command:

```bash
npx @contentful/create-contentful-app init commerce-selector
```

This creates a **_commerce-selector_** folder. Inside of it, under the **_src_** folder we can find our **_components_** folder which contains the sections/locations we want to customize for our app (we will work on the highlighted files).

![Folder structure](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/emxbbreefioy5377j5fe.png)

But wait a second, this is a _create-react-app_ boilerplate under the hood, let's try to run `npm run start` on our terminal and visit http://localhost:3000 ...

![Localhost Message](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/cc6z8jqkycypcquihmhk.png)

Hmm...interesting...the message is pretty clear, our local environment is not meant to run on our machine but directly on the Contentful web app... let's see how...

---

## Creating the AppDefinition on Contentful

In our space on Contentful, we need to create an AppDefinition. Doing this we let Contentful know that our app exists. 
With this configuration, we can deploy the final app once finished but we can also use it as our development playground.
In our Organization settings, we need to go to the App Section and click the Create App button.

![App Definition: Create Button](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/wbot6gk1fh9j754crd9s.png)

We need to give our app a name and a frontend location. At the moment the URL will be our localhost.

![App Definition: Name and Frontend Location](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/aayhbogl3gq2rzqbzkaw.png)

As soon as we start typing the URL a bottom section will appear. Here we can choose which locations we want to customize. This is how Contentful knows where to show our app.
&nbsp;
We need to check **_App configuration screen_** and **_Entry Field_** (the Dialog Location will be used by the Entry Field itself).
For the Entry field, we need to specify also the data type of the field, in our case will be a JSON object.

![App Definition: App Locations Configuration](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/5o8v5bt46633ddlxwyif.png)

### Instance parameters

For our scenario, we need to do an extra step and define an instance parameter.
This kind of parameter is requested when you define the entry field in your content type, its value is specific for that field only.
The why for this parameter is because in my mind this app will be used not only for define category/product URLs but also for saving info about products/categories, used for example in some editorial components.

_Of course, nobody stops you to create specific apps for specific tasks, especially now that Contentful [increased the amount](https://www.contentful.com/developers/changelog/#increased-limits-for-apps) of installable apps for Team and Enterprise accounts._

Anyway...back on track...we need to define an instance parameter called 'type' (If you have more fantasy than me, use a different name :smile:).
It will be a required parameter, the **_Type_** will be **_Select_** and the **_Options_** will be the following:

- Url (we will focus on this one)
- Product
- Products
- Category
- Categories

![App Definition: Instance Parameter configuration](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/7cg3i6mr7s1vcb2ums1u.png)

Save and then click on Create button.
Congratulations :partying_face: :partying_face: you have created your first app...but the party is not over yet...

---

## In the next episode...

In part 2 we'll install the app in our space, we'll create our sample content type with a customized field...and we will start code something...or maybe not :smile:...

Stay :radio:
:heart:

Oh Hi 👋 and welcome to my very first blog post ever 🚀 ... be nice 😊.              Why I'm...

WRITING