Builder.io и Astro
Builder.io — это графическая CMS, поддерживающая редактирование контента методом перетаскивания для создания веб-сайтов.
Эта инструкция покажет вам, как подключить ваше пространство Builder к Astro без использования клиентского JavaScript.
Предварительные требования
Заголовок раздела Предварительные требованияДля начала вам потребуется следующее:
- Учетная запись и пространство Builder - Если у вас еще нет аккаунта, зарегистрируйтесь бесплатно и создайте новое пространство. Если у вас уже есть пространство в Builder, смело используйте его, но вам нужно будет изменить код, чтобы он соответствовал названию модели (
blogpost
) и полям пользовательских данных. - API-ключ Builder - этот открытый ключ будет использоваться для получения вашего контента из Builder. Прочтите руководство Builder о том, как найти ваш ключ..
Настройка учетных данных
Заголовок раздела Настройка учетных данныхЧтобы добавить ключ API Builder и имя модели Builder в Astro, создайте файл .env
в корне вашего проекта (если он еще не существует) и добавьте в него следующие переменные:
Теперь вы можете использовать этот API-ключ в своем проекте.
На момент написания статьи этот ключ является публичным, поэтому вам не нужно беспокоиться о его сокрытии или шифровании.
Если вы хотите получить подсказки IntelliSense для ваших переменных среды, вы можете создать файл env.d.ts
в директории src/
и настроить ImportMetaEnv
следующим образом:
Теперь ваш проект должен включать эти файлы:
Directorysrc/
- env.d.ts
- .env
- astro.config.mjs
- package.json
Создание блога с помощью Astro и Builder
Заголовок раздела Создание блога с помощью Astro и BuilderСоздание модели для блога
Заголовок раздела Создание модели для блогаИнструкции ниже создают блог Astro с использованием модели Builder (Тип: “Section”), называемой blogpost
, которая содержит два обязательных текстовых поля: title
и slug
.
Вы можете найти видео, демонстрирующее эту процедуру, в одном из официальных учебных пособий Builder.
В приложении Builder создайте модель, которая будет представлять запись в блоге: перейдите на вкладку Models и нажмите кнопку + Create Model, чтобы создать модель со следующими полями и значениями:
- Тип: Section
- Имя: “blogpost”
- Описание: “Эта модель предназначена для записи в блоге”.
В новой модели с помощью кнопки + New Custom Field создайте 2 новых поля:
-
Текстовое поле
- Название: “title”
- Обязательное: Да
- Значение по умолчанию “Я забыл дать этому заголовок”
(остальные параметры оставьте по умолчанию)
-
Текстовое поле
- Название: “slug”
- Обязательное: Да
- Значение по умолчанию “some-slugs-take-their-time”
(остальные параметры оставьте по умолчанию)
Затем нажмите кнопку Save в правом верхнем углу.
С полем slug
есть несколько подводных камней:
-
Убедитесь, что ваш слаг не является просто числом. Это, похоже, приводит к поломке запроса на получение в API Builder.
-
Убедитесь, что ваши слаги уникальны, так как от этого будет зависеть маршрутизация вашего сайта.
Настройка предпросмотра
Заголовок раздела Настройка предпросмотраЧтобы использовать графический редактор Builder, создайте страницу src/pages/builder-preview.astro
, которая будет отображать специальный <builder-component>
:
Directorysrc/
Directorypages/
- builder-preview.astro
- env.d.ts
- .env
- astro.config.mjs
- package.json
Затем добавьте следующее содержимое:
В приведенном выше примере <builder-component>
указывает Builder, куда вставлять контент из его CMS.
Установка нового маршрута в качестве URL-адреса предварительного просмотра
Заголовок раздела Установка нового маршрута в качестве URL-адреса предварительного просмотра-
Скопируйте полный URL-адрес превью, включая протокол, в буфер обмена (например,
https://{ваш хост}/builder-preview
). -
Перейдите на вкладку Models в вашем пространстве Builder, выберите созданную модель и вставьте URL из шага 1 в поле Preview URL. Убедитесь, что URL-адрес является полным и включает протокол, например
https://
. -
Нажмите кнопку Save в правом верхнем углу.
При развертывании сайта измените URL-адрес предварительного просмотра, чтобы он соответствовал производственному URL-адресу, например https://myAwesomeAstroBlog.com/builder-preview
.
Проверка настройки URL-адреса предварительного просмотра
Заголовок раздела Проверка настройки 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
, чтобы получить и отобразить список заголовков всех постов, каждый из которых будет ссылаться на свою страницу:
Получение данных через API возвращает массив объектов, содержащих данные для каждой записи. Параметр запроса fields
указывает Builder, какие данные включены (см. выделенный код). slug
и title
должны соответствовать именам пользовательских полей данных, которые вы добавили в свою модель Builder.
Массив posts
, возвращаемый запросом, отображает список заголовков блогов на домашней странице. Индивидуальные маршруты страниц будут созданы на следующем этапе.
Если вы используете JavaScript-фреймворк (например, Svelte, Vue или React) в своем проекте Astro, вы можете использовать одну из интеграций Builder в качестве альтернативы необработанным вызовам fetch через REST API.
Перейдите на ваш индексный маршрут и вы увидите список ссылок, каждая из которых содержит название записи в блоге!
Отображение одной записи в блоге
Заголовок раздела Отображение одной записи в блогеСоздайте страницу src/pages/posts/[slug].astro
, которая будет динамически генерировать страницу для каждого поста.
Directorysrc/
Directorypages/
- index.astro
Directoryposts/
- [slug].astro
- env.d.ts
- .env
- astro.config.mjs
- package.json
Этот файл должен содержать:
- Функция
getStaticPaths()
для получения информации оslug
из Builder и создания статического маршрута для каждой записи блога. - Функция
fetch()
для обращения к API Builder с использованием идентификатораslug
для возврата содержимого поста и метаданных (например,title
). - Фрагмент
<Fragment />
в шаблоне для отображения содержимого поста в виде HTML.
Каждый из них выделен в следующем фрагменте кода.
Переменные builderModel
и builderAPIpublicKey
должны быть созданы дважды, поскольку getStaticPaths()
выполняется в собственной изолированной области.
Теперь при нажатии на ссылку в индексном маршруте вы будете переходить на страницу отдельной записи блога.
Публикация сайта
Заголовок раздела Публикация сайтаДля развертывания вашего веб-сайта посетите наши руководства по развертыванию и следуйте инструкциям для выбранного вами хостинг-провайдера.
Пересборка при изменениях в Builder
Заголовок раздела Пересборка при изменениях в BuilderЕсли ваш проект использует стандартный статический режим Astro, вам потребуется настроить вебхук для запуска новой сборки при изменении вашего контента. Если вы используете Netlify или Vercel в качестве хостинг-провайдера, вы можете использовать их функцию вебхуков для запуска новой сборки при нажатии Publish в редакторе Builder.
Netlify
Заголовок раздела Netlify- Перейдите на панель управления вашего сайта, затем Site Settings и нажмите на Build & deploy.
- На вкладке Continuous Deployment найдите раздел Build hooks и нажмите на Add build hook.
- Укажите имя веб-хука и выберите ветку, на которой будет запускаться сборка. Нажмите на Save и скопируйте сгенерированный URL.
Vercel
Заголовок раздела Vercel- Перейдите на панель управления проектом и нажмите на Settings.
- На вкладке Git найдите раздел Deploy Hooks.
- Укажите имя вашего веб-хука и ветку, на которой будет запускаться сборка. Нажмите Add и скопируйте сгенерированный URL.
Добавление вебхука в Builder
Заголовок раздела Добавление вебхука в BuilderДополнительные сведения см. в Руководстве по добавлению вебхуков в 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.
Ресурсы сообщества
Заголовок раздела Ресурсы сообщества- Читайте Подключение графической CMS Builder.io к Astro Йоава Ганбара.