Builder.io и Astro

Builder.io — это графическая CMS, поддерживающая редактирование контента методом перетаскивания для создания веб-сайтов.

Эта инструкция покажет вам, как подключить ваше пространство Builder к Astro без использования клиентского JavaScript.

Предварительные требования

Для начала вам потребуется следующее:

Учетная запись и пространство Builder - Если у вас еще нет аккаунта, зарегистрируйтесь бесплатно и создайте новое пространство. Если у вас уже есть пространство в Builder, смело используйте его, но вам нужно будет изменить код, чтобы он соответствовал названию модели (blogpost) и полям пользовательских данных.
API-ключ Builder - этот открытый ключ будет использоваться для получения вашего контента из Builder. Прочтите руководство Builder о том, как найти ваш ключ..

Настройка учетных данных

Чтобы добавить ключ API Builder и имя модели Builder в Astro, создайте файл .env в корне вашего проекта (если он еще не существует) и добавьте в него следующие переменные:

BUILDER_API_PUBLIC_KEY=YOUR_API_KEY
BUILDER_BLOGPOST_MODEL='blogpost'

Теперь вы можете использовать этот API-ключ в своем проекте.

Если вы хотите получить подсказки IntelliSense для ваших переменных среды, вы можете создать файл env.d.ts в директории src/ и настроить ImportMetaEnv следующим образом:

interface ImportMetaEnv {
  readonly BUILDER_API_PUBLIC_KEY: string;
}

Теперь ваш проект должен включать эти файлы:

Директорияsrc/
- env.d.ts
.env
astro.config.mjs
package.json

Создание блога с помощью Astro и Builder

Создание модели для блога

Инструкции ниже создают блог Astro с использованием модели Builder (Тип: “Section”), называемой blogpost, которая содержит два обязательных текстовых поля: title и slug.

В приложении Builder создайте модель, которая будет представлять запись в блоге: перейдите на вкладку Models и нажмите кнопку + Create Model, чтобы создать модель со следующими полями и значениями:

Тип: Section
Имя: “blogpost”
Описание: “Эта модель предназначена для записи в блоге”.

В новой модели с помощью кнопки + New Custom Field создайте 2 новых поля:

Текстовое поле
- Название: “title”
- Обязательное: Да
- Значение по умолчанию “Я забыл дать этому заголовок”
(остальные параметры оставьте по умолчанию)
Текстовое поле
- Название: “slug”
- Обязательное: Да
- Значение по умолчанию “some-slugs-take-their-time”
(остальные параметры оставьте по умолчанию)

Затем нажмите кнопку Save в правом верхнем углу.

Настройка предпросмотра

Чтобы использовать графический редактор Builder, создайте страницу src/pages/builder-preview.astro, которая будет отображать специальный <builder-component>:

Директорияsrc/
- Директорияpages/
  - builder-preview.astro
- env.d.ts
.env
astro.config.mjs
package.json

Затем добавьте следующее содержимое:

---
const builderAPIpublicKey = import.meta.env.BUILDER_API_PUBLIC_KEY;
const builderModel = import.meta.env.BUILDER_BLOGPOST_MODEL;
---

<html lang="en">
  <head>
    <title>Preview for builder.io</title>
  </head>
  <body>
    <header>This is your header</header>

    <builder-component model={builderModel} api-key={builderAPIpublicKey}
    ></builder-component>
    <script async src="https://cdn.builder.io/js/webcomponents"></script>

    <footer>This is your footer</footer>
  </body>
</html>

В приведенном выше примере <builder-component> указывает Builder, куда вставлять контент из его CMS.

Установка нового маршрута в качестве URL-адреса предварительного просмотра

Скопируйте полный URL-адрес превью, включая протокол, в буфер обмена (например, https://{ваш хост}/builder-preview).
Перейдите на вкладку Models в вашем пространстве Builder, выберите созданную модель и вставьте URL из шага 1 в поле Preview URL. Убедитесь, что URL-адрес является полным и включает протокол, например https://.
Нажмите кнопку Save в правом верхнем углу.

Проверка настройки URL-адреса предварительного просмотра

Убедитесь, что ваш сайт работает (например, запущен dev-сервер) и маршрут /builder-preview работает.
В пространстве Builder на вкладке Content нажмите на New, чтобы создать новую запись контента для модели blogpost.
В только что открывшемся редакторе Builder вы должны увидеть страницу builder-preview.astro с большим Add Block в центре.

Иногда при настройке предварительного просмотра что-то может пойти не так. Если что-то не так, вы можете попробовать следующее:

Убедитесь, что сайт работает — например, запущен ваш сервер разработки.
Убедитесь, что URL-адреса точно совпадают — тот, что в проекте Astro, и тот, что задан в приложении Builder.
Убедитесь, что это полный URL, включая протокол, например https://.
Если вы работаете в виртуальной среде, например StackBlitz или Gitpod, вам, возможно, придется скопировать и вставить URL заново при перезапуске рабочей области, поскольку при этом обычно генерируется новый URL для вашего проекта.

Дополнительные идеи можно найти в руководстве по устранению неполадок от Builder.

Создание записи в блоге

В графическом редакторе Builder создайте новую запись контента со следующими значениями:
- заголовок: ‘Первая запись, ура!’
- slug: ‘first-post-woohoo’
Дополните пост с помощью кнопки Add Block и добавьте текстовое поле с содержимым поста.
В текстовом поле над редактором дайте вашей записи имя. Так она будет отображаться в приложении Builder.
Когда вы будете готовы, нажмите кнопку Publish в правом верхнем углу.
Создавайте столько постов, сколько хотите, следя за тем, чтобы все записи содержали title и slug, а также некоторое содержание поста.

Отображение списка записей в блоге

Добавьте следующее содержимое в src/pages/index.astro, чтобы получить и отобразить список заголовков всех постов, каждый из которых будет ссылаться на свою страницу:

---


const builderAPIpublicKey = import.meta.env.BUILDER_API_PUBLIC_KEY;
const builderModel = import.meta.env.BUILDER_BLOGPOST_MODEL;

const { results: posts } = await fetch(
  `https://cdn.builder.io/api/v3/content/${builderModel}?${new URLSearchParams({
    apiKey: builderAPIpublicKey,
    fields: ["data.slug", "data.title"].join(","),
    cachebust: "true",
  }).toString()}`
)
  .then((res) => res.json())
  .catch();
---

<html lang="en">
  <head>
    <title>Blog Index</title>
  </head>
  <body>
    <ul>
      {
        posts.map(({ data: { slug, title } }) => (
          <li>
            <a href={`/posts/${slug}`}>{title}</a>
          </li>
        ))
      }
    </ul>
  </body>
</html>

Получение данных через API возвращает массив объектов, содержащих данные для каждой записи. Параметр запроса fields указывает Builder, какие данные включены (см. выделенный код). slug и title должны соответствовать именам пользовательских полей данных, которые вы добавили в свою модель Builder.

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

Перейдите на ваш индексный маршрут и вы увидите список ссылок, каждая из которых содержит название записи в блоге!

Отображение одной записи в блоге

Создайте страницу src/pages/posts/[slug].astro, которая будет динамически генерировать страницу для каждого поста.

Директорияsrc/
- Директорияpages/
  - index.astro
  - Директорияposts/
    [slug].astro
- env.d.ts
.env
astro.config.mjs
package.json

Этот файл должен содержать:

Функция getStaticPaths() для получения информации о slug из Builder и создания статического маршрута для каждой записи блога.
Функция fetch() для обращения к API Builder с использованием идентификатора slug для возврата содержимого поста и метаданных (например, title).
Фрагмент <Fragment /> в шаблоне для отображения содержимого поста в виде HTML.

Каждый из них выделен в следующем фрагменте кода.

---
export async function getStaticPaths() {
  const builderModel = import.meta.env.BUILDER_BLOGPOST_MODEL;
  const builderAPIpublicKey = import.meta.env.BUILDER_API_PUBLIC_KEY;
  const { results: posts } = await fetch(
    `https://cdn.builder.io/api/v3/content/${builderModel}?${new URLSearchParams(
      {
        apiKey: builderAPIpublicKey,
        fields: ["data.slug", "data.title"].join(","),
        cachebust: "true",
      }
    ).toString()}`
  )
    .then((res) => res.json())
    .catch
    // ...catch some errors...);
    ();
  return [
    ...posts.map(({ data: { slug, title } }) => [
      {
        params: { slug },
        props: { title },
      },
    ]),
  ];
}
const { slug } = Astro.params;
const { title } = Astro.props;
const builderModel = import.meta.env.BUILDER_BLOGPOST_MODEL;
const builderAPIpublicKey = import.meta.env.BUILDER_API_PUBLIC_KEY;
// Builder's API requires this field but for this use case the url doesn't seem to matter - the API returns the same HTML
const encodedUrl = encodeURIComponent("moot");
const { html: postHTML } = await fetch(
  `https://cdn.builder.io/api/v1/qwik/${builderModel}?${new URLSearchParams({
    apiKey: builderAPIpublicKey,
    url: encodedUrl,
    "query.data.slug": slug,
    cachebust: "true",
  }).toString()}`
)
  .then((res) => res.json())
  .catch();
---
<html lang="en">
  <head>
    <title>{title}</title>
  </head>
  <body>
    <header>This is your header</header>
    <article>
      <Fragment set:html={postHTML} />
    </article>
    <footer>The is your footer</footer>
  </body>
</html>

Теперь при нажатии на ссылку в индексном маршруте вы будете переходить на страницу отдельной записи блога.

Публикация сайта

Для развертывания вашего веб-сайта посетите наши руководства по развертыванию и следуйте инструкциям для выбранного вами хостинг-провайдера.

Пересборка при изменениях в Builder

Если ваш проект использует стандартный статический режим Astro, вам потребуется настроить вебхук для запуска новой сборки при изменении вашего контента. Если вы используете Netlify или Vercel в качестве хостинг-провайдера, вы можете использовать их функцию вебхуков для запуска новой сборки при нажатии Publish в редакторе Builder.

Netlify

Перейдите на панель управления вашего сайта, затем Site Settings и нажмите на Build & deploy.
На вкладке Continuous Deployment найдите раздел Build hooks и нажмите на Add build hook.
Укажите имя веб-хука и выберите ветку, на которой будет запускаться сборка. Нажмите на Save и скопируйте сгенерированный URL.

Vercel

Перейдите на панель управления проектом и нажмите на Settings.
На вкладке Git найдите раздел Deploy Hooks.
Укажите имя вашего веб-хука и ветку, на которой будет запускаться сборка. Нажмите Add и скопируйте сгенерированный URL.

Добавление вебхука в Builder

В панели инструментов Builder перейдите к модели blogpost. В разделе Show More Options выберите Edit Webhooks в самом низу.
Добавьте новый веб-хук, нажав на Webhook. Вставьте URL-адрес, сгенерированный вашим хостинг-провайдером, в поле Url.
Нажмите на Show Advanced под полем URL и переключите опцию, чтобы выбрать Disable Payload. При отключении полезной нагрузки Builder отправляет хостинг-провайдеру более простой POST-запрос, что может быть полезно по мере роста вашего сайта. Нажмите Done, чтобы сохранить этот выбор.

Когда вы нажмете кнопку Publish в редакторе Builder, ваш хостинг-провайдер перестроит ваш сайт, и Astro получит новые опубликованные данные для вас. Остается только откинуться на спинку кресла и выкладывать этот сладкий контент!

Официальные ресурсы

Ознакомьтесь с официальным стартовым проектом Builder.io, в котором используются Astro и SolidJS.
В официальном руководстве по быстрому запуску Builder рассказывается как об использовании REST API, так и о получении данных через интеграцию с JavaScript-фреймворком, например Qwik, React или Vue.
Builder’s API explorer может помочь, если вам нужно устранить неполадки с вызовами API.