Обновление контекстного редактирования в приложениях на JavaScript

Эта статья поможет вам перейти от системы ICE версии 3.x к системе Experience Builder (XB) версии 4.x.

DC CMS версии 3.x и более ранних версий включала функции "редактирования в контексте" (In-Context Editing (ICE)), которые теперь устарели в DC CMS 4.x. Эта статья предоставляет руководство по переходу от системы ICE версии 3.x к системе Experience Builder (XB) версии 4.x. Для новых проектов обращайтесь к документации Experience Builder.

DC CMS 4 представляет новые возможности, позволяющие авторам редактировать контент непосредственно в режиме предварительном просмотра, использовать контекстные меню для доступа к конкретным формам контента и применять улучшенную функциональность перетаскивания (drag&drop) для компонентов и ресурсов с рабочего стола или из новой панели ресурсов.

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

В новой системе каждое поле модели можно определить отдельно, что даёт возможность напрямую изменять эти поля. При необходимости авторы могут вызвать форму контента для всей модели или для отдельного поля без использования "ICE групп" в редакторе типов контента.

FreeMarker

До версии 4 ICE полагался на использование макросов FreeMarker, которые вызывались между обычными HTML-тегами.

Например:


      <!-- Declare an element which should show a pencil that opens
<section id="banner" <@studio.iceAttr iceGroup="hero"/>>...</section>


<!-- Declares a component drop target called `features_o` -->
<div class="features" <@studio.componentContainerAttr target="features_o" component=contentModel/>>...</div>

В Experience Builder (XB) группы ICE устарели, а авторы контента могут более точно управлять полями. Можно открывать и редактировать контент отдельных полей напрямую или в режиме WYSIWYG — в зависимости от типа поля. Следовательно, разработчикам больше не нужно указывать "ICE группы" в модели контента.

Запуск миграции

1. Чтобы начать миграцию, начните с поиска всех старых файлов импорта cstudio-support.ftl в ваших шаблонах FreeMarker.


      <#import "/templates/system/common/cstudio-support.ftl" as studio />

2. Замените файл импорта cstudio-support.ftl на новый файл cms.ftl.


      <#import "/templates/system/common/cms.ftl" as cms />

3. Удалите вызов макроса @studio.toolSupport, затем вставьте <@cms.head/> внутри тега <head>, <@cms.body_top/> в начале тега <body> и <@cms.body_bottom/> в конце тега <body>.


      <html>
<head>
  <meta charset="utf-8">
  <title>${model.title_t}</title>
  <@cms.head />
</head>
<body>
  <@cms.body_top/>
  <main>
    ...
  </main>
  <@cms.body_bottom/>
</body>
</html>

Все экземпляры макросов в cstudio-support.ftl должны быть заменены. Примеры этих макросов включают @studio.iceAttr, @studio.componentAttr и @studio.componentContainerAttr и другие. Все они должны быть удалены и заменены новой системой.

Новая система требует указания каждого поля модели, которое появляется на странице, для каждого элемента. Каждый тег на странице, который выводит что-то из модели типа контента DC CMS, должен иметь свой собственный элемент, и этот элемент должен быть помечен соответствующими атрибутами, предоставленными новыми встроенными макросами.

Простые значения

Найдите все интерполяционные выражения FreeMarker (например, ${contentModel.someFieldId}) в вашем HTML-коде, где они находятся внутри тега HTML. Например, правильно использовать ${contentModel.authorName_s}, где только интерполированное значение находится в своем теге контейнера, в отличие от By ${contentModel.authorName_s}, где есть еще один текст в том же элементе, что и интерполяция.

После того как вы найдете все интерполяции и убедитесь, что каждое выражение находится в своем элементе, замените обычный HTML-тег на макрос DC CMS. Например, ${contentModel.authorName_s} должно быть заменено на <@dc.span $field="authorName_s">${contentModel.authorName_s}</@dc.span>.

Помимо преобразования обычного тега в макро, вам необходимо указать дополнительные метаданные, зависящие от части модели, с которой вы работаете. Обычно интерполяции относятся к полю модели, которое является отсутствующим элементом метаданных в последнем примере. Добавьте атрибут $field к вашей модели со значением, которое является идентификатором поля, которое вы выводите.


      <@dc.span $field="authorName_s">${contentModel.authorName_s}</@dc.span>

Большинство тегов HTML соответствуют макросам. Однако для необычных или пользовательских тегов без соответствующего макроса вы можете использовать макрос @dc.tag. Этот макрос будет выводить любой указанный тег, предоставленный в его аргументе $tag.


      <@dc.tag $tag="author-name" $field="authorName_s">${contentModel.authorName_s}</@dc.tag>

Коллекции (компоненты и повторяющиеся группы)

Говоря о коллекциях, следует отметить появление новых макросов, предназначенных для решения типичных задач и сценариев, связанных с компонентными коллекциями или повторяющимися группами.

Прежние макросы, используемые для отображения коллекций (например, componentContainerAttr, componentContainerAttr, draggableComponent), следует заменить на renderComponentCollection или renderRepeatGroup. Если эти новые макросы не соответствуют вашему конкретному случаю использования, начните с понимания причин их неприменимости и в идеале обновите ваше приложение для использования этих макросов. Однако в более сложных ситуациях, когда эти макросы не подходят, вам придется вручную настроить разметку коллекции для включения Experience Builder. Это включает структурирование элементов для представления самого поля, каждого элемента внутри коллекции и для компонентов элемента, вложенного в каждый элемент для представления компонента.

Аналогично другим полям, между элементами поля и соответствующими параметрами элементов не должно быть посторонней разметки.

JavaScript

Подход к обновлению приложений на JavaScript будет зависеть от того, как вы изначально интегрировали ваше приложение с ICE. Если у вас не было возможности редактирования в контексте в вашем приложении, перейдите в документацию Experience Builder, чтобы узнать, как провести интеграцию.

Переход от настройки атрибутов вручную

Если вы устанавливаете атрибуты данных на своих элементах вручную, вы теоретически можете заменить старые атрибуты новыми. Однако рекомендуется использовать библиотеки JavaScript SDK, предоставляемые DC CMS для интеграции вашего приложения с Experience Builder. Вы можете использовать их напрямую из npm или скачать предварительно собранную версию — это на ваше усмотрение, но использование этих библиотек упростит интеграцию с Experience Builder и поможет предотвратить ошибки.

Атрибуты, используемые для старой системы редактирования в контексте, отличаются от тех, что используются в новой системе Experience Builder. Вам следует удалить все старые атрибуты, перечисленные ниже:

data-studio-ice
data-studio-ice-path
data-studio-ice-label
data-studio-component
data-studio-component-path
data-studio-embedded-item-id

Новыми атрибутами, которые нужно установить, являются:

data-dccms-model-id: уникальный идентификатор отображаемой модели, соответствующий тегу objectId в XML
data-dccms-model-path: путь к отображаемой модели
data-dccms-field-id: идентификатор поля в модели контента (применяется к полям, а не ко всей модели)
data-dccms-index: индекс внутри коллекции (важно для элементов коллекции или полей, вложенных в повторяющуюся группу)

Для реализации рекомендуется использовать JavaScript SDK, конкретно пакет @dccms/experience-builder. После установки или загрузки пакета можно использовать функцию getICEAttributes для получения объекта, содержащего все необходимые атрибуты и их значения. Эти атрибуты могут быть применены к вашим элементам в соответствии с требованиями вашего приложения. Если вы используете React, рассмотрите использование специфичных для React привязок, предоставляемых этим пакетом.

Переход из @dccms/ice

@dccms/ice пакет был заменен на @dccms/experience-builder. Вам следует обновить ваш код для использования нового пакета вместо старого.

Новый пакет включает функцию с названием getICEAttributes для извлечения атрибутов, которые будут установлены на ваши элементы. Хотя аргументы похожи, они не идентичны, поэтому обновите их соответствующим образом.
Если вы ранее использовали repaintPencils, то теперь вы можете его удалить, так как это больше не требуется.
Функция getDropZoneAttributes была заменена на getICEAttributes. Вам больше не нужно использовать отдельную функцию для зон перетаскивания; все поля должны использовать getICEAttributes вместо этого.
Метод reportNavigation был заменен на initExperienceBuilder. Если вы использовали навигацию через report, рассмотрите возможность инициализации Experience Builder вручную. Для этого включите initializeInContextEditing=false в ваш вызов dc.body_bottom (например, <@dc.body_bottom initializeInContextEditing=false />). После каждого рендера страницы, где происходит навигация, вызовите initExperienceBuilder для информирования CMS Studio о новом виде страницы. Перед инициализацией нового вида вызовите функцию unmount, возвращаемую initExperienceBuilder (например, initExperienceBuilder({ ... }).unmount()).
Кроме того, новый пакет экспортирует fetchIsAuthoring и addAuthoringSupport, которые эквивалентны методам, найденным в обоих пакетах.

Связанные статьи

Документация для разработчиков