Шаблоны

В этой статье вы узнаете, что такое шаблон в DC CMS, а также алгоритм его создания, установки и редактирования.

Что такое шаблон?

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

Стандартный шаблон, включенный в DC CMS - Web Blog Template, который предоставляет начальную структуру проекта. Этот шаблон включает навигацию проекта, наследование контента, таксономию для организации контента (например, категории, сегменты), которые также используются для таргетинга контента. Кроме того, он включает статические активы, такие как изображения и шрифты, а также файлы конфигурации для управления сегментами, разрешениями, сопоставлением ролей, конфигурацией RTE и многое другое.

Как было отмечено ранее, шаблоны предоставляют возможность создавать проекты с предопределенными макетами, контентом и конфигурациями. В то же время пользователи могут создавать новые шаблоны на основе существующих проектов, расширяя возможности DC CMS для создания разнообразных проектов на основе новых разработанных шаблонов.

Разработчики могут предоставлять свои шаблоны в CMS Marketplace GitHub App. Каталог CMS Marketplace отображает представленные шаблоны, позволяя пользователям напрямую создавать проекты на основе плагинов Marketplace из диалогового окна создания проекта CMS.

Создание шаблона

Шаблоны во многом похожи на проект. Поэтому вы можете использовать новый проект, созданный на основе шаблона “Empty”, в качестве отправной точки для вашего шаблона.

Адаптация HTML-шаблона

Если у вас есть существующий чистый HTML-шаблон, вы можете превратить его в шаблон для использования в рамках DC CMS.

Для этого продублируйте все файлы, исключая index.html и любые другие .html файлы, в папку static-assets вашего проекта.

HTML-файлы преобразуются в шаблоны Freemarker. В этом руководстве мы покажем, как адаптировать страницу index.html, а затем вы сможете адаптировать и другие страницы по образцу.

Начните процесс с изменения ftl-шаблона главной страницы, заменив ее содержимое содержимым файла index.html.

Оставьте <#import "/templates/system/common/cms.ftl" as cms /> в начале для корректной работы CMS Studio. Затем исправьте расположение ресурсов, которые, вероятно, указывают на неверные места. Замените каждый URL, не указывающий на страницу (включая <link rel="stylesheet" href=" для файлов CSS, <script src=" для файлов JS, <img src=" для файлов изображений и <source src=" для видео- и звуковых файлов) так, чтобы они начинались с /static-assets/ и указывали на соответствующий файл.

Настройте конфигурацию Rich Text Editor для использования стилей вашего шаблона.

На этом этапе у вас должна быть статическая страница, которая отображается так, как это предусмотрено шаблоном. Для других HTML-страниц вам нужно создать новый тип контента страницы и, подобно примеру с индексом, заменить его ftl-шаблон исходным кодом страницы. В противном случае обобщите тип контента с использованием правильного моделирования контента так, чтобы несколько страниц могли использовать один общий ftl-шаблон, отличаясь только компонентами, которые они содержат.

Моделирование контента

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

Хороший шаблон разделяет каждый значимый блок HTML-кода на компонент. Например, если вы реализуете раздел "Наша команда" с использованием повторяющейся группы или нескольких общих компонентов "Участники", это все равно должен быть отдельный тип, который содержит только информацию, относящуюся к разделу "Наша команде". Независимо от того, является ли это компонентом или страницей, в нем не должно быть информации из раздела "Продукт". Как только вы выделили HTML-блоки с определенным значением, начните перемещать их в соответствующий файл template.ftl своего типа. Затем замените любую информацию переменной из contentModel (и добавьте соответствующий элемент управления к типу контента). Если они не являются крайне простыми, большинство страниц будут содержать общие компоненты, даже если это просто компонент хедера и футера, предоставленный компонентом "Компоненты по умолчанию".

Рекомендуем придерживаться следующих практик:

1. Добавляйте префикс "component" или "page" к отображаемому лейблу типа контента.

2. Используйте drag&drop минимально. Поскольку текущая система не ограничивает типы компонентов, разрешенных в контейнере, избыточная гибкость может привести к запутанному пользовательскому опыту. Ограничьте функциональность перетаскивания до разделов, предотвращая случайное вложение и улучшая удобство использования.

3. Используйте элементы управления “Label” для дополнения формы типа контента дополнительной информацией, предлагая подсказки или рекомендации для продвинутых элементов управления.

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

5. Вы можете настроить папки для конкретных типов контента и обеспечить их соблюдение, используя <paths> в файле config.xml ваших типов. Используйте includes, когда вы хотите разрешить определенные пути, и используйте excludes для запрета путей, но не смешивайте их. Дополнительные примеры можно найти здесь.


      <paths>
    <includes> <pattern>REG_EXP_HERE</pattern> </includes>
    OR
    <excludes> <pattern>REG_EXP_HERE</pattern> </excludes>
</paths>

6. Убедитесь, что ваш шаблон поддерживает Experience Builder.

Компоненты по умолчанию

Тип контента "Компоненты по умолчанию" предоставляет унаследованные значения для всех дочерних и родственных элементов контента. Чтобы узнать больше о наследовании контента, читайте статью "Наследование контента".

Packaging

Предположим, что {CMS_HOME} указывает на каталог установки DC CMS, содержащий скрипты запуска, папки apache-tomcat/ и data/. Шаблоны располагаются в {CMS_HOME}/data/repos/global/templates. Каждая папка представляет собой шаблон. Чтобы создать собственный шаблон, продублируйте пустую папку и переименуйте ее в желаемое имя шаблона, например, "my_template".

Ваш проект хранится в {CMS_HOME}/data/repos/sites/имя-вашего-проекта. В этом пути вы найдете два репозитория: sandbox и published. Оба репозитория содержат проектные папки, но т.к. репозиторий sandbox отражает текущее состояние вашего проекта в предварительном просмотре CMS Studio, то именно из него вы скопируете файлы. Вам нужно переместить папки этого проекта во внешнюю папку с именем вашего шаблона, но избегайте копирования содержащейся там папки .git/, поскольку она не нужна для окончательного распространяемого пакета и может даже содержать конфиденциальную информацию.

Не объединяйте папки, перед копированием любой папки удалите существующую, чтобы переименованные или удаленные файлы не сохранялись.

Установка

Переместите вашу папку с шаблонами в {CMS_HOME}/data/repos/global/templates.
Проверьте, содержит ли ваша папка с шаблонами файл cms-plugin.yaml; если нет, вставьте его, продублировав файл cms-plugin.yaml из любого “коробочного” шаблона, например, из папки 4000_empty. Измените скопированный файл при необходимости, следуя рекомендациям, изложенным ниже.
Затем коммитните изменения в глобальный репозиторий ({CMS_HOME}/data/repos/global/), используя git. Теперь ваш шаблон будет отображаться при попытке создать новый проект.
- DC CMS использует стандартную версию Git, поэтому обычные команды Git работают так, как предполагается. Чтобы коммитнуть ваши изменения так, чтобы DС CMS мог их увидеть, перейдите в {CMS_HOME}/data/repos/global/templates и выполните команду git add для ваших измененных файлов, как показано ниже:
  - для каждого отдельного файла: git add <filename>
  - для всех файлов сразу: git add --all
- Затем коммитните их при помощи следующей команды: git commit -m "<the commit’s description>"
- Не нужно выполнять push, так как удаленный репозиторий не сконфигурирован. Вы также можете использовать любой клиент Git. Теперь ваш шаблон будет доступен при создании нового проекта.

Добавление изображения по умолчанию для шаблона

DC CMS использует предопределенный путь для поиска репрезентативного изображения для шаблонов. URL по умолчанию - ../.cms/screenshots/default.png.

На экране проектов, где перечислены ваши проекты, если у проекта есть изображение с сообщением "Изображение не установлено", это указывает на отсутствие изображения по умолчанию в папке .cms/screenshots/ внутри шаблона. Чтобы заменить изображение "Изображение не установлено" для вашего шаблона, просто добавьте файл изображения (например, default.png) в папку .cms/screenshots/ вашего шаблона.

Добавление дескриптора плагина

Каждый шаблон должен включать в себя файл описания плагина с именем cms-plugin.yaml. Этот файл YAML служит для детального описания шаблона, включая его название, описание, версию и другую важную информацию. Кроме того, файл описания плагина играет ключевую роль в передаче данных о параметрах, которые могут быть предоставлены шаблону при его создании.

Дескриптор шаблона DC CMS

Файл cms-plugin.yaml содержит важные сведения для использования в системе DC CMS. Этот файл дескриптора включает информацию о вашем расширении, такую как лицензия, поддерживаемые версии DC CMS, а также дополнительные конфигурации и метаданные.

Ниже приведен пример файла дескриптора для шаблона:


      # The version of the format for this file
descriptorVersion: 2
# Describe the template
plugin:
  type: template
  id: ru.dc.cms.digitalchief
  name: Digital Chief
  tags:
    - website
    - company
  version:
    major: 1
    minor: 0
    patch: 0
  description: |
    Digital Chief company showcase
  website:
    name: Digital Chief
    url: https://digitalchief.ru
  media:
    screenshots:
      - title: Home Page
        description: Screenshot of the home page
        url: /studio/static-assets/images/templates/digital_chief/screenshot_1.png
      - title: Experience Page
        description: Screenshot of the experience page
        url: /studio/static-assets/images/templates/digital_chief/screenshot_2.png
      - title: Cases Page
        description: Screenshot of the cases page
        url: /studio/static-assets/images/templates/digital_chief/screenshot_3.png
      - title: Experience Page 2
        description: Screenshot of the experience page 2
        url: /studio/static-assets/images/templates/digital_chief/screenshot_4.png
      - title: Advantages Page
        description: Screenshot of the advantages page
        url: /studio/static-assets/images/templates/digital_chief/screenshot_5.png
  developer:
    company:
      name: Digital Chief
      email: info@digitalchief.ru
      url: https://digitalchief.ru
  license:
    name: DC CMS
    url: https://cms.digitalchief.ru
  cmsVersions:
    - major: 1
      minor: 0
      patch: 0
  cmsEditions:
    - community
    - enterprise

Ниже отображены некоторые моменты, которые следует отметить в файле дескриптора:

Поле	Обязательное/необязательное	Описание
`descriptorVersion`	Обязательное	Версия формата для данного файла
`plugin.type`	Обязательное	Укажите значение `template`
`plugin.id`	Обязательное	Уникальный id, узнаваемый для людей, которые будут использовать шаблон
`plugin.name`	Обязательное	Имя, отображаемое в CMS Marketplace. Выберите уникальное имя для вашего шаблона. Вы можете проверить в CMS Marketplace, не существует ли уже выбранного вами имени. Также рекомендуется выбирать осмысленное или узнаваемое имя для вашего шаблона. Имя может состоять из нескольких слов.
`plugin.version`	Обязательное	Номер версии шаблона
`plugin.description`	Необязательное	Краткое описание шаблона, которое отображается под названием шаблона в CMS Marketplace
`plugin.website.url`	Необязательное	Может быть страницей для получения дополнительной информации о вашем шаблоне или для объявления обновлений, сообщений об ошибках и т.д. из вашего сообщества пользователей.
`plugin.media.url`	Необязательное	Местоположение для поиска репрезентативного изображения для шаблона. В случае отсутствия явного указания `plugin.media.url`, путь по умолчанию для поиска репрезентативного изображения для шаблона- `../.cms/screenshots/default.png`. Дополнительные сведения о добавлении репрезентативного изображения по умолчанию для вашего шаблона можно узнать здесь.
`plugin.license`	Необязательное	Лицензия, поддерживаемая шаблоном
`plugin.cmsVersions`	Обязательное	Содержит информацию о версии или версиях DC CMS, с которыми совместим данный плагин. Важно регулярно обновлять эту информацию.

Для изображений, используемых в файле cms-plugin.yaml, рекомендуется использовать изображения с соотношением сторон 4:3 (ширина к высоте), например, изображения размером 1200x800.

Передача параметров в шаблоны проекта

Может потребоваться передавать некоторые параметры в шаблон, а не оставлять их внутри шаблона, например, учетные данные AWS, учетные данные Box, учетные данные CommerceTools и т.д. DC CMS поддерживает передачу параметров шаблонам при их создании.

Для включения параметров, которые должны быть переданы шаблонам, вы можете обновить файл cms-plugin.yaml, добавив в него следующее:


      parameters:
 - label: My Parameter Label
   name: myParam
   type: string
   description: My parameter
   required: true

где:

label: метка, отображаемая для параметра в диалоговом окне создания проекта
name: имя параметра в нотации camelCase
type: тип параметра (возможные значения: STRING или PASSWORD. По умолчанию STRING)
description: Описание параметра
required: Указывает, является ли параметр обязательным. По умолчанию true.

Чтобы включить эти параметры в файлы конфигурации, используйте ${plugin:PARAM_NAME}, где PARAM_NAME - это имя параметра.

Редактирование шаблона как проекта vs Прямое редактирование

Поскольку структура шаблона во многом похожа на структуру проекта, вы можете изменить шаблон, отредактировав проект, созданный с помощью этого шаблона, а затем объединив изменения. Такой подход предоставляет несколько преимуществ:

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

Папка config/ включает в себя множество конфигурационных файлов с именем проекта. В шаблонах это обычно представлено с помощью {siteName}, поэтому вы должны либо редактировать конфигурационные файлы непосредственно в файловой системе шаблона, либо заменить название вашего проекта на {siteName}, если это необходимо. Для этого будет полезно иметь начальную версию шаблона (когда это была просто копия пустого шаблона перед созданием проекта) в репозитории Git.

Файлы permission-mappings-config.xml и site-config.xml используют {siteName}, который затем CMS Studio заменяет именем проекта при создании проекта. Примеры файлов сохраняют их {siteName}.

В permission-mappings-config.xml {siteName} используется внутри <site id="{siteName}">.

В site-config.xml {siteName} используется в <wem-project>{siteName}</wem-project> и <display-name>{siteName}</display-name>.

Каждый проект включает в себя два отдельных репозитория Git: sandbox и published. В любом из репозиториев находятся папки проекта, а также папка .git/. Необходимо переместить эти папки проекта обратно в папку шаблона, исключив папку .git/, так как она излишняя для конечного распределительного пакета и может содержать конфиденциальную информацию.

Помните, что при прямом редактировании в файловой системе необходимо коммитнуть ваши изменения.

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

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

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