Перейти к содержимому

Builder.io и Astro

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

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

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

Заголовок раздела Предварительные требования

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

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

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

Заголовок раздела Настройка учетных данных

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

.env
BUILDER_API_PUBLIC_KEY=YOUR_API_KEY
BUILDER_BLOGPOST_MODEL='blogpost'

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

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

src/env.d.ts
interface ImportMetaEnv {
  readonly BUILDER_API_PUBLIC_KEY: string;
}

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

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

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

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

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

Заголовок раздела Создание модели для блога

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

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

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

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

  1. Текстовое поле

    • Название: “title”
    • Обязательное: Да
    • Значение по умолчанию “Я забыл дать этому заголовок”

    (остальные параметры оставьте по умолчанию)

  2. Текстовое поле

    • Название: “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

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

src/pages/builder-preview.astro
---
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-адреса предварительного просмотра

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

  2. Перейдите на вкладку Models в вашем пространстве Builder, выберите созданную модель и вставьте URL из шага 1 в поле Preview URL. Убедитесь, что URL-адрес является полным и включает протокол, например https://.

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

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

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

  1. Убедитесь, что ваш сайт работает (например, запущен dev-сервер) и маршрут /builder-preview работает.

  2. В пространстве Builder на вкладке Content нажмите на New, чтобы создать новую запись контента для модели blogpost.

  3. В только что открывшемся редакторе Builder вы должны увидеть страницу builder-preview.astro с большим Add Block в центре.

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

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

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

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

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

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.

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

src/pages/posts/[slug].astro
---
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

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

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

Netlify
Заголовок раздела Netlify
  1. Перейдите на панель управления вашего сайта, затем Site Settings и нажмите на Build & deploy.
  2. На вкладке Continuous Deployment найдите раздел Build hooks и нажмите на Add build hook.
  3. Укажите имя веб-хука и выберите ветку, на которой будет запускаться сборка. Нажмите на Save и скопируйте сгенерированный URL.
Vercel
Заголовок раздела Vercel
  1. Перейдите на панель управления проектом и нажмите на Settings.
  2. На вкладке Git найдите раздел Deploy Hooks.
  3. Укажите имя вашего веб-хука и ветку, на которой будет запускаться сборка. Нажмите Add и скопируйте сгенерированный URL.
Добавление вебхука в Builder
Заголовок раздела Добавление вебхука в Builder
  1. В панели инструментов Builder перейдите к модели blogpost. В разделе Show More Options выберите Edit Webhooks в самом низу.
  2. Добавьте новый веб-хук, нажав на Webhook. Вставьте URL-адрес, сгенерированный вашим хостинг-провайдером, в поле Url.
  3. Нажмите на Show Advanced под полем URL и переключите опцию, чтобы выбрать Disable Payload. При отключении полезной нагрузки Builder отправляет хостинг-провайдеру более простой POST-запрос, что может быть полезно по мере роста вашего сайта. Нажмите Done, чтобы сохранить этот выбор.

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

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

Заголовок раздела Официальные ресурсы

Ресурсы сообщества

Заголовок раздела Ресурсы сообщества

Дополнительные руководства по CMS

Внести свой вклад

Что у вас на уме?

Создать проблему в GitHub

Самый быстрый способ предупредить нашу команду о проблеме.

Сообщество