Forem: William Iommi

Share your content with Contentful and Telegram

William Iommi — Mon, 03 Jun 2024 11:17:42 +0000

Hello and welcome!

What I'm about to present is the final part of my journey with Telegram and Contentful.
Following my article published on the Contentful Blog (you can read more here), in this post, I’ll show you how I built a custom app to send messages to your Telegram Channel right from your Contentful entry.

This won't be a technical section, more of a “show and tell”. However, if you are interested in seeing the code, at the end of the article you will find links to the repositories.

Key Points of the Application

Let's define what, how, and where our application will operate.

As many of you may already know, the App Framework allows us to customize various parts of the Contentful web interface. In our case, we will modify the configuration screen of the app itself to define some parameters necessary for its overall operation. While the actual app will reside within the sidebar of our entries.

Our application will provide the user with the ability to send content to an external endpoint, leveraging the data from the current entry or completely custom data. The endpoint will then be responsible for retrieving the data and sending it to the associated Telegram channel (this part has been covered on the other article).

Configuration Screen

Let's start with the initial configuration. As mentioned earlier, without this, our app cannot function. Why is that? Simply because here, we give the user the ability to define multiple endpoints that our app can then use to send information.

Each endpoint can define different logics; for example, we can have an endpoint that relies on a Test channel that we can use to send test messages. Another example could be having different channels for different topics, providing us with the flexibility to communicate different information.

Let's see how the initial screen looks:

From here, we can add, modify, or delete our endpoints. The entry form includes the following fields:

Name: name of the endpoint.
Url: URL of our external service.
Channel Id: Telegram channel ID.
Channel name: name of the Telegram channel.

Doing so, we obtain a list of endpoints that our app will then utilize:

Sidebar App

As mentioned earlier, we will be working in a specific location, the sidebar.

This allows our application to be available on every entry of a specific content type (or more than one if desired).

Once the app is installed, to display it in the sidebar, we will need to modify the 'Sidebar' section of our content type:

..and move our 'Telegram Sender' app to the right-hand list, choosing the position, and then saving the content type:

Now, if we go to any Entry of type Recipe, we will see our application ready to be used:

How does it work?

Now that we have configured our app, let's see how it works.

After clicking 'Configure message,' the first crucial step is selecting the endpoint for sending our data:

Once the channel is selected, we will have a form with the following fields:

Media
Text message and parse mode
Link URL and Link name

Let's examine them in detail.

Media

This field allows us to select media in different ways.

We can create a new media from scratch or choose one from those already present. These first two options are fixed and interact through the Contentful SDK, displaying the default interface. For example, if we select 'Select existing media,' the application will open a modal with our saved assets:

The other entries starting with 'Entry field: ...' are dynamic entries based on the structure of our Content Type. In our example, our recipe, has only one Media-type field named 'Image.' Clicking on this option allows us to directly select the image associated with that field. If the field in the entry is not populated, the option in the select would still be present but disabled:

Text Message and Parse Mode:

This is where you can configure the text message to send to the channel. Similar to the media field, we have some dynamic fields based on the structure of our Content Type. Within the options, we have fields of type Symbol/Text. In addition to these, we have a 'Custom value' option that allows us to enter free text:

The 'Parse Mode' option is specific to Telegram, indicating the format of the text we are entering. The options are: HTML (Default), Markdown, and MarkdownV2.

There are links provided that redirect to the Telegram documentation for more information on these options.

Link URL and Name

These two optional fields allow you to define a link and a label to include in our message. Again, similar to the text message, we have the option to use fields from the entry or enter custom values:

Preview and Send CTA

The application also provides a preview of the message we are about to send. This feature can be useful for users who want to see how the message will appear within the Telegram channel before sending:

When the message is ready, we can click on the 'Send Message' CTA, which will send the data to our external endpoint responsible for delivering the message to our Telegram channel. The implementation of the external service will be very similar to what we saw in the previous article.

Conclusion

And with this, our journey through Bots, Webhooks, and custom apps comes to an end.

We've seen how, with simple configurations, we can establish our presence on Telegram and leverage the power of webhooks with just a few lines of code.

Last but not least, thanks to the power of the App Framework, we've been able to explore the creation of a small app that puts into practice everything we've learned in the previous article, all within the Contentful interface.

Below, you can find the links to the repositories used in this series:

Enhance your Customers' Experience with Sanity's Structure Builder API.

William Iommi — Thu, 01 Feb 2024 08:09:41 +0000

This article assumes a basic familiarity with Sanity Studio and document creation process. Prior knowledge of basic Sanity concepts is recommended for optimal comprehension.

One of the things that makes Sanity so flexible is the ability to have extensive freedom in organizing your content model according to your specific needs.

Through the Structure Tool (formerly known as Desk Tool), you have the possibility to define nested levels within the same document, allowing you to organize the view of your entries as you prefer.

The first example that comes to my mind (and which we will explore in this article) is the management of links, specifically dealing with various types of links.

Introducing the content model

Let's begin by defining our content model.
Imagine we need to manage an e-commerce website.
In our content model, we will have the following document types:

Product
Category/Collection
Editorial Page

All these documents, in addition to their specific attributes, share one attribute that we'll call 'slug,' containing the relative path. This attribute is used to identify the page on our website.

(We're limiting ourselves to these three types, but nothing prevents us from having others based on a slug. For example, a recipe or a blog post...)

We could have, within our slugs, paths like these:

c/men-shoes → Category
p/12345 → Product
/company/our-story → Editorial Page

How do we access these pages? Well, either we have knowledge of the entire product catalog (and its codes) and the entire site map (kudos to those who have this skill 😁), or in most cases, it's the website itself that provides us with a way to access various pages. This can be through a navigation menu or through an editorial banner promoting a specific product.

In all these cases, we are using links that contain the information to redirect to the desired page.

Returning to our content model, let's define a document, which we'll call 'Link,' to manage these redirects.

Defining the Link document

Now, let's identify the fields necessary for our case.

Label - The label of our link
Type - Defines the type of link. Possible values are: 'external', 'product', 'category', 'page'
External Url - Contains the link to an external resource
Product - Contains a reference to a 'Product' document
Category - Contains a reference to a 'Category' document
Page - Contains a reference to an 'Editorial Page' document

Without specific customizations, the default view of our document is the following:

What we want to achieve is a nested view that can differentiate between the possible link types. This solution will allow the content editor to access a particular type of link more easily.

Graphically, we want to achieve something like this:

Customizing the Structure Tool

To customize our view, we need to extend the Structure Tool using the Structure Builder API. We will override the 'structure' attribute, as we can see below:

// sanity.config.ts
import {structureTool} from 'sanity/structure'
import CustomStructure from '...customStructurePath...'

export default defineConfig({
  // ...
  plugins: [
    structureTool({
      structure: CustomStructure,
    }),
  ],
  // ...
})

We are only interested in customizing the view of our Link document; all the other documents present will behave by default. Before seeing our customization, let's ensure that all the other documents are not modified.

// custom-structure.ts
import {StructureBuilder, StructureResolverContext} from 'sanity/structure'
import CustomLinkItem from '...customLinkItemPath...'

export default function CustomStructure(S: StructureBuilder){
  return S.list()
    .title('Content')
    .items([
      ...S.documentTypeListItems().map((item) => {
        if (item.getId() === 'link') return CustomLinkItem
        return item
      }),
    ])
}

By leveraging the documentTypeListItems method, we obtain all the documents registered in our schema. Through the map method, we return all the default items, and if the document's ID is link, we return our custom view. Now, let's take a look at what CustomLinkItem contains.

Custom Link Item

As mentioned earlier, what we want to achieve is that when clicking on our document, before seeing the various entries, we want to have an intermediate view that groups the entries by type (external, product, category, page).

For the sake of the article, we will only look at a couple of these; at the end of the article, you can find the link to the repository with the full example.

Okay, in the previous snippet, we are returning the CustomLinkItem object. Let's start by looking at the basic definition, which is the first level:

// custom-link-item.ts
import {AiOutlineLink} from 'react-icons/ai'
import {StructureBuilder} from 'sanity/structure'

export default function CustomLinkItem(S: StructureBuilder) {
  return S.listItem().icon(AiOutlineLink).title('Links')
}

So, we are returning a listItem with an icon and a title. This is what we get:

On the right side, there is nothing, and the browser console complains that there is no child. Let's define this child. In our case, it will contain a list of items that will identify our filters.

All Links Item

The first item we define is the one that groups all the types. We want to give the user the option to view all the links regardless of type.

// custom-link-item.ts

import {AiOutlineLink} from 'react-icons/ai'
import {StructureBuilder} from 'sanity/structure'

const AllLinksItem = (S: StructureBuilder) => {
  return S.listItem()
    .icon(AiOutlineLink)
    .title('All Links')
    .child(
      S.documentTypeList('link').title('All Links'),
    );
};

// rest of the file

We define again a listItem with an icon and a title.
As a child, we use the documentTypeList method, passing the name of our document as a parameter. This method allows rendering the default view and displaying the entries of our document.

Product Links Item

The next item we create is the first real filter, and it concerns all the links of type 'product.' The definition will be similar to what we saw earlier, but we will add a filter function to achieve the desired result.

// custom-link-item.ts

import {BsCart} from 'react-icons/bs'
import {StructureBuilder} from 'sanity/structure'

const AllProductLinksItem = (S: StructureBuilder) => {
  return S.listItem()
    .icon(BsCart)
    .title('Product Links')
    .child(
      S.documentTypeList('link')
       .title('All Product Links')
       .filter(`linkType == $linkType`)
       .params({ linkType: 'product' }),
    );
};

// rest of the file

By forcing the linkType filter to 'product,' we get that the list of displayed entries will contain only the links that interest us.

The other filters

Continuing with this logic, we will define the other filters by changing only the title, icon, and the value of the linkType parameter.

What we will achieve is a filtered view, just as we imagined with the initial sketch.

On the code side, we added all the filters within the initial child of our CustomLinkItem.

// custom-link-item.ts

export default function CustomLinkItem(S: StructureBuilder) {
  return S.listItem()
    .icon(AiOutlineLink)
    .title('Links')
    .child(
      S.list()
       .title('Filtered Links')
       .items([
         AllLinksItem(S),
         S.divider(),
         AllExternalLinksItem(S),
         AllProductLinksItem(S),
         AllCategoryLinksItem(S),
         AllPageLinksItem(S),
       ])
    )
}

Bonus: Templates

From an organizational perspective, having this freedom to structure content based on your needs is a game-changer. But we can do even better...

Currently, we have separated our links based on type. However, if, for example, within the 'Product Links' filter, we add a new link, the Type field does not auto-populate with the product type. Thus, we are forced to select it manually.

By using the Initial Value Templates API, we can define an initial value for our document so that the user does not have to manually select the value.

Let's define the initial template for our product filter (the others will be similar):

// link template for product
{
  id: 'tpl-productLink',
  title: 'Product Link',
  schemaType: 'link',
  value: {
    linkType: 'product'
  }
}

The templates need to be declared first within our schema, inside the sanity.config.ts file, to be utilized and prevent Studio crashes.

// sanity.config.ts

export default defineConfig({
  // ...
  schema: {
    types: [/* your documents/objects */]
    templates: [{
      id: 'tpl-productLink',
      title: 'Product Link',
      schemaType: 'link',
      value: {
        linkType: 'product'
      }
    },
    // other templates
    ]
  }
  // ...
})

Once declared, we can use them within our filter. Let's take our Product filter as an example and update its declaration:

// custom-link-item.ts

import {BsCart} from 'react-icons/bs'
import {StructureBuilder} from 'sanity/structure'

const AllProductLinksItem = (S: StructureBuilder) => {
  return S.listItem()
    .icon(BsCart)
    .title('Product Links')
    .child(
      S.documentTypeList('link')
       .title('All Product Links')
       .filter(`linkType == $linkType`)
       .params({ linkType: 'product' })
       .initialValueTemplates([ 
         S.initialValueTemplateItem(`tpl-productLink`)
       ]),
    );
};

// rest of the file

Now, when we are within the 'Product Links' filter and click on the + icon, the draft of the created document will already have the desired value selected in the Type field.

Expanding the logic to the 'All Links' item as well, we have the opportunity to guide the link creation by providing the desired options:

// custom-link-item.ts

import {AiOutlineLink} from 'react-icons/ai'
import {StructureBuilder} from 'sanity/structure'

const AllLinksItem = (S: StructureBuilder) => {
  return S.listItem()
    .icon(AiOutlineLink)
    .title('All Links')
    .child(
      S.documentTypeList('link')
       .title('All Links')
       .initialValueTemplates([
         S.initialValueTemplateItem('tpl-externalLink'),
         S.initialValueTemplateItem('tpl-productLink'),
         S.initialValueTemplateItem('tpl-categoryLink'),
         S.initialValueTemplateItem('tpl-pageLink'),
       ]),
    );
};

Conclusion

Today, we've explored the power of the Structure Builder API in customizing our content model. The ability to filter results according to our preferences through GROQ filters opens up virtually infinite solutions.

You can find the complete code in the following repository.

Thanks for reading!

See ya 🤙

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

William Iommi — Fri, 11 Aug 2023 12:33:13 +0000

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

The feature in question is called 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.

// 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.

// 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

🚨 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:

// 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:

🚨 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:

Before

After

👋 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 🤙

From Sanity to Dev: Level up your blogging experience

William Iommi — Tue, 06 Jun 2023 11:03:33 +0000

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.

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!👨‍🔬 🚀

The why behind this plugin
DEV endpoints
Init Sanity plugin with plugin-kit
Document structure
Custom components
Custom workflows with document actions
Body serialization
Demo
Next steps and final thoughts

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.

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, 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 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} (a PUT call to update an article with a specific ID)
https://dev.to/api/articles/me/all (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:

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 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.

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:

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

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:

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:

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:

DevField

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, 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.

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.

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

Portable Text Blocks

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.
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:

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

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 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.

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:

Article not present on DEV:

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 present on DEV in DRAFT/UNPUBLISHED state:

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 present on DEV in PUBLISHED state:

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.

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 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.

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:

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 🤓😎

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.

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 to get a recap of your articles.

Thank you for sticking around until the end!

See ya 🤙

How to YouTube 🏄 in Contentful

William Iommi — Mon, 13 Jun 2022 18:20:21 +0000

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 or take a look at my previous series 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 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. 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: 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: 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.

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)

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: Field

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

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 🤙

Can 'Tailwind CSS' improve your review process?

William Iommi — Thu, 20 Jan 2022 11:19:37 +0000

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?

👇👇👇

How do you review CSS?

William Iommi — Thu, 13 Jan 2022 16:32:12 +0000

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? 😬

👇👇👇

Welcome to my website

William Iommi — Tue, 04 Jan 2022 21:36:05 +0000

I did it!!! My website is live and I'm happy to share it with you all!
I hosted it on Vercel and you can reach it at the following URL:

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 (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, 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, Lodash for some utility methods and react-masonry-css for the gallery grid.

Special mentions

The writing page uses the 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 Spotify's Snippet 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 🤙

Animate a Hamburger Menu with Framer Motion

William Iommi — Fri, 05 Nov 2021 19:13:22 +0000

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, a React animation library by Framer.

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, representing my animation states. Every shape is inside a 24 x 24 box.

The first shape represent the 'closed' state:

The second, represent the middle state:

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

The following are the 3 SVG exported from Figma.



<!-- CLOSED STATE -->
<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>



<!-- MIDDLE STATE -->
<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>



<!-- OPEN STATE -->
<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:



d="Mx1 y1Lx2 y2"

So the first 2 SVG have become:



<!-- CLOSED STATE -->
<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>



<!-- MIDDLE STATE -->
<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, 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.



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.



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...



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

and my return statement is:



<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 hook creates an 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.



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:



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...



<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 😇

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 🤙

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

William Iommi — Fri, 08 Oct 2021 18:28:46 +0000

The road so far...

It's time folks! The end of our journey through a Contentful App is here.
We have gathered a lot of information in the first three parts. We have seen the theory behind it, we understood the why for all of this and we saw an integration between Contentful and a third-party platform like Commerce.js.

Now it's time to connects all the pieces and finally see our main customization, which is the reason why I'm here writing stuff on a monitor 😂.

In this final episode, we are going to see our customized entry field. Our focus will be the research and selection of a product from Commerce.js.

And with a little bit of sadness in my eyes, let's start our last take 🙁 🥺 😢.

The Concept

So what do we want to build? For our field, we want to choose which type of URL to save: Product, Category or Content Page.
Based on this choice, we open a modal showing all the related entries, in our use case, all the products from Commerce.js.
After the user selects a product, we save our field with some info. Since this field is of type JSON, we can structure it as we want and the user will see a card preview of the selected product and not the JSON Object itself.

Initial Setup

Inside our project, I created a lib folder where I'm going to save few files with constants and utility methods.

Constants

Our App has multiple purposes even if our focus is on the URL + product behavior.
I have defined few constants to separate these logics.

export const APPEARANCE_TYPES = {
  URL: "url", // used in this demo
  PRODUCT: "product",
  PRODUCTS: "products",
  CATEGORY: "category",
  CATEGORIES: "categories",
};

export const TYPES = {
  PRODUCT: "product", // used in this demo
  CATEGORY: "category",
  PAGE: "page",
};

Utilities

After that, we create some utility methods that will be used in the upcoming sections.
First, we need a function that retrieves a specific product from Commerce.js:

import Commerce from "@chec/commerce.js";
import { Product } from "@chec/commerce.js/types/product";

export const getProduct = async (
  apiKey: string,
  productId: string,
  successCB?: (product: Product) => void,
  failCB?: (e: any) => void
): Promise<Product | any> => {
  try {
    const commerce = new Commerce(apiKey);
    const product = await commerce.products.retrieve(productId);
    if (!successCB) return product;
    successCB(product);
  } catch (e) {
    console.error(e);
    if (!failCB) return e;
    failCB(e);
  }
};

and then we need the function that retrieves all the products:

import Commerce from "@chec/commerce.js";
import { ProductCollection } from "@chec/commerce.js/features/products";

export const getProducts = async (
  apiKey: string,
  successCB?: (products: ProductCollection) => void,
  failCB?: (e: any) => void
): Promise<ProductCollection | any> => {
  try {
    const commerce = new Commerce(apiKey);
    const products = await commerce.products.list();
    if (!successCB) return products;
    successCB(products);
  } catch (e) {
    console.error(e);
    if (!failCB) return e;
    failCB(e);
  }
};

Both methods expect an API key as input and if you have read part 3 of this series, you know where it will come from 😉.

Custom components

We are not limited to using the files provided by Contentful, we can also create our own.

Product Card

The Product Card Component will be used both in the modal when we are looking for products to select, and also after the selection to show a nice UI instead of the JSON object saved on Contentful.

import { css } from "emotion";
import { Product } from "@chec/commerce.js/types/product";
import {
  Card,
  IconButton,
  Flex,
  Tag,
  Heading,
  HelpText,
} from "@contentful/forma-36-react-components";

interface IProductCard {
  product?: Product;
  showTag?: boolean;
  onClickCard?: (product: Product) => void;
  onClickIcon?: () => void;
}

export const ProductCard = (props: IProductCard) => {
  const { product, showTag, onClickCard, onClickIcon } = props;

  if (!product) return null;

  return (
    <Card
      className={css({
        height: "100%",
        boxSizing: "border-box",
        position: "relative",
      })}
      {...(onClickCard && { onClick: () => onClickCard(product) })}
    >
      {onClickIcon && (
        <IconButton
          iconProps={{ icon: "Close" }}
          buttonType="muted"
          className={css({
            position: "absolute",
            top: "3px",
            right: "3px",
          })}
          onClick={onClickIcon}
        />
      )}
      <Flex alignItems="center">
        {product.media && (
          <div className={css({ marginRight: "20px", width: "100px" })}>
            <img
              className={css({ maxWidth: "100%" })}
              src={product.media.source}
              alt={product.name}
            />
          </div>
        )}
        <Flex flexDirection="column">
          {showTag && <Tag>product</Tag>}
          <Heading>{product.name}</Heading>
          <HelpText
            className={css({
              fontStyle: "italic",
              fontSize: "12px",
              marginBottom: "10px",
            })}
          >
            SKU: {product.sku}
          </HelpText>
        </Flex>
      </Flex>
    </Card>
  );
};

We are importing some UI components from Forma36 and a Product type definition from Commerce.js.
Our custom IProductCard interface defines the properties available for the component:

product: this is the prop containing the whole product data coming from Commerce.js.
showTag: this flag shows a tag that identifies this card as a product (this will be more clear later).
onClickCard: this optional callback is used inside the products modal when the user selects a product. The function passes the product prop as a parameter.
onClickIcon: this callback, when defined, shows an 'x' icon on the top right corner and is used when we want to clear our selection.

This card will have two possible layouts which we can see below:

The first one will be used inside the modal, the second in place of the JSON object when the product is already selected.

Product Wrapper

This component will be used inside the Dialog/Modal Location. It will contain all the products coming from Commerce.js.
Here the customer can click on a single card and select the product.

import { css } from "emotion";
import { Grid, GridItem } from "@contentful/forma-36-react-components";
import { useEffect, useState } from "react";
import { getProducts } from "../lib/commerce";
import { ProductCollection } from "@chec/commerce.js/features/products";
import { Product } from "@chec/commerce.js/types/product";
import { ProductCard } from "./ProductCard";
import { TYPES } from "../lib/Constants";

interface IProductWrapper {
  publicKey: string;
  onSelectProduct: (data: { id: string; type: string; url: string }) => void;
}

export const ProductWrapper = (props: IProductWrapper) => {
  const { publicKey, onSelectProduct } = props;
  const [productCollection, setProductCollection] =
    useState<ProductCollection>();
  useEffect(() => {
    getProducts(publicKey, setProductCollection);
  }, [publicKey]);
  const onClickCard = (product: Product) => {
    onSelectProduct({
      id: product.id,
      type: TYPES.PRODUCT,
      url: `/p/${product.permalink}`,
    });
  };
  if (!productCollection) return <p>Loading...</p>;
  return (
    <Grid columns={3} rowGap="spacingS" className={css({ margin: "20px 0" })}>
      {productCollection.data.map((product) => (
        <GridItem key={product.id}>
          <ProductCard product={product} onClickCard={onClickCard} />
        </GridItem>
      ))}
    </Grid>
  );
};

As usual, we are using UI components from Forma36, in this case, Grid and GridItem. We are using also the previous Product Card component in order to show all our dummy products.
If we look at the available props, we have:

publicKey: this is the key used to call Commerce.js.
onSelectProduct: this is the callback that will be called when the user clicks the card. It accepts an object as parameter. This object contains the data structure that will be saved on Contentful.

The component, thanks to the public key, calls Commerce.js with our utility method and saves products inside productCollection inner state. While is waiting for a response from Commerce.js, the component shows a simple Loading... paragraph to inform the reader.
We can see the UI below:

This is a simple demo with a simple UI and few products. Of course, if we want to do some improvements we could add an input field to search products and maybe also pagination if your Product Catalog is huge.
The only limit is your imagination (and your Business requirements/plan 😂)

Url Appearance Field

This is definitely the most complex component of the entire app.
This UI is rendered only when our instance parameter is set to 'URL'.
I'm going to analyze the file in the detail.

Url Appearance Field: imports

import { useState, useEffect } from "react";
import { css } from "emotion";
import { Product } from "@chec/commerce.js/types/product";
import { Flex, Button } from "@contentful/forma-36-react-components";
import { APPEARANCE_TYPES, TYPES } from "../lib/Constants";
import { getProduct } from "../lib/commerce";
import { ProductCard } from "./ProductCard";
import { FieldExtensionSDK } from "@contentful/field-editor-shared";

This is pretty clear, we are importing UI components, utilities, typescript types...🥱😪

Url Appearance Field: props interface

interface IUrlAppearanceField {
  sdk: FieldExtensionSDK;
}

The interface is simple, we are expecting, as a prop, the SDK related to the field provided by Contentful.

Url Appearance Field: react hooks

Here we are extracting the Commerce.js public key from our parameters.installation and we are defining some react hooks.

const { sdk } = props;
const { publicKey }: any = sdk.parameters.installation;
const [innerValue, setInnerValue] = useState(sdk.field.getValue());
const [product, setProduct] = useState<Product>();

useEffect(() => {
  if (innerValue?.type === TYPES.PRODUCT) {
    getProduct(publicKey, innerValue.id, setProduct);
  }
}, [publicKey, innerValue]);

We have two useState hooks: the first is an inner state containing the value saved on Contentful, extracted with the getValue function provided by the SDK. The second contains the Commerce.js product.
The useEffect hook is called every time the innerValue changes and also on first load. The hook checks if the saved value is of type 'product' and if so, we call Commerce.js retrieving the full product, passing the innerValue.id which contains the id of a specific product.

Url Appearance Field: the UI

Let's jump to the return statement:

return (
    <>
      {product && (
        <>
          <ProductCard showTag product={product} onClickIcon={clearValue} />
          <div
            className={css({
              margin: "20px 0",
              borderTop: "1px solid #cfd9e0",
            })}
          />
        </>
      )}
      <Flex className={css({ marginTop: `${innerValue ? "0" : "10px"}` })}>
        <Button
          icon="ShoppingCart"
          buttonType="muted"
          className={css({ marginLeft: "10px", height: "2rem" })}
          onClick={() => openDialog(TYPES.PRODUCT)}
        >
          Choose a Product
        </Button>
      </Flex>
    </>
  );

We are showing a Product Card and a separator when the user selects or has already selected a product.
The component has the showTag attribute set to true and the onClickIcon callback defined with a 'clearValue' function.
Finally, we have a Forma36 Button with a cart icon and a callback on the onClick event that opens a Dialog of type 'product'.
We can see the UI in the following screenshots:

As mentioned a million times 😅 we are focusing only on the product selection, the complete UI would instead be like this:

The light blue product badge lets the user understand immediately which type of URL has been saved on the field.

Url Appearance Field: clearValue callback

The clearValue function lets the user clear his selection by clicking on the 'x' icon on the card.

const clearValue = () => {
  setProduct(undefined);
  setInnerValue(undefined);
  sdk.field.setValue(undefined);
};

We are cleaning our react states and we are using the setValue function provided by the SDK in order to reset the value also for Contentful.

Url Appearance Field: openDialog callback

The openDialog function is the core of the component.
It lets you open the Contentful Modal with the dialogs.openCurrentApp method passing few parameters. Basically, this function moves the focus of your app into the Dialog Location.
Since is a Promise, it waits until you close the modal and after that, you have access to a response object.
If you remember, in the Product Wrapper component we defined an object composed of an id, type and URL. This is the object received from the Promise when we select a product (if we click on the x of the modal we receive an undefined object).
Let's see the implementation:

const openDialog = async (type: string) => {
    const res = await sdk.dialogs.openCurrentApp({
      position: "top",
      minHeight: "75vh",
      width: "fullWidth",
      shouldCloseOnOverlayClick: true,
      allowHeightOverflow: true,
      title: `Search ${type === TYPES.CATEGORY ? " Categories" : "Products"}`,
      parameters: { appearance: APPEARANCE_TYPES.URL, type },
    });
    if (res) {
      setInnerValue(res);
      sdk.field.setValue(res);
    }
  };

As you can see, if the res object is defined, it means that we have selected a product and we are saving this object into our react state but also into Contentful through the SDK.
Here you can see the entire code related to the product

import { useState, useEffect } from "react";
import { css } from "emotion";
import { Product } from "@chec/commerce.js/types/product";
import { Flex, Button } from "@contentful/forma-36-react-components";
import { APPEARANCE_TYPES, TYPES } from "../lib/Constants";
import { getProduct } from "../lib/commerce";
import { ProductCard } from "./ProductCard";
import { FieldExtensionSDK } from "@contentful/field-editor-shared";

interface IFieldUrl {
  sdk: FieldExtensionSDK;
}

export const UrlAppearanceField = (props: IFieldUrl) => {
  const { sdk } = props;
  const { publicKey }: any = sdk.parameters.installation;
  const [innerValue, setInnerValue] = useState(sdk.field.getValue());
  const [product, setProduct] = useState<Product>();

  useEffect(() => {
    if (innerValue?.type === TYPES.PRODUCT) {
      getProduct(publicKey, innerValue.id, setProduct);
    }
  }, [publicKey, innerValue]);

  const openDialog = async (type: string) => {
    const res = await sdk.dialogs.openCurrentApp({
      position: "top",
      minHeight: "75vh",
      width: "fullWidth",
      shouldCloseOnOverlayClick: true,
      allowHeightOverflow: true,
      title: `Search ${type === TYPES.CATEGORY ? " Categories" : "Products"}`,
      parameters: { appearance: APPEARANCE_TYPES.URL, type },
    });
    if (res) {
      setInnerValue(res);
      sdk.field.setValue(res);
    }
  };

  const clearValue = () => {
    setProduct(undefined);
    setInnerValue(undefined);
    sdk.field.setValue(undefined);
  };

  return (
    <>
      {product && (
        <>
          <ProductCard showTag product={product} onClickIcon={clearValue} />
          <div
            className={css({
              margin: "20px 0",
              borderTop: "1px solid #cfd9e0",
            })}
          />
        </>
      )}
      <Flex className={css({ marginTop: `${innerValue ? "0" : "10px"}` })}>
        <Button
          icon="ShoppingCart"
          buttonType="muted"
          className={css({ marginLeft: "10px", height: "2rem" })}
          onClick={() => openDialog(TYPES.PRODUCT)}
        >
          Choose a Product
        </Button>
      </Flex>
    </>
  );
};

Connecting dots

Now is the time to connect all the pieces of the puzzle.
In the previous section, we saw all our custom implementation and now we need to use the locations provided by Contentful and finish our implementation.

Our focus is on the Dialog.tsx and Field.tsx files. Let's start with the Modal.

Dialog Location

This file is used when we call the dialogs.openCurrentApp function that we saw previously.

import { ModalContent } from "@contentful/forma-36-react-components";
import { DialogExtensionSDK } from "@contentful/app-sdk";
import { TYPES } from "../lib/Constants";
import { ProductWrapper } from "./ProductWrapper";

interface DialogProps {
  sdk: DialogExtensionSDK;
}

const Dialog = (props: DialogProps) => {
  const { type }: any = props.sdk.parameters.invocation;
  const { publicKey }: any = props.sdk.parameters.installation;
  return (
    <>
      <ModalContent>
        {type === TYPES.PRODUCT && (
          <ProductWrapper
            publicKey={publicKey}
            onSelectProduct={props.sdk.close}
          />
        )}
        {/* {type === TYPES.CATEGORY && (
          <CategoryWrapper
            publicKey={publicKey}
            onSelectCategory={props.sdk.close}
          />
        )} */}
      </ModalContent>
    </>
  );
};

export default Dialog;

We have a specific Typescript type definition for the SDK which is now DialogExtensionSDK. With this SDK, inside the parameters.invocation we have access to the type attribute that we passed when we called the modal. This attribute lets us know what type of content to provide to the modal as you can see in the return statement.
To our Product Wrapper component, we are passing also the close SDK callback that we'll be used when we select a product passing back the object to save on Contentful.

Field Location

Based on our instance parameter 'type' we render a UI or another, in our demo will be always the URL Appearance Field

import { useEffect } from "react";
import { FieldExtensionSDK } from "@contentful/app-sdk";
import { APPEARANCE_TYPES } from "../lib/Constants";
import { UrlAppearanceField } from "./UrlAppearanceField";

interface FieldProps {
  sdk: FieldExtensionSDK;
}

const Field = (props: FieldProps) => {
  const instanceProps: any = props.sdk.parameters.instance;
  useEffect(() => {
    props.sdk.window.startAutoResizer();
    return () => props.sdk.window.stopAutoResizer();
  }, [props]);

  return (
    <>
      {instanceProps.type === APPEARANCE_TYPES.URL && (
        <UrlAppearanceField sdk={props.sdk} />
      )}
      {/*
        {instanceProps.type === APPEARANCE_TYPES.PRODUCT && (
          <ProductAppearanceField sdk={props.sdk} />
        )}
        {instanceProps.type === APPEARANCE_TYPES.PRODUCTS && (
          <ProductsAppearanceField sdk={props.sdk} />
        )}
        {instanceProps.type === APPEARANCE_TYPES.CATEGORY && (
          <CategoryAppearanceField sdk={props.sdk} />
        )}
        {instanceProps.type === APPEARANCE_TYPES.CATEGORIES && (
          <CategoriesAppearanceField sdk={props.sdk} />
        )}
      */}
    </>
  );
};

export default Field;

Here, the only thing that I want to clarify is the useEffect hook. We are using the window.startAutoResizer feature. This function updates the height of the iframe every time something happens (for example when we select or remove the product card). Doing this, we have always our wrapper height updated with no white spaces or scrollbars.

Little Demo

This is it, we finally completed our app 🥳 🥳 🥳.
Here you can see a little demo:

Here instead the snapshot of the entry where you can see what is saved on Contentful:

{
    "metadata": {
        "tags": []
    },
    "sys": {
        "space": {
            "sys": {
                "type": "Link",
                "linkType": "Space",
                "id": "xxx"
            }
        },
        "id": "35MgIumMobPVc9qnCH0Xa0",
        "type": "Entry",
        "createdAt": "2021-10-02T16:55:24.957Z",
        "updatedAt": "2021-10-03T10:11:46.157Z",
        "environment": {
            "sys": {
                "id": "website",
                "type": "Link",
                "linkType": "Environment"
            }
        },
        "revision": 5,
        "contentType": {
            "sys": {
                "type": "Link",
                "linkType": "ContentType",
                "id": "testCommerceSelector"
            }
        },
        "locale": "en-US"
    },
    "fields": {
        "url": {
            "id": "prod_RqEv5xXO2d5Zz4",
            "type": "product",
            "url": "/p/shoe05"
        }
    }
}

Deploying the app

Of course is not over yet 😉. We need to deploy our application, otherwise will be available only for us and with a local environment running.
Since our app is very small we don't need an external provider, we can deploy the app directly on Contentful, the process is pretty simple.
In our package.json file, we have scripts that build and upload the app for us.
The commands to run on the terminal are:

npm run build
npm run upload

Follow the instructions of the script and when finished we can see on Contentful our uploaded app.

As you can see now the frontend is not anymore our local environment but is hosted by Contentful 😎.

A step further...

It's not part of this series but I want to mention one further step that we can and should do for our app.
As we have seen, data about the product saved on Contentful, is minimal: product code and the permalink, nothing else. All other information for the product card is gathered in real-time by calling Commerce.js.
But what happens if a permalink changes or worse, the product on Commerce.js is deleted? Our website or mobile app that depends on Contentful data, can lead to a broken page.

Commerce.js provides a set of webhooks that we can configure. For example, there is a specific webhook when the product has been updated or another one if is deleted.
For each one, we need to provide a URL that Commerce.js can call every time something happens.

My demo website uses my Contentful data. It's built with Next.js and deployed on Vercel and I defined few API routes that listen to Commerce.js webhooks.
Every time a product changes, my API route receives the updated product from Commerce.js and thanks to the Contentful Content Management API I can update my content with the updated data or skip if nothing that I care about is changed.

Or for example, If I don't want to update my content automatically, when I receive the updated product I can send a notification and hopefully (😆) there will be someone that will update manually the broken link(s) on Contentful.

Conclusion...

Wow...what a journey 🤯...probably not the best way to start my 'blog career' with a 4 articles series but it was fun, so much fun 😁.
Hope you enjoyed it too and if you are still here reading thank you very much, I appreciate it 🙇🏻‍♂️.
Now you can leave or drop a comment or a like or a follow or whatever 😆...
And if with 'the road so far...' at the beginning of this page you get which TV series I'm referring to, carry on, drop another comment below and let me know.

See ya 🤙 💪

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

William Iommi — Wed, 29 Sep 2021 19:52:37 +0000

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 👆.

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.

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.

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: Creating sample products

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

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.

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)

When all fields are filled, leave the product as active and click save.
We have defined a new product on Commerce.js.

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.

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 😄... except for a title and a paragraph.

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.

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.

App Configuration: Overview

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

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 is implemented.
The other focus is on all the imports from @contentful/forma-36-react-components. Forma36 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 😄.

App Configuration: Commerce.js package

Before starting our customization one thing is missing. We need to download the Commerce.js SDK in order to check if the provided key is valid. Let's install it on our local environment with the following CLI command:

npm install @chec/commerce.js

and if you are using Typescript also this:

npm install --save-dev @types/chec__commerce.js

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:

import {
  Heading,
  Form,
  Workbench,
  Paragraph,
  TextField,
  Button,
  Flex,
} from "@contentful/forma-36-react-components";
import Commerce from "@chec/commerce.js";

App Configuration: AppInstallationParameters Interface

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

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.

App Configuration: The new (outstanding 😄) UI

Let's jump now to the return method of our component and implement our new interface.

<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 😄 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.

Awesome right?!? 😂 ... Let's implement now those callbacks.

App Configuration: onPublicKeyChange

The first is pretty straightforward:

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.

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:

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:

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:

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).

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:

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 📻
❤️

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

William Iommi — Tue, 21 Sep 2021 18:20:02 +0000

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

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.

Here, you need to define the space and the environment

(Your space and environment could be different)

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.

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 🥳 🥳.

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.

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.

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.

("Type" is the instance parameter defined in our App Definition step.)

We can see the result of our setup if we try to create an entry for our content type.

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

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.

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.

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 📻
❤️