Как использовать Airtable с Gatsby

Airtable — это облачное гибридное приложение для совместной работы с базой данных и таблицами. Оно предлагает гибкий и интуитивно понятный графический интерфейс, разумные цены (и довольно щедрый бесплатный арсенал инструментов) и полный REST API с отличной автоматически созданной документацией. Также данное приложение отлично работает в качестве источника данных для Gatsby.js. В этом мануале вы узнаете, как настроить его для этого.

В этом уроке мы сначала создадим очень простое меню с помощью Airtable, а затем без особых усилий отобразим его на веб-сайте Gatsby. Предполагаем, что у вас уже есть базовый проект Gatsby.js и вы готовы его редактировать. Если же вы хотите потренироваться на тестовом приложении, выполните мануал Gatsby v2: с чего начать работу?, а затем вернитесь сюда.

Настройка Airtable

Поскольку мануал в основном сосредоточен на Gatsby, мы рассмотрим только общие шаги, связанные с Airtable. Вы быстро увидите, что пользовательский интерфейс Airtable интуитивно понятен, а документация при необходимости быстро генерируется. Тем не менее, рекомендуем все же не торопиться и постепенно изучить доступные функции.

1: Создайте учетную запись Airtable

Первое, что нам нужно сделать, это создать учетную запись Airtable, если у вас ее еще нет. Просто зайдите на сайт Airtable и нажмите Sign Up в главной панели навигации.

После того как вы зарегистрируетесь и войдете в систему, вы окажетесь на главной панели инструментов. Изначально вам предоставляется единая рабочая область, workspace, в которой хранится набор образцов bases (это базы данных). Каждая база может содержать любое количество таблиц, которые работают так же, как таблицы базы данных.

Рабочие пространства и базы можно создавать бесплатно. Создайте здесь новое пустое рабочее пространство, если хотите – это рекомендуется сделать, но не обязательно.

2: Создайте новую базу

Для нашего меню нужно создать новую базу. Нажмите на серую кнопку Add a base внутри рабочей области.

При появлении запроса выберите вариант start from scratch, а затем во всплывающем окне присвойте новой базе название. Вы также можете выбрать цвет и глиф для значка, если хотите. Давайте назовем нашу новую базу ChompsFoodTruck.

Примечание: При работе с клиентскими проектами в Airtable всегда создавайте индивидуальное рабочее пространство для каждого клиента. Доступ к базам нельзя передавать, зато можно передать права на рабочие пространства.

3: Переименуйте таблицу по умолчанию

Когда новая база инициализирована, кликните на ее значок, чтобы начать ее настройку.

Обратите внимание, вкладка вверху стандартно помечена как Table 1, и ее лучше переименовать во что-то более подходящее. Давайте назовем ее Sandwiches.

Поскольку мы будем ссылаться на это имя таблицы в Gatsby, рекомендуем использовать именования в стиле camelCase или PascalCase, если имя таблицы состоит из нескольких слов (например, SoupsAndSalads).

4: Отредактируйте таблицу

Давайте отредактируем структуру таблицы Sandwiches следующим образом:

  1. Удалим стандартные столбцы Notes и Attachments.
  2. Создадим два новых столбца: Description  (тип: Single Line Text) и Price (тип: Currency).
  3. Добавим несколько строк данных. Запишите в меню свои любимые бутерброды и придумайте цену и описание для каждого.

Итак, теперь у нас есть простая таблица с сэндвичами в базе ChompsFoodTruck. Мы могли бы легко продублировать ее, чтобы создать другие разделы меню, такие как гарниры или напитки, но не будем усложнять.

5: Учетные данные Airtable API

Остался последний шаг в Airtable: получить наши учетные данные API. Для вызовов API Airtable требуется как базовый ID, так и ключ API.

Чтобы получить базовый ID, нажмите Help рядом со ссылкой на ваш профиль (вверху справа), а затем нажмите API documentation в выпадающем списке. Это автоматически создаст свежую документацию для базы ChompsFoodTruck в новой вкладке браузера. Затем кликните на ссылку Sandwiches, и в примере кода (JavaScript) справа вы увидите базовый идентификатор:

var base = new Airtable({apiKey: 'YOUR_API_KEY'})
                .base('appABCD12345'); // 👈 nice!

Чтобы получить ключ API, просто перейдите на обзор учетной записи. Там вы увидите кнопку для создания нового ключа.

Установка Airtable завершена!

Давайте вернемся к проекту Gatsby и попробуем интегрировать данные.

Внесение данных в Gatsby

В целом, мы могли бы написать простой код, используя примеры из документации Airtable, это несложно. Однако при работе с Gatsby всегда полезно заглянуть в раздел плагинов на официальном сайте, чтобы найти что-то полезное.

К счастью, в Gatsby есть отличный плагин gatsby-source-airtable, который нам подходит. Этот плагин может извлекать строки данных из нескольких баз и таблиц в Airtable и автоматически преобразовывать их все в узлы GraphQL.

1: Установка плагина

Первое, что нам нужно сделать, это установить плагин gatsby-source-airtable. Остановите сервер разработки, если он запущен, а затем введите:

$ yarn add gatsby-source-airtable

2: Конфигурация плагина

Как любой другой плагин Gatsby, это плагин нужно включить в gatsby-config.js и установить некоторые параметры. Давайте сделаем это сейчас. Вставьте его в массив plugins:

// ... siteMetadata above here
plugins: [
  {
    resolve: `gatsby-source-airtable`,
    options: {
      apiKey: `YOUR_AIRTABLE_API_KEY`,
      tables: [
        {
          baseId: `AIRTABLE_BASE_ID`,
          tableName: `Sandwiches`
        },
        // We can add other bases/tables here, too!
        //{
          //baseId: `AIRTABLE_BASE_ID`,
          //tableName: `Sides`
        //}
      ]
    }
  },
  // ... other plugins here
]

Это базовая конфигурация, и ее достаточно для извлечения данных. Давайте убедимся, что все работает, перезапустив наш сервер разработки, а затем открыв GraphiQL в браузере. Обычно это URL-адрес: http://localhost:8000/___graphql.

Вы должны увидеть две новые записи в верхней части меню слева: airtable и allAirtable. Если вы запросите данные в allAirtable.nodes, вы должны увидеть все свои данные из БД.

3: Отображение данных

На данный момент у нас настроена база Airtable и уже есть данные в узлах GraphQL, доступные для Gatsby. Все, что осталось сделать, это запросить и отобразить все на нашем сайте. Конечно, мы могли бы сделать это, используя запрос по странице, но давайте создадим новый компонент меню и будем использовать в нем статический запрос.

Создадим новый файл в /src/components/Menu.js и добавим следующий код:

import React from 'react';
import { useStaticQuery, graphql } from 'gatsby';

const Menu = () => {
  const data = useStaticQuery(graphql`
    query MenuQuery {
      sandwiches: allAirtable(
        filter: { table: { eq: "Sandwiches" } }
        sort: { fields: data___Price, order: DESC }
      ) {
        nodes {
          data {
            Name
            Price
            Description
          }
          recordId
        }
      }
    }
  `);

  return (
    <div>
      <h3>Sandwiches</h3>

      <ul>
        {data.sandwiches.nodes.map((item, i) => (
          <li key={item.recordId}>
            <p>
              {item.data.Name}, ${item.data.Price}
            </p>
            <p>{item.data.Description}</p>
          </li>
        ))}
      </ul>
    </div>
  );
};

export default Menu;

Как видите, мы просто отображаем наши данные и возвращаем элементы <li>. Обратите внимание, мы применяем более новую функцию Gatsby, useStaticQuery, которая использует встроенный хук React, чтобы разрешить запросы GraphQL внутри любого компонента во время сборки.

Важно: для этой функции требуется Gatsby версии 2.1.0 или выше и React 16.8.0 или выше.

Также заметьте, что мы используем параметр filter в запросе, чтобы убедиться, что мы извлекаем данные только из таблицы Sandwiches. Таким образом, мы могли бы создавать дополнительные запросы, если бы у нас были другие разделы.

Теперь мы можем использовать новый компонент Menu в любом месте нашего проекта. Конечно, в реальном приложении его лучше стилизовать.

Другие параметры плагина

В каждом объекте tables мы уже использовали два обязательных параметра, baseId и tableName, и они не требуют особых пояснений. Но есть несколько других полезных опций, доступных внутри каждого объекта. Давайте их рассмотрим:

  • tableView: (строка). Данная опция позволяет использовать собственное представление, которое вы настроили в Airtable (например, для индивидуального порядка строк и/или фильтрации, которую вы написали на стороне Airtable).
  • queryName: (строка). Иногда в двух разных базах встречаются таблицы с одинаковыми именами. С помощью этой опции вы можете задать альтернативное имя для таких таблиц, чтобы упростить работу с запросами GraphQL.
  • mapping: (объект). Данный параметр позволяет сопоставлять столбцы с определенными типами данных для преобразования Gatsby. Это бесценный параметр для работы с данными markdown или изображениями.
  • tableLinks: (массив строк) Airtable предлагает специальный тип столбца, который связывается с записями других таблиц. С помощью этой опции мы определяем эти имена столбцов, чтобы убедиться, что Гэтсби извлекает полные данные. (В противном случае будет получен только идентификатор каждого связанного элемента.)

В документации плагина все они описаны более подробно, а в репозитории на Github есть несколько классных примеров использования, включая обработку изображений и markdown.

Итоги

Как видите, Airtable и Gatsby.js – это отличный дуэт, особенно при участии плагина gatsby-source-airtable. Однако не останавливайтесь на достигнутом! Попробуйте поработать с Airtable самостоятельно, например:

  • Добавьте новые таблицы с другими разделами меню.
  • Создайте таблицу Info для хранения электронной почты, номера телефона, логотипа и т.д.
  • Добавьте изображения в меню, а затем используйте компонент Image для их отображения.
Tags: , ,

Добавить комментарий