Hello everyone! In this brief article, we will explore how to customize a feature offered by [Sanity.io](https://www.sanity.io).

The feature in question is called [Field Groups](https://www.sanity.io/docs/field-groups). This functionality allows you to define groups within your document/object and associate them with individual fields. As a result, within the Studio, the fields are visually separated into tabs. 

This option is incredibly useful when you want to group fields that are related to each other (a classic example being an SEO group where there are only fields related to the specific theme).

In addition to the groups you define, the platform inserts an uncustomizable 'All Fields' group in the first position, which contains all fields regardless of their group membership.

However, there's currently one thing that isn't possible (unless done manually for each individual document) and which I believe could be quite useful — having a dynamic group dedicated to fields that aren't associated with any of the custom groups, for any reason.

Here's what we'll cover today:

- Creation of a dynamic group called 'Unmapped fields'
- Bonus: Through a small hack, we will remove the 'All fields' group.

---

## 🧑‍💻 Create a dynamic group

One of the things I appreciate about Sanity is its high level of customization flexibility. As mentioned earlier, we don't want to create this group for every document we have, but since the Sanity Studio is 'just' Javascript, we can find a way to achieve what we want.

Let's start by defining what our function should do:

- Receive our documents/objects as input
- Determine whether each document has fields without an associated group
- Create the dynamic group and place it at the end of the available custom groups
- Associate this group with the necessary fields.

```ts
// some-utility-method-file-blah-blah.ts
import {DocumentDefinition, FieldGroupDefinition, ObjectDefinition} from 'sanity'
import {LinkRemovedIcon} from '@sanity/icons'

// this is the definition of our custom group for unmapped fields
const unmappedFieldsGroup: FieldGroupDefinition = {
  name: 'unmapped-fields',
  icon: LinkRemovedIcon,
  title: Unmapped Fields
}


type DocumentObjectDefinitionType = DocumentDefinition | ObjectDefinition

export const enhancedGroupsDefinition = (definitions: DocumentObjectDefinitionType[]): DocumentObjectDefinitionType[]  => {
  
  const doMagic = (def: DocumentObjectDefinitionType) => {
    // Check if your document/object has any groups defined.
    if (def.groups && Array.isArray(def.groups) && def.groups.length > 0) {
      
      // Check if every field has a group defined.
      const everyFieldsHaveGroup = !!def.fields.every(
        (field) =>
          typeof field.group === 'string' || (Array.isArray(field.group) && field.group.length > 0)
      )

      // If some fields don't have a group, we can add our custom group.
      if (!everyFieldsHaveGroup) {
        // Add our custom group at the end of the list.
        def.groups.push(unmappedFieldsGroup)
        // Loop through all fields and add the unmapped group if a group is not defined.
        def.fields = def.fields.map((field) => {
          if (!field.group || (Array.isArray(field.group) && field.group.length === 0))
            field.group = unmappedFieldsGroup.name
          return field
        })
      }
    }
    return def
  }

	// map every definitions with our doMagic function
  return definitions.map(doMagic)
}
```

Now we can go to the 'sanity.config.ts' file (or wherever we have defined our schemas) and enhance our definitions.

```ts
// sanity.config.js
import {enhancedGroupsDefinition} from '../../some-utility-file-blah-blah'

defineConfig({
  // your configuration
 schema: {
    types: [
      ...enhancedGroupsDefinition([Document1, Document2]),
    ],
  },
})
```

What we achieve is a dynamic group that contains only the unmapped fields and disappears as soon as all fields are associated with a group. Naturally, being a custom group, you can change its name or icon as you prefer.

---

## ⭐️ Bonus: Remove the 'All fields' group
<div>&nbsp;</div>
> 🚨 I consider this to be a minor 'hack', so please take this into consideration. Currently, I have only noticed a minor side effect that you should be aware of, and I will explain it later.

To remove the group, we need to make changes within the 'sanity.config.ts' file and modify the following object `form->components->input` like this:

```ts
// sanity.config.js
import {isObjectInputProps} from 'sanity'
import {enhancedGroupsDefinition} from '../../some-utility-method-file-blah-blah'

defineConfig({
  // your configuration
  form: {
    components: {
      input: (props) => {
        if (isObjectInputProps(props) && Array.isArray(props.groups) && props.groups.length > 0) {
          if (props.groups[0].name === 'all-fields') {
            props.groups.shift()
          }
        }
        return props.renderDefault(props)
      },
    },
  },
})
```

This is the final result:

![Unmapped fields](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/yz4w87l45rx1tzmpy7ul.jpg)
<div>&nbsp;</div>
### 🚨 Known issue:

As mentioned earlier, with the removal of the 'All fields' group, I have currently noticed only one side effect that occurs when the 'Review changes' sidebar is opened. Here are the differences:


<figure>
<img src="https://dev-to-uploads.s3.amazonaws.com/uploads/articles/tx1d5hjhchynv4fw1kmb.jpg" alt="Before" style="width:100%">
<figcaption align = "center"><b>Before</b></figcaption>
</figure>


<figure>
<img src="https://dev-to-uploads.s3.amazonaws.com/uploads/articles/7b2o84ch7t4hco37hw26.jpg" alt="After" style="width:100%">
<figcaption align = "center"><b>After</b></figcaption>
</figure>

---

## 👋 Conclusion

Today we saw how even with a simple function, it's possible to enhance your experience within the Sanity Studio by introducing a customization that can be useful for your clients. This is one of the things I like the most about Sanity.

Thanks for reading!

See ya 🤙











Hello everyone! In this brief article, we will explore how to customize a feature offered by...

A Guide to Field Groups and Dynamic Customization in Sanity.io

William Iommi

Hello and welcome back. Over the last few months, I have been exploring a new CMS, or to be more precise, a new Composable Content Cloud Platform, called [Sanity](http://sanity.io/).

As usual, I get bored pretty easily with the out-of-the-box features 😄 , and I like to enhance the authoring experience with customizations.

This will not be an article about the pros and cons or a product review. Instead, we are going to build a plugin and see what the platform offers in terms of customizations.

Let's have some fun, guys!👨‍🔬 🚀

---

- <a href='#the-why-behind-this-plugin'>The why behind this plugin</a>
- <a href='#dev-endpoints'>DEV endpoints</a>
- <a href='#init-sanity-plugin-with-pluginkit'>Init Sanity plugin with plugin-kit</a>
- <a href='#document-structure'>Document structure</a>
- <a href='#custom-components'>Custom components</a>
- <a href='#custom-workflows-with-document-actions'>Custom workflows with document actions</a>
- <a href='#body-serialization'>Body serialization</a>
- <a href='#demo'>Demo</a>
- <a href='#next-steps-and-final-thoughts'>Next steps and final thoughts</a>


---

## The why behind this plugin

The idea behind this plugin was to address a personal need I had.

Currently, on my personal website, I have a "writing" section that contains links to the articles I publish on [DEV](http://dev.to/). 

I use an endpoint provided by the platform to retrieve all my published articles and display them as links that redirect to the corresponding article. 

However, my end goal, besides experimenting with Sanity, is to display full articles on my personal website with a custom design. 

But at the same time, I want to be able to publish the same content on [DEV](http://dev.to/), without leaving the Sanity Studio and without having to manually copy and paste the article content. I want a seamless integration that allows me to achieve both objectives with ease.

---

## DEV endpoints

DEV is built on the Forem platform. The latter provides a series of [endpoints](https://developers.forem.com/api) that, through an API key generated by your DEV account, allow you to retrieve the articles you have published, as well as create, update, and publish articles.

For this plugin, we will be using the following endpoints:

- **[https://dev.to/api/articles**](https://developers.forem.com/api/v0#tag/articles/operation/createArticle) (a POST call to create an article)
- **[https://dev.to/api/articles/{id}](https://developers.forem.com/api/v0#tag/articles/operation/updateArticle)** (a PUT call to update an article with a specific ID)
- **[https://dev.to/api/articles/me/all](https://developers.forem.com/api/v0#tag/articles/operation/getUserAllArticles)** (this GET call retrieves all the articles of a user, and in my custom implementation, it will returns the linked article)

To obtain the API key on DEV, you need to go to the following link and generate the key in the appropriate section:


![Image description](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/3hlmbixeknctf8y0xhjl.jpg)

As stated by the documentation, all the above endpoints are CORS-disabled.

This means that it is not possible to call them directly within the browser, and therefore within our plugin.

To overcome this, we will need to make these calls on the server-side. In my case, using the Studio within my Next.js project, I will use [API Routes](https://nextjs.org/docs/api-routes/introduction) to make these calls.

As for how these calls will be implemented, they are out of scope for the article. 

Below are some points to consider:

- All calls must respect the documentation and always return a valid article object.
- The GET receives a query parameter 'articleId' from the plugin.
- The POST and PUT receive the article to be saved in the request body.

As we will see shortly, the plugin receives 3 input parameters representing the URLs to be called for proper functioning.

---

## Init Sanity plugin with plugin-kit

For the creation of the plugin, we will use the official Sanity package, **[@sanity/plugin-kit](https://github.com/sanity-io/plugin-kit)**. 

It is a set of tools and utilities that help simplify the process of building plugins.

Following the provided documentation, we can start by running the following script:

```
npx @sanity/plugin-kit@latest init sanity-plugin-devtoarticle
```

After following the setup proposed by the script, you will end up with the following folder structure:


![Image description](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/ox2hzp5635zh0oa63iew.jpg)

The file that we are most interested in is `index.ts` inside the `src` folder.

```ts
import {definePlugin} from 'sanity'

interface DevArticleConfig {
  /* nothing here yet */
}

export const DevArticle = definePlugin<DevArticleConfig | void>((config = {}) => {
  return {
    name: 'sanity-plugin-devtoarticle',
  }
})
```

As previously anticipated, API calls will be made on the server-side. What the plugin needs to know is only where to make them. For this reason, we will define mandatory input parameters to be provided when using the plugin inside the Studio:

```ts
interface DevtoArticleConfig {
  api: {
    get: string // api/devto/article/get
    create: string // api/devto/article/create
    update: string // api/devto/article/update
  }
}
```

In my specific case, using the plugin inside a Nextjs project, the URLs will be relative paths to the `api` folder under `pages`.

---

## Document structure

The main functionality of the plugin is to provide a Content Model called “**DEV Article”** with a set of fields necessary for creating the article on the external platform.

- An Object field in read-only mode with a custom component, containing information from DEV: article ID, a flag to indicate whether the article is published or not, the generated slug, and the updateAt date.
- Title
- Description
- Cover Image
- Body: represented by a Portable Text Sanity capable of handling some custom blocks.
- Tags: an array of strings containing up to 4 values.
- Series: to identify whether the article belongs to a series of articles.
- Canonical Url
- Organization Id

Below you can see how it is defined in the code:

```ts
const DevtoArticle = (config: DevtoArticleConfig) =>
  defineType({
    type: 'document',
    name: 'devto.article',
    title: 'DEV Article',
    icon: FaDev, // an icon from react-icons
    preview: {
      select: {
        title: 'title',
        subtitle: 'description',
        media: 'cover_image',
      },
    },
    fields: [
      defineField({
        type: 'object',
        name: 'devto',
        title: 'DEV',
        readOnly: true,
        components: {
          field: (props) => DevField({...props, config}),
        },
        fields: [
          defineField({
            type: 'number',
            name: 'id',
            title: 'DEV ID',
          }),
          defineField({
            type: 'boolean',
            name: 'isPublished',
            title: 'Is Published',
          }),
          defineField({
            type: 'slug',
            name: 'slug',
            title: 'Slug',
          }),
          defineField({
            type: 'datetime',
            name: 'updatedAt',
            title: 'Updated At',
          }),
        ],
      }),
      defineField({
        type: 'string',
        name: 'title',
        title: 'Title',
        validation: (Rule) => Rule.required(),
      }),
      defineField({
        type: 'text',
        name: 'description',
        title: 'Description',
        rows: 5,
      }),
      defineField({
        type: 'image',
        name: 'cover_image',
        title: 'Cover Image',
        validation: (Rule) => Rule.required(),
      }),
      defineField({
        type: 'array',
        name: 'body',
        title: 'Body',
        validation: (Rule) => Rule.required(),
        of: [
          {
            type: 'block',
            marks: {
              decorators: [
                {title: 'Strong', value: 'strong'},
                {title: 'Emphasis', value: 'em'},
                {title: 'Code', value: 'code'},
                {title: 'Underline', value: 'underline'},
                {title: 'Strike', value: 'strike-through'},
                {
                  title: 'Inline Katex Notion',
                  value: 'devto.katexinline',
                  icon: TbMathFunction,
                  component: KatexInlinePreview,
                },
              ],
            },
          },
          {type: 'devto.image'},
          {type: 'code'},
          {type: 'devto.details'},
          {type: 'devto.embed'},
          {type: 'devto.katexblock'},
        ],
      }),
      defineField({
        type: 'array',
        name: 'tags',
        title: 'Tags',
        options: {
          layout: 'tags',
        },
        of: [
          {
            type: 'string',
          },
        ],
        validation: (Rule) => Rule.max(4),
      }),
      defineField({
        type: 'string',
        name: 'series',
        title: 'Series',
      }),
      defineField({
        type: 'url',
        name: 'canonical_url',
        title: 'Canonical URL',
      }),
      defineField({
        type: 'number',
        name: 'organization_id',
        title: 'Organization ID',
      }),
    ],
  })
```

---

## Custom components

Based on the definition of the document provided in the previous paragraph, in addition to several basic fields, there are also some custom ones. Let's take a closer look at them together:
<br>
#### <u>DevField</u>

```ts
components: {
  field: (props) => DevField({...props, config}),
},
```

The custom component DevField is defined within the object containing the information extracted from DEV.

Inside the *components* object, we are going to override the field attribute. This operation, as indicated by the [documentation](https://www.sanity.io/docs/form-components), allows us to replace the UI of the entire field.

Our custom component receives, in addition to the default props, an object 'config' that represents the input parameters of the plugin. We will in fact need the 'get' URL to retrieve the article information and display them.


![DevField - draft UI](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/pec5qluhuasl0cm2safn.jpg)

As you can see, the component represents a summary of the article present on DEV. We have retrieved some useful information such as likes, comments, views, and reading time.

In addition to the title, description, and author, we also show the article status with a badge above the cover.

The 'Show Info' button, instead, allows you to see the data actually saved in the field, which, as previously indicated, are: id, isPublished flag, slug, date of last update.


![DevField - modal UI](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/a8xnx96iem92afn0m5bg.jpg)

If the article is published on DEV, we also have some links available on the right side:


![DevField - published UI](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/2i1q8hxzftvztl7s75jq.jpg)
<br>
#### <u>Portable Text Blocks</u>

Portable Text is a powerful feature within Sanity that allows for a high level of customization and is much more than just a simple WYSIWYG editor. The idea of using it instead of a simple markdown editor is to provide the freedom to manage content as preferred within the website.

The field that we will analyze is the "body" field. The extensions that have been introduced mainly refer to the customization possibilities provided by DEV through some Liquid Tags. Let's take a look at them:

- Katex Inline: allows us to insert a mathematical notation inline.
- Katex Block: allows us to insert a mathematical notation into a separate block.
- Details: allows us to define content as an accordion. The content of the accordion is also a portable text with fewer options.
- Embed: allows us to embed an external resource. It is possible to choose whether to show a preview using an iframe.
- Code: allows us to insert a code snippet using [Sanity's official plugin](https://www.sanity.io/plugins/code-input).
- Image: a custom object for inserting an image with the ability to define an alt text and a title for the image.

The Portable Text tool palette looks like this:


![Portable Text - Tools](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/593jfj3qzil6wzqa58zm.jpg)
![Portable Text - Tools](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/6xjtubsdj340l1ctt3ao.jpg)

Each customization has its own preview within the editor. Here are a couple of examples:

![Portable Text - Blocks](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/5uweiiypgt55gxswrc9r.jpg)

---

## Custom workflows with document actions

Okay, so far we've seen how the content model is structured and some internal customizations. But how do we communicate and save information on DEV? That's where [document actions](https://www.sanity.io/docs/document-actions) come in handy 😃.

As indicated in the official documentation, document actions allow you to perform some operations on the document.

So, we will add a series of actions on top of the default ones, and in the same way, we will remove one, the duplicate action, because we do not want to allow the user to duplicate this kind of document in the Studio.

To add our actions, we need to modify the configuration of our plugin by inserting our code inside the **`document.actions`** object.

```ts
export const DevArticle = definePlugin<DevArticleConfig | void>((config = {}) => {
  return {
    name: 'sanity-plugin-devtoarticle',
    // ... rest of the configuration ...
    document: {
      actions: (prev, context) => {
        // customization valid only for devto.article document.
        if (context.schemaType === 'devto.article') {
          // removing the duplicate action
          prev = prev.filter((item) => item.action !== 'duplicate');
          [
            TitleAction,
            CreateDraftAction,
            CreatePublishedAction,
            UpdateAction,
            PublishAction,
            UnpublishAction,
            UnlinkAction,
            DividerAction,
          ].forEach((action, index) =>
            prev.splice(index + 1, 0, (actionProps) => action(actionProps, config))
          )					
        }
        return prev;
      }
    }
  }
})
```

The actions will only be visible if certain conditions are met. The main condition for all, however, is that **the document must be in the 'published' state on the Studio.**

The 'TitleAction' and 'DividerAction' actions are just placeholders that allow you to visually separate custom actions from default ones.

Below are the possible combinations that can be obtained:
<br>
#### <u>Article not present on DEV:</u>

The visible actions are *CreateDraftAction* and *CreatePublishedAction*, which respectively allow you to create a draft document or create and directly publish the document on DEV.


![article not present](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/lpctms4hg67tz1b0vp92.jpg)
<br>
#### <u>Article present on DEV in DRAFT/UNPUBLISHED state:</u>

Possible actions are UpdateAction, PublishAction, and UnlinkAction. The first two are self-explanatory, while the unlink action allows you to remove the association with the article on DEV. Both documents on the two platforms will not be deleted but can no longer be linked to each other (at least in this version of the plugin 😬).


![article in draft](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/twnbuqz864ec45ft4yau.jpg)
<br>
#### <u>Article present on DEV in PUBLISHED state:</u>

Possible actions are UpdateAction, UnpublishAction, and UnlinkAction. We have already seen two actions previously, while the Unpublish action allows you to return the document on DEV to draft state.


![article published](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/jgummi2hsuu2uhafr2wx.jpg)

---

## Body serialization

Everything is awesome so far, at least for me 😄. But what about the body of the article? How do we transform the content into something that DEV can save and, above all, render correctly on the platform?

To achieve this, we will use the **[@sanity/block-content-to-markdown](https://github.com/sanity-io/block-content-to-markdown)** plugin to convert portable text into markdown.

> ***The plugin block-content-to-markdown is in beta and hasn't received updates for many years, but so far, I haven't encountered any particular issues.***
> 

What we need to do is provide a series of serializers to transform those custom sections that otherwise would not be interpreted correctly.

```ts
const toMarkdown = require('@sanity/block-content-to-markdown')

toMarkdown($portableTextContent, {
  serializers: {
    marks: {
      'devto.katexinline': katexInlineSerialiizer,
    },
    types: {
      'devto.image': (props: any) => imageSerializer(props, projectId, dataset),
      'devto.details': (props: any) => detailsSerializer(props, projectId, dataset),
      'devto.embed': embedSerialiizer,
      'devto.katexblock': katexBlockSerialiizer,
      code: codeSerializer,
    },
  },
})
```

Most serializers return a string with the corresponding liquid tag inside:

```ts
export const katexInlineSerialiizer = (props: any): string => {
  return `{% katex inline %}${props.children}{% endkatex %}`
}

export const katexBlockSerialiizer = (props: any): string => {
  return `{% katex %}\n${props.node.notation}\n{% endkatex %}`
}

export const embedSerialiizer = (props: any): string => {
  return `{% embed ${props.node.url} %}`
}
```

---

## Demo?

Alright folks, we've seen enough theory and blah blah blah! How about a little demonstration? Time to get our hands dirty 🤓😎

{% embed https://youtu.be/y3fsp-Mi3-k %}

---

## Next steps and final thoughts

That's all for now, folks. I hope you enjoyed the content. You can find the Github repository at the following [link](https://github.com/williamiommi/sanity-plugin-devtoarticle).

The idea for the future is to add the ability to link to articles already present on DEV in addition to creating new ones. And maybe even create a widget to use in the [Sanity Dashboard](https://www.sanity.io/docs/dashboard) to get a recap of your articles.

Thank you for sticking around until the end!

See ya 🤙


Hello and welcome back. Over the last few months, I have been exploring a new CMS, or to be more...

From Sanity to Dev: Level up your blogging experience

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 YouTube 🏄 in Contentful

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