Forem: Yusuf Musleh

How to handle Webflow Multi-Reference Fields in Form Submissions

Yusuf Musleh — Sat, 28 Nov 2020 04:59:46 +0000

Summary

Creating a Collection Item in a Webflow CMS when a user submits a form is a common use case for a Webflow site. There have been multiple ways to achieve this using the many low-code/no-code automation tools. However, historically there's been a common complaint amongst many makers; that things get tricky when the form contains multi-reference fields because of the way Webflow formats them in the form submission event data.

In this article I'll walk you through solving this problem using Autocode. You can see it in action right away by performing form submissions from a sample Webflow site and see collection items created in the CMS when forms are submitted.

First, you need to clone the Webflow site by clicking here, then pressing the Clone button on the top right to copy the sample blog form site to your own Webflow account. Then, you need to map the values of each category field in the form to the corresponding Category item ID and publish the site. (If you're not sure how to get the category IDs, check the How It Works section below).

Once you've cloned and published the Webflow site, click here to open the starter app in Autocode. You can checkout the source code if you'd like, then install the app to your Autocode account. You'll then be asked to link your Webflow site, simply follow the instructions to do so. Next, you'll need to set the COLLECTION_ID environment variable for the Blog Posts collection in the site you cloned. (If you're not sure how to get the collection id, check the How It Works section below).

After that, you're good to go! Once the app finishes installing and deploying, you can go to your Blog Site and submit a form selecting some Categories (multi-reference fields). A new blog post will appear in the CMS referencing the correct categories that were selected!

Introduction

Webflow is a great tool for building websites and e-commerce stores with little to no code required. Utilizing their powerful drag & drop UI builder bundled with their CMS, means you can go from an idea to a live website in a very short period of time. It has become a very common tool in the arsenal of many makers.

One of common use cases or flows many people build on Webflow is a form that stores submissions in the Webflow CMS. In other words, being able to create a Collection Item when a user submits a response to a form on the site. There have been multiple ways to achieve this using the many low-code/no-code automation tools. However, historically there's been a common complaint amongst many makers; that things get tricky when the form contains multi-reference fields.

Say you have a blogging website that allows users to create blog posts by submitting a form on your site. In that form you allow your users to tag their blog posts with different topic categories. These categories are fetched from a collection you created in your Webflow CMS. These categories are represented as a multi-reference field in your Blog Posts.

The Problem

Generally the automation of this process involves 2 steps:

Listening to when a form is submitted
Creating a new Collection Item using the data from the submitted form

While most tools do a great job handling the first step, listening to form submissions from Webflow. Passing in that data directly to the default Webflow Create Collection Item connector/module would usually fail when multiple items are selected in the multi-reference field. This is because of how Webflow represents multi-reference field data in the event object and what the connector/module expects.

Below is sample payload that Webflow sends when a form is submitted (in this case Categories is the multi-reference field):

{
  "d": "2020-08-26T16:29:54.226Z",
  "_id": "000000000000000000000000",
  "data": {
    {
      "Title": "[SOME_TITLE]",
      "Content": "[SOME_CONTENT]",
      "Categories": "000000000000000000000001,000000000000000000000002,000000000000000000000003"
}
  },
  "name": "FORM_NAME",
  "site": "000000000000000000000000"
}

Notice how the data in Categories is a comma-separated string instead of an array. If you try to pass this in directly to the connector/module that creates a collection item it would consider the whole string as a single ID and fail to identify a Category with that ID.

[400] ValidationError: Validation Failure Referenced item not found: categories

Because of this, many folks handle this by stitching together multiple connectors/module to modify the data, and manually make API calls to Webflow to solve this problem.

In this article, I'll show you how to easily handle this using Autocode. A Node.js API development platform and online code editor/IDE with built-in autocomplete, that handles Webflow's authentication, listening to form submission events and creation of collection items.

All you need to follow along is a Webflow account, with this sample blog site cloned, and a free Autocode account.

How It Works

Prerequisites

Before you start, you'd need to setup clone and setup the Webflow site:

Click on the Clone button on the top right corner of this page
Map each of the category fields in the form to their corresponding Category Item IDs

You can find the category IDs, by navigating to the CMS, then clicking on each of the Category Items in the Categories Collection

Publish the cloned site to be able to make form submissions

Let's Get Started

When you link your Webflow site to your app, Autocode takes care of the Authentication, creation and validation of webhooks to listen to form submission events, and making API calls to Webflow.

This app listens to all form_submission events coming from the linked Webflow site by default, you'll notice a wild card * is specified in the form_name field in the event handler. If you'd like to specify a certain form to listen to submission events from, you can add a new form_submission event handler and set the form_name to your specific form's name defined in the Webflow designer.

Diving into some code

The event handler is simply an exported JavaScript function that takes in a parameter called event that represents the event coming in from Webflow. This function runs every time a form is submitted on your site:

const lib = require('lib')({token: process.env.STDLIB_SECRET_TOKEN});

/**
* An HTTP endpoint that acts as a webhook for Webflow form_submission event
* @param {object} event
* @returns {object} result Your return value
*/
module.exports = async (event) => {
  // event handler logic
}

We include all the logic that we would like to run whenever we get a new event, i.e. when a form is submitted on our site. The general structure of the event parameter object is as we described earlier:

{
  "d": "2020-08-26T16:29:54.226Z",
  "_id": "000000000000000000000000",
  "data": {
    {
      "Title": "[SOME_TITLE]",
      "Content": "[SOME_CONTENT]",
      "Categories": "000000000000000000000001,000000000000000000000002,000000000000000000000003"
}
  },
  "name": "FORM_NAME",
  "site": "000000000000000000000000"
}

Creating a Collection Item with Multi-Reference fields

Now that we know how the event handler is setup and what the event object looks like, let's take a look at creating new collection items with these multi-reference fields.

When we get a new form submission we first check if the multi-reference field (in our case Categories) is present in the data object of the event. If it is, simply split it on the commas , to get a list of IDs, otherwise set it to an empty list:

let categoryIDs = (event.data.Categories && event.data.Categories.split(',')) || [];

Based on the example event object mentioned earlier, it will convert it to the following:

["000000000000000000000001", "000000000000000000000002", "000000000000000000000003"]

Note: You'd need to do this for every multi-refernce field you have in order to pass it in the endpoint below to create the collection item.

Next, to create the collection item in Webflow we utilize the
collections.items.create API endpoint from Autocode's Standard Library, and pass in the required fields:

  await lib.webflow.collections['@1.0.0'].items.create({
    collection_id: process.env.COLLECTION_ID,
    fields: {
      'name': `${event.data.Title}`,
      'categories': categoryIDs,
      '_archived': false,
      '_draft': false
    },
    live: true
  });

collection_id: is the ID of the collection in the CMS to create the item in. To get that ID, navigate to the CMS tab in the Webflow designer of your site, then click on the settings button for the Collection (in this case Blog Posts) and it should be there

fields: the fields of the item that will be created. Notice how we passed in the categoryIDs list to the categories field to reference the categories that the blog post maps to in Webflow
live: whether or not the item should be published to the live site when created

Once that endpoint is called, the new item will be created and appear in the Blog Posts CMS in Webflow.

Tying it all together

The final result of the event handler should look something like this:

const lib = require('lib')({token: process.env.STDLIB_SECRET_TOKEN});

/**
* An HTTP endpoint that acts as a webhook for Webflow form_submission event
* @param {object} event
* @returns {object} result Your return value
*/
module.exports = async (event) => {
  let result = {};

  let categoryIDs = (event.data.Categories && event.data.Categories.split(',')) || [];

  await lib.webflow.collections['@1.0.0'].items.create({
    collection_id: process.env.COLLECTION_ID,
    fields: {
      'name': `${event.data.Title}`,
      'categories': categoryIDs,
      '_archived': false,
      '_draft': false
    },
    live: true
  });

  return result;
};

That's It!

Thank you for checking out this post. If you have any questions or feedback please feel free to join our community Slack channel. You can get an invite from the Community Tab in the top bar of the Autocode website.

You can also follow the Autocode team on Twitter for updates @AutocodeHQ.

Setup a Custom Webhook URL in 30 Seconds with Autocode

Yusuf Musleh — Wed, 19 Aug 2020 06:44:35 +0000

TLDR (30s)

To quickly get your own customizable Webhook URL, simply Fork this Source in Autocode. You can change the name of the project if you'd like, as it's reflected in the webhook URL that's generated.

Once you've created the Fork you'll be brought into the Autocode editor. Click on the blue Deploy button at the bottom left corner of the editor. Once it's deployed, open the functions/__main__.js file to view the live Webhook URL at the bottom of the editor.

That's it! You can add whatever custom handling logic you'd like to the webhook at anytime, and simply click deploy again!

Note: Make sure you include the / at the end of the url otherwise it will be redirected and the payload will be dropped.

$ curl --request POST \
    --url https://YOUR_USERNAME.api.stdlib.com/my-webhook@dev/ \
    --header 'content-type: application/json' \
    --data '{
  "some_data": "This is sample data",
  "more_data": "More sample data"
}'

# OR

$ curl --request GET \
  --url 'https://YOUR_USERNAME.api.stdlib.com/my-webhook@dev/?some_data=%22This%20is%20sample%20data%22&more_data=%22More%20sample%20data%22'

Introduction

Often when working on projects that involve integrating different tools together or syncing data between different services, you may find yourself utilizing webhooks. A lot of tools/services allow you to set a webhook URL that they can then push data to based on some triggers. The webhook server behind that URL can then perform custom logic with that data.

Sounds pretty straightforward right? However, you'll realize you have to provision a new server, develop and deploy a web app, and worry about other administrative tasks such as maintenance and scalability. Not to mention, every time you want to make changes or test different payloads, you'd need to go through the deployment process again.

This adds a lot of hurdles just to perform a simple task of receiving and handling data from an external service.

We get a lot of questions about setting up webhooks at Autocode, and I think it's the easiest way to get started and have a live webhook URL in (literally) seconds. I built a Source in Autocode that you can simply fork and deploy to get your own webhook URL in no time!

Your webhook is deployed on top of serverless technology. That means it will scale for you without any need for administrative efforts on your end.

How It Works

When your webhook is deployed on Autocode, the endpoint listens to incoming requests. It accepts both GET and POST requests. The parameters passed in from either the request body or querystrings are parsed out and included in the context.params object. context is a magic parameter that we populate automatically. It must be the last parameter in the list of parameters you define in your function signature. You can access the headers or the actual request body and other useful data from within the context object:

/**
* An HTTP endpoint that acts as a webhook for HTTP(S) request event
* @returns {object} result Your return value
*/
module.exports = async (context) => {
  let result = {};

  console.log('params:', context.params);
  console.log('headers:', context.http.headers);
  console.log('body:', context.http.body);

  return result;
};

You can also pass in named parameters with type checking included out of the box based on the FunctionScript specification. Simply include the named parameter as an argument in the function and update the comment above the function defining the name and type of that parameter it should expect:

/**
* An HTTP endpoint that acts as a webhook for HTTP(S) request event
* @param {string} name
* @param {number} age 
* @returns {object} result Your return value
*/
module.exports = async (name = "Bob", age, context) => {
  let result = {};

  console.log('params:', context.params);
  console.log('headers:', context.http.headers);
  console.log('body:', context.http.body);

  return result;
};

Testing with Payloads

You can test your webhook URL before deploying it from within the Autocode editor.

Press on the Edit Test Event Payload at the top of the endpoint file:

That will open up the payload editor where you can enter a JSON formatted payload for testing:

Once you've finished setting a test payload and saved it, click on the green Run Test Event button at the bottom right corner of the editor. That will then open up a console displaying any logs or errors you may have:

Deploying your Webhook

When you're ready to deploy your webhook URL and start listening to incoming events, all you need to do is press on the blue Deploy button at the bottom left corner of the editor:

Once it's deployed, the URL displayed is now ready to handle events from any external service. You can also view real time logs by clicking on the View Logs button in the same corner of the editor.

Note: Make sure you include the / at the end of the URL otherwise it will be redirected and the payload will be dropped.

That's It!

Thanks for checking out this post! Hope it helped, if you have any questions please feel free to reach out to me at yusuf@autocode.com. I'd love to hear about what you're building! You can also follow the Autocode team on Twitter for more updates @AutocodeHQ.

Yusuf is a software engineer at Autocode.