Представляем Crafter CMS Javascript SDK

Crafter CMS — это безголовая CMS, которая предоставляет все свои услуги и возможности потребителям через RESTful API. Это позволяет разработчикам легко встраивать поддержку контента (внешнее управление контентом, строками, мультимедиа и т. д.) в любое приложение, написанное на любом языке программирования.

Crafter CMS также поддерживает привязки для конкретных языков (например, Java, Groovy, Javascript, .Net и т. д.) и фреймворков (Angular, React, Vue и т. д.). Эти привязки делают модель программирования не просто простой, а естественной для языка или фреймворка. Использовать RESTful API легко, но собственные привязки еще больше сокращают время и сложность программирования, упрощая и сокращая код, необходимый для выполнения работы.

В этом блоге мы сосредоточимся на языковых привязках для Javascript, Crafter CMS Javascript SDK. Эти привязки можно использовать в любых приложениях на стороне клиента (например, в браузерном приложении) или на стороне сервера (например, Node.js).

Архитектура высокого уровня

Прежде чем мы углубимся в особенности Javascript SDK, давайте быстро рассмотрим архитектуру. Ниже приведена диаграмма, которая иллюстрирует, как SDK работает в вашем приложении Javascript с Crafter Engine и другими компонентами Crafter CMS для доставки управляемого контента в ваше приложение.

Вы можете узнать больше об общей архитектуре Crafter CMS здесь. На диаграмме выше мы иллюстрируем следующее:

Авторы работают в Crafter Studio (веб-приложение) для создания контента и управления им. Crafter Studio предоставляет авторам инструменты, необходимые им для обновления, выполнения рабочих процессов и публикации. Утвержденные обновления могут быть опубликованы в Crafter Engine для доставки контента в любое время через пользовательский интерфейс без какой-либо технической помощи.
Crafter Engine предоставляет контент, навигацию и структуры через службы RESTful, доступные через HTTP(s). Содержимое и данные возвращаются вызывающей стороне в формате JSON.
В этой архитектуре вызывающим абонентом является библиотека привязок Javascript Crafter CMS, которая делает запросы от имени приложения.
Crafter CMS Javascript SDK предоставляет код приложения с интерфейсами и классами на основе Javascript для взаимодействия. Коду приложения не нужно заниматься REST, JSON и другими концепциями более низкого уровня.

Предварительные условия для использования библиотеки

NPM/пряжа установлена
Выпуски SDK публикуются в Node Package Manager (NPM). Пример: https://www.npmjs.com/package/@craftercms/content
NPM поможет вам легко загрузить нужные зависимости. Вы все можете использовать NPM или Yarn для создания и выполнения вашего приложения.
В нашем примере я буду использовать Yarn для управления файлом package.json и для помощи в создании моего приложения.
Доступ к работающему экземпляру и сайту Crafter Engine.
Возможно, вам придется настроить сайт из-за CORS (ограничения совместного использования ресурсов между источниками в браузерах), чтобы разрешить запросы от вашего приложения, если приложение и Crafter Engine работают из разных базовых доменов. Мы объясним это позже.

Создание простого приложения Javascript

Цель нашего приложения в этом блоге — продемонстрировать, как включать и использовать Javascript SDK Crafter CMS в приложении и использовать его для извлечения содержимого из работающего экземпляра Crafter Engine. Мы собираемся оставить приложение очень простым, чтобы проиллюстрировать, что эта библиотека не зависит от каких-либо конкретных фреймворков или платформ, таких как Node.js, React, Angular6, Vue и т. д.

Для тех, кто хочет сразу приступить к интеграции, использование SDK начинается с шага 4.

Шаг 1. Создайте базовую структуру и соберите приложение

Первое, что мы хотим сделать, это создать каталог для нашего исходного кода приложения. Я назову свой каталог simple-js. В этот каталог добавьте файл с именем package.json со следующим содержимым:

{
 "name": "simple-js",
 "version": "1.0.0",
 "description": "Simple JS app that will use Crafter CMS Javascript SDK",
 "main": "index.js",
 "author": "Russ",
 "license": "MIT",
 "dependencies": {
 "@craftercms/classes": "^1.0.0",
 "@craftercms/content": "^1.0.0",
 "@craftercms/models": "^1.0.0",
 "@craftercms/search": "^1.0.0",
 "@craftercms/utils": "^1.0.0"
 },
 "scripts": {
 "test": "echo \"Error: no test specified\" && exit 1",
 "build": "webpack"
 },
 "devDependencies": {
 "webpack": "^4.17.1",
 "webpack-cli": "^3.1.0"
 }
}

Этот файл описывает наше приложение, как его собрать и что для этого нужно. В содержании выше мы видим:

Метаданные приложения.
Зависимости приложений, которые нам требуются, — это различные зависимости Crafter CMS Javascript SDK («@craftercms/content»: «¹.0.0», «@craftercms/search»: «¹.0.0» и т. д.)
Зависимости сборки/разработки приложения, которые помогают нам скомпилировать приложение для распространения («webpack»: «⁴.17.1», «webpack-cli»: «³.1.0».)

Шаг 2. Выполните первоначальную сборку

Запустите yarn в каталоге вашего приложения. Это загрузит все ваши зависимости.

Шаг 3: Создайте приложение Javascript

Обратите внимание, что в нашем package.json мы указали index.js в качестве основного для приложения. Давайте создадим каталог src и создадим index.js в каталоге src.

Я буду использовать команду Unix touch для создания index.js. Это создает пустой файл.

Когда файл будет на месте, вы можете запустить команду yarn build. Это создаст папку dist со скомпилированным файлом main.js. Файл main.js содержит уменьшенный объединенный набор ваших зависимостей и ваш код script.js (который в настоящее время пуст).

Шаг 4. Создайте HTML-код приложения

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

В каталоге simple-js добавьте файл index.html со следующим содержимым:

<!doctype html>
 <html>
   <head>
     <meta http-equiv="Content-Type" content="text/html;charset=ISO-8859-1">
     <title>Getting Started</title>
   </head>
   <body>
     <script src="./dist/main.js"></script>
   </body>
 </html>

Как видите, все, что делает этот HTML, — это объявляет заголовок и тело нашей страницы и вызывает файл сценария main.js.

Чтобы сделать наше приложение более интересным, давайте добавим некоторую базовую логику в наш файл script.js. Добавьте следующий код в файл src/script.js:

function component() {
  var element = document.createElement('div');
  element.innerHTML = "Hello World";
  document.body.appendChild(element);
}
component();

Теперь перестройте приложение с помощью команды yarn build и откройте файл index.html в браузере, чтобы увидеть, как работает ваше приложение.

Шаг 4: Вызов API Crafter CMS с помощью нашего приложения

Теперь, когда у нас есть очень простое работающее приложение, пришло время использовать Crafter CMS Javascript SDK.

Экземпляр Crafter Engine

Чтобы использовать API-интерфейсы Crafter CMS, вам потребуется работающий экземпляр Crafter Engine с настроенным проектом, к которому у вас есть доступ. Начать работу несложно. Вот несколько полезных ссылок по настройке:

Установка Crafter CMS: Установка Crafter CMS
Ваш первый проект веб-сайта: Создание и работа с вашим сайтом First Crafter

CORS: ПРАВИЛА МЕЖСАЙТОВОГО СЦЕНАРИЯ

Если вы шаг за шагом следуете этому блогу, вы, вероятно, используете Crafer Engine на локальном хосте и загружаете свой HTML-файл с локального диска (например, file:///Users/rdanner/code/simple-js/index.html. )

С точки зрения браузера http://localhost/… и file:///… — это разные хост-домены. Браузер по умолчанию не позволит вам совершать вызовы AJAX из кода, загруженного в одном домене, в другой домен, если принимающий домен не даст браузеру OK с соответствующими заголовками HTTP. Такое поведение браузера является защитой от атак типа CORS (Cross-Origin Requests/Cross-Site Scripting).

В Crafter CMS вы можете настроить правильные заголовки для принимающего сервера (Crafter Engine) для поддержки этого примера, выполнив следующие действия:

В Crafter Studio для вашего сайта/проекта перейдите в раздел Конфигурация сайта (находится на боковой панели).

Выберите инструмент Настройка. В раскрывающемся списке выберите параметр Конфигурация сайта двигателя.

Добавьте следующую конфигурацию и нажмите Сохранить внизу экрана.

Импортируйте API в ваше приложение javascript

Добавьте следующий код в самый верх файла скрипта index.js. Здесь мы объявляем классы, которые будем использовать, и указываем, откуда они импортированы (SDK).

import { ContentStoreService, NavigationService, UrlTransformationService } from '@craftercms/content';
import { crafterConf } from '@craftercms/classes';

Настройте SDK для базового URL-адреса вашей конечной точки Crafter Engine (имя сервера, порт и т. д.).

Теперь, когда вы объявили сервисы Crafter CMS SDK, которые хотите использовать, вы почти готовы приступить к извлечению контента. Прежде чем мы сможем это сделать, нам нужно убедиться, что API-интерфейсы SDK знают, где находится «конечная точка» / сервер Crafter Engine и с какого сайта извлекать контент. Для этого у нас есть два варианта:

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

Поскольку мы собираемся использовать ту же конечную точку и сайт, мы настроим объект конфигурации и передадим его при вызове API. Чтобы настроить конечную точку, мы добавляем следующий код в наш скрипт после операторов импорта:

crafterConf.configure({
 site: 'editorial'
});

В приведенной выше конфигурации указано, что наши вызовы API будут ссылаться на сайт в Crafter Engine, который имеет «редакционный» идентификатор. По умолчанию конфигурация предполагает, что Crafter Engine работает локально на порту 8080. Чтобы изменить это, добавьте следующее:

baseUrl: «ВАШ_ПРОТОКОЛ//ВАШ_ДОМЕН:ВАШ_ПОРТ»

crafterConf.configure({
 site: 'editorial',
 baseUrl: "https://mydotcomsite"
});

Если вы хотите, чтобы система предполагала, что приложение и конечные точки API находятся на одном сервере, вы можете установить базовый URL-адрес в виде пустой строки («»)

Вызов API Crafter CMS и получение контента

ВНЕСИТЕ ИЗМЕНЕНИЯ В КОД:

Теперь, когда библиотека импортирована и настроена, мы готовы ее использовать. Давайте добавим в наш пример код, чтобы сделать запрос контента и вывести его на экран для пользователя. Ниже приведен весь скрипт index.js для нашего приложения с изменениями:

import { ContentStoreService, NavigationService, UrlTransformationService } from '@craftercms/content';
import { crafterConf } from '@craftercms/classes';
crafterConf.configure({
 site: 'editorial'
})

function component() {
   ContentStoreService.getItem("/site/website/index.xml", crafterConf.getConfig()).subscribe((respItem) => {
      var element = document.createElement('div');
      element.innerHTML = respItem.descriptorDom.page['hero_title'];
      document.body.appendChild(element);
    })
}
component();

Что мы сделали, так это заменили код в функции component, которая была жестко запрограммирована для вывода «Hello World» на экран для пользователя, кодом, который вызывает Crafter CMS для content и вместо этого записывайте полученный контент на экран.

Давайте подробнее рассмотрим вызов API; ContentStoreService.getItem

Первый параметр — это путь к элементу контента, который мы хотим вернуть. В примере используется домашняя страница редакционного сайта.
Второй параметр — это наш объект конфигурации, который предоставляет конфигурацию базового URL-адреса сайта и конечной точки.
Наконец, обратите внимание на операцию subscribe. SDK выполняет асинхронные вызовы компонента Crafter Engine Crafter CMS. Подписка позволяет вам предоставить код, который вы хотите выполнить, когда вызов вернется. В нашем примере именно здесь мы создаем элемент, получаем значение содержимого (hero_title) из возвращенного ответа, а затем обновляем приложение содержимым.

СОСТАВЬТЕ КОД

После обновления кода перестройте приложение.

Протестируйте приложение

После компиляции, если вы обновите свое приложение, вы должны увидеть содержимое вашего проекта Crafter CMS в обновленном приложении!

Поздравляю! Содержимое вашего приложения теперь экстернализовано и управляется в CMS.

Шаг 5: Обновите свой контент с помощью CMS

Теперь, когда наш код завершен, наши авторы контента могут обновлять контент в любое время через CMS, и нам не нужно перестраивать или повторно развертывать приложение. Давайте воспользуемся Crafter Studio для обновления содержимого нашего приложения. Вы можете найти подробную инструкцию здесь: Создание и работа с вашим сайтом First Crafter

В Crafter Studio найдите контент, который хотите отредактировать.

В нашем случае контент, который мы потребляем, — это титул героя. Давайте внесем изменения в этот контент:
В предварительном просмотре контента вашего сайта включите карандаши для редактирования и нажмите на карандаш для названия героя (как показано выше). )

Обратите внимание, что у автора есть предварительный просмотр содержимого. Это что-то совсем другое и, в конечном счете, намного лучше, чем то, что вы видите в других системах Headless CMS.

С Crafter всегда можно предоставить пользователю предварительный просмотр контента, который он редактирует, независимо от интерфейсной среды. Возможность предварительного просмотра является ключевой, поскольку она упрощает редактирование контента для авторов.

Измените содержимое и сохраните

После того, как вы нажмете карандаш для текста Hero, внесите изменения, а затем нажмите кнопку «Сохранить и закрыть» в нижней части формы. Вы сразу увидите свое обновление в CMS.

Обновите пример приложения

Вау! Эти изменения в CMS выглядят великолепно (если я могу так сказать :D!) Теперь пришло время увидеть изменения в нашем приложении. Просто обновите приложение в браузере. Никаких обновлений кода не требуется!

Это действительно так просто! Несколько строк кода позволяют нам создавать приложения с содержимым, конфигурацией и другими строками, которые мы можем обновлять в любое время без необходимости обновления или повторного развертывания нашего кода приложения.

Как насчет рабочего процесса и публикации?

Хороший вопрос! Большую часть времени вам нужен процесс проверки и утверждения, прежде чем обновления контента для приложений станут общедоступными. Мы называем этот процесс рабочим процессом и публикацией. Crafter CMS имеет готовые рабочие процессы и возможности публикации.

Чтобы сделать наш пример максимально простым, я сохранил архитектуру простой, и мы указали наше приложение непосредственно на Crafter Studio и сервер предварительного просмотра на локальном хосте, порт 80.

В приведенной выше конфигурации API сразу увидит обновления. Архитектура в разделе Высокоуровневая архитектура выше показывает типичную рабочую топологию, в которой обновления проходят рабочий процесс утверждения и публикации. После утверждения и публикации контент становится доступным для приложения.

Знакомство с SDK API

В нашем примере приложения мы использовали один метод службы из SDK. Теперь, когда мы знаем, как использовать SDK, давайте рассмотрим различные сервисы и методы обслуживания, которые предоставляет SDK:

ServiceDescriptionContent Service
(@craftercms/content) Этот пакет содержит службы для извлечения контента и навигации с помощью API, предлагаемых Crafter CMS.

Получить объект контента и связанные с ним атрибуты контента
Получить дерево объектов контента (дети, деревья и т.д.)
Получите динамическую навигацию и структуру хлебных крошек
Выполнение преобразований URL

Спецификация API и примеры:
https://www.npmjs.com/package/@craftercms/content

Служба поиска
(@craftercms/search) Этот пакет содержит инструменты для интеграции вашего приложения с Crafter Search.

Создание объектов запроса Crafter Search
Выполнять поисковые запросы Crafter

Спецификация API и примеры:
https://www.npmjs.com/package/@craftercms/search

Вывод

Javascript SDK Crafter CMS предоставляет разработчикам интерфейсов и полного стека, которые работают с Javascript и технологиями, связанными с Javascript, собственный программный API для работы, который значительно упрощает создание приложений с богатым содержанием.

Когда мы перестаем думать об этом, почти в каждом приложении есть контент. Если этот контент легко обновить, а обновление контента может быть выполнено нетехническими пользователями в любое время без сборки или развертывания, все выиграют:

Контент в приложении богаче и намного свежее
Разработчики тратят время на разработку, а не на обновления, не связанные с кодом.
Устранение отвлекающих факторов, не связанных с развертыванием, дает нам больше времени и делает наши команды более гибкими.
Наши бизнес-пользователи могут вносить свои изменения в любое время, что делает бизнес более гибким.

Возможности Headless CMS предоставляют пользователям, не являющимся техническими специалистами, возможность обновлять, выполнять рабочие процессы и публиковать содержимое приложения в любое время без участия разработчиков и ИТ-специалистов.

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