Integrate Formium with Gatsby

Gatsby is a is a popular front-end framework that helps you create static apps and websites with React and GraphQL.

For those already familiar with Gatsby, Formium has an official Gatsby source plugin called gatsby-source-formium that streamlines data fetching by making your Formium project's forms queryable through Gatsby's GraphQL data layer.

Set Up Your Gatsby Project

Firstly, set up a Gatsby project by installing Gatsby CLI globally from your terminal:

npm i -g gatsby-cli

Then you can run the following command to create a Gatsby project locally:

gatsby new my-gatsby-project

Next, move into the directory from your terminal with cd my-gatsby-project. You can see your new project in a local development environment by using the npm develop command, set in the package.json by Gatsby CLI.

Install Formium dependencies

To use Formium with Gatsby, you'll want to install gatsby-source-formium, Formium React, and the Formium API client packages. We'll use them to query for your form schemas in GraphQL, render your forms in React, and finally send your submission data back to Formium.

You can install all the packages from NPM by running the following command:

npm i @formium/client @formium/react gatsby-source-formium --save

Setup gatsby-source-formium

gatsby-source-formium will fetch your project's form schemas from the Formium API and expose them to Gatsby's GraphQL data layer. However, the plugin requires you to configure it with a personal access token and project id to accomplish this.

To avoid having to commit secrets and other secured data to source control, we recommend using dotenv to expose both values as environment variables.

Read more about dotenv and using environment variables in Gatsby here.

Once installed, and once you have dotenv setup, add the follwing lines to your .env file.

GATSBY_FORMIUM_PROJECTID=XXXXX
FORMIUM_TOKEN=XXXXX

You'll need to replace the two XXXXXs in your .env file with the correct values for your specific Formium project and account. Here's how to get them:

• GATSBY_FORMIUM_PROJECTID - This is your project's public unique identifier. Go to the Formium dashboard, navigate to any of your project's form's Overview pages. Copy the Project ID from the API Information panel.

  

• FORMIUM_TOKEN - A secret personal access token to your account. You can create one in your Formium account settings here: https://dashboard.formium.io/account#tokens.

  

Now that you've have your credentials ready, add the gatsby-source-formium plugin to your gatsby-config.js file:

module.exports = {
  plugins: [
    {
      resolve: `gatsby-source-formium`,
      options: {
        // Get your projectId from https://dashboard.formium.io
        projectId: process.env.GATSBY_FORMIUM_PROJECTID,
        // Generate a personal access token by going to https://dashboard.formium.io/account#tokens
        accessToken: process.env.FORMIUM_TOKEN,
      },
    },
  ],
};

Once setup, you can run npm start which will trigger gatsby develop command. To check that everything worked, open Gatsby's GraphiQL IDE http://localhost:8000/___graphql to discover the types and properties of your GraphQL model. If you see allFormiumForm in the left sidebar. You're ready to rock!

Query with GraphQL

The gatsby-source-formium plugin will expose your Formium project's forms in Gatsby's GraphQL data layer as FormiumForm nodes.

You can query nodes created from Formium using GraphQL like the following:

{
  formiumForm(slug: { eq: "your_form_slug" }) {
    id
    name
    slug
    projectId
    schema
    createAt
    updateAt
  }
}

Render your form

Now that you have your project in Gatsby's GraphQL data layer, you can render your forms anywhere using the official <FormiumForm /> component from the @formium/react package and some GraphQL. The <FormiumForm /> component is a special React component we've built that interprets your form's schema and renders it. It also takes care of coordinating validation, conditional logic, and submission handling.

Let's make a new page for one of our Formium forms and use Gatsby's Page query to query for a specific Formium form in GraphQL:

import React from 'react';
import { graphql } from 'gatsby';
import { FormiumForm } from '@formium/react';
export default function FeedbackForm({ data }) {
  return <FormiumForm data={data.formiumForm} />;
}
export const query = graphql`
  {
    formiumForm(slug: { eq: "your_form_slug" }) {
      id
      createAt
      name
      projectId
      schema
      slug
      updateAt
      version
    }
  }
`;

We then pass the whole formiumForm object the <FormiumForm/> component. Note that the <FormiumForm> component needs all of the above information to function properly.

Submit form data

To submit data back to Formium API, we first need to create a Formium API client. Let's do that now in another file and then import it back into our feedback form.

import { createClient } from '@formium/client';
export const formium = createClient(process.env.GATSBY_FORMIUM_PROJECTID);

import React from 'react';
import { graphql } from 'gatsby';
import { FormiumForm } from '@formium/react';
import { formium } from '../lib/formium';
export default function FeedbackForm({ data }) {
  return (
    <FormiumForm
      data={data.formiumForm}
      onSubmit={async (values) => {
        // Send form values to Formium
        await formium.submitForm('your_form_slug', values);
        alert('Success');
      }}
    />
  );
}
export const query = graphql`
  {
    formiumForm(slug: { eq: "your_form_slug" }) {
      id
      createAt
      name
      projectId
      schema
      slug
      updateAt
      version
    }
  }
`;

Bonus: Show a success message

Showing a success message helps the user know that their response has been received successfully. Within your onSubmit callback, you can either use regular React to set some state or use Gatsby's navigate to redirect the user to a different page (with a success message on it).

import React from 'react';
import { graphql } from 'gatsby';
import { FormiumForm } from '@formium/react';
import { formium } from '../lib/formium';
export default function FeedbackForm({ data }) {
  const [success, setSuccess] = React.useState(false);
  if (success) {
    return <div>Thank you! Your response has been recorded.</div>;
  }
  return (
    <FormiumForm
      data={data.formiumForm}
      onSubmit={async (values) => {
        // Send form values to Formium
        await formium.submitForm('your_form_slug', values);
        setSuccess(true);
      }}
    />
  );
}
export const query = graphql`
  {
    formiumForm(slug: { eq: "your_form_slug" }) {
      id
      createAt
      name
      projectId
      schema
      slug
      updateAt
      version
    }
  }
`;

Use your own React components

Now that you have everything setup and the data flowing, head over to the @formium/react docs to learn how to use your own React components with <FormiumForm> instead of the default ones.