FreeMarker API (создание шаблонов)

В этой статье вы узнаете об использовании Freemarker-шаблонов страниц и компонентов в DC CMS. Здесь же приводится список полезных переменных Freemarker.

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

Документация по Freemarker доступна на http://freemarker.org.

Основной переменной, доступной в шаблонах Freemarker для страниц и компонентов, является contentModel, которая предоставляет доступ к самому контенту. Например, если вы определили на странице переменную с именем title, вы можете получить её значение, используя ${contentModel.title}.

CMS Engine также заполняет шаблоны другими полезными переменными, описанными ниже.

Название	Описание	Тип
siteItemService	Разрешает доступ к контенту сайта	SiteItemService
urlTransformationService	Сервис для преобразования URL-адресов, например, для преобразования URL-адреса контента страницы в веб-URL или URL-адрес для рендеринга	UrlTransformationService
applicationContext	Предоставляет доступ к Spring-бинам (bean) CMS Engine и бинам сайта, определенным в файле `config/spring/application-context.xml`	ApplicationContextAccessor
globalProperties	Предоставляет доступ к свойствам глобальной конфигурации, определенным в `server-config.properties`	PropertySourcesPropertyResolver
navBreadcrumbBuilder	Вспомогательный класс, который возвращает список компонентов пути в URL для создания навигационных хлебных крошек (бредкрамбов)	BreadcrumbBuilder
navTreeBuilder	Вспомогательный класс, который создает навигационные деревья для облегчения рендеринга	NavTreeBuilder
tenantsResolver	Может использоваться для получения профилей арендаторов, связанных с текущим сайтом	TenantsResolver
modePreview	Флаг, указывающий, что CMS Engine выполняется в режиме предварительного просмотра (также значение свойства `cms.engine.preview`)	Boolean
cmsEnv	Указывает окружение используя значение свойства `cms.engine.environment`	String
siteConfig	Текущая конфигурация сайта, загруженная из `/config/site.xml`	См. `XMLConfiguration` в разделе `org.apache.commons.configuration2` в Apache Commons apidocs.
siteContext	Текущий SiteContext	ServletContextHashModel
request	Текущий запрос	HttpRequestHashModel
requestParameters	Значения параметров для текущего запроса	HttpRequestParametersHashModel
cookies	Значения файлов cookie для текущего запроса	См. `Map` в пакете `java.util` модуля `java.base` в документации по Java.
session	Текущая сессия	HttpSessionHashModel
locale	Текущий язык для текущего пользователя	См. `Locale` в пакете `java.util` модуля `java.base` в документации по Java.
authToken	Токен текущей аутентификации (если пользователь вошел в систему), созданная Spring Security	См. раздел `Authentication` в разделе `org.springframework.security.core` в Spring Security apidocs.

Следующие переменные предоставляются для обеспечения обратной совместимости при использовании CMS Profile и, по возможности, должны быть заменены на authToken:

Название	Описание	Тип
authentication	Текущая аутентификация (если пользователь вошел в систему), созданная CMS Security Provider	Authentication
profile	Текущий профиль (если пользователь вошел в систему), созданная CMS Security Provider	Profile

Переменные profile и authentication в большинстве случаев будут иметь значение null и больше не должны использоваться.

Следующие переменные ограничены по умолчанию, их использование описано в статье “Конфигурация CMS Engine”:

Название	Описание	Тип
application	Контекст сервлета	ServletContextHashModel
siteContext	Текущий SiteContext	SiteContext

Рендеринг компонентов

CMS Engine предоставляет макрос renderComponent, который можно использовать для отображения компонентов в любом шаблоне:


      <!-- Render a component by referencing the path -->
<@renderComponent componentPath='/site/components/headers/header.xml' />
<!-- Render a component by referencing a shared component from the current item -->
<@renderComponent component=contentModel.mySharedComponent_o.item  />
<!-- Render a component by referencing an embedded component from the current item -->
<@renderComponent component=contentModel.myEmbeddedComponent_o.item />
<!-- Render an embedded component from another component instead of the current item -->
<#assign sharedItem = siteItemService.getSiteItem('/site/components/global.xml')/>
<@renderComponent parent=sharedItem component=sharedItem.myEmbeddedComponent_o.item />
<!-- Render a component passing additional variables -->
<!-- Inside the component's template 'theme' will be available as a global variable -->
<@renderComponent component=contentModel.myComponent.item additionalModel={ 'theme': contentModel.theme_s } />

где:

componentPath: путь, указывающий на общий компонент на веб-сайте
component: узел XML, полученный из поля выбора узла, поддерживающий как общие, так и встроенные компоненты
parent: SiteItem, используемый в качестве родительского элемента для встроенных компонентов (по умолчанию используется текущий элемент, который отображается)
additionalModel: объект Freemarker, содержащий пары ключ-значение, которые могут использоваться как глобальные переменные в шаблоне компонента

Рендеринг навигации

CMS Engine предоставляет возможность автоматического рендеринга навигации при помощи макроса navigation. Подробнее о макросе можно узнать здесь.

Рендеринг хлебных крошек (breadcrumbs)

DC CMS поддерживает макрос renderBreadcrumb для простого создания динамического списка со всеми родительскими страницами определенного URL. Подробнее о макросе можно узнать здесь.

Запуск скриптов/контроллеров

CMS Engine позволяет выполнять скрипты/контроллеры в шаблонах Freemarker с использованием тега @controller. Этот тег требует единственного параметра, path, который представляет собой местоположение скрипта/контроллера на сайте:


      <@controller path=“/scripts/plugins/MyPlugin/1/get-tweets.groovy” />
<@controller path=“/scripts/plugins/MyPlugin/1/get-fbs.groovy” />

Экранирование HTML и скриптов

Чтобы экранировать HTML и скрипты и предотвратить их выполнение в вашем шаблоне, просто “оберните” HTML/скрипт, который нужно экранировать, директивой outputformat Freemarker, установленной на html:


      <#outputformat "HTML">
...
</#outputformat>

Упрощение шаблонов

Хотя доступ ко всем сервисам CMS Engine непосредственно из шаблонов Freemarker является возможным, рекомендуется избегать включения логики и сложных операций в сами шаблоны. Это упростит отладку и обслуживание. Одним из простых способов извлечения логики из шаблонов является использование замыканий Groovy (Groovy closures):

Скрипт страницы или компонента:


      // Add a closure to the templateModel map, in this case it will find if a page has a custom
// nav icon defined in the xml descriptor.
templateModel.getNavIcon = { item ->
  def storeUrl = urlTransformationService.transform("renderUrlToStoreUrl", item.url)
  def siteItem = siteItemService.getSiteItem(storeUrl)
  if(siteItem) {
    def navIcon = siteItem.navIcon?.text
    if(navIcon) {
      return navIcon
    }
  }
  return "fa-file-o"
}

Шаблон страницы или компонента:


      <!-- Now the closure is available to use in the template, you only have to use the same name
     from the script and use the `call` method. -->
<i class="fa ${getNavIcon.call(navItem)}">

Если есть множество замыканий или операций, которые должны быть повторно использованы в нескольких шаблонах, рекомендуется создать вместо этого класс на Groovy:

Класс кастомного сервиса:


      // Define a class with all the logic
package org.site.service
class NavIconService {
  def urlTransformationService
  def siteItemService
  def defaultIcon
  def getNavItem(item) {
    ...
    return this.defaultIcon
  }
}

Файл контекста приложения сайта CMS Engine - application-context.xml:


      <!-- Add a bean definition using the new class -->
<bean id="navIconService" class="org.site.service.NavIconService">
  <property name="urlTransformationService" ref="cms.urlTransformationService"/>
  <property name="siteItemService" ref="cms.siteItemService"/>
  <property name="defaultIcon" value="${nav.defaultIcon}"/>
</bean>

Файл конфигурации сайта CMS Engine - site-config.xml:


      <!-- If needed the bean can use external configuration for easy management -->
<?xml version="1.0" encoding="UTF-8"?>
<site>
  ...
  <nav>
    <defaultIcon>fa-file-o</defaultIcon>
  </nav>
  ...
</site>

Шаблон:


      <!-- Now the bean can be use just like DC CMS built-in services -->
<i class="fa ${navIconService.getNavIcon(navItem)}">

Дополнительные сведения о файлах конфигурации сайта CMS Engine см. здесь.

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

API