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 } />

Copy-icon

где:

  • 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” />

Copy-icon

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

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

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

Copy-icon

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

Хотя доступ ко всем сервисам 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"
}

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

<!-- 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)}">

Copy-icon

Если есть множество замыканий или операций, которые должны быть повторно использованы в нескольких шаблонах, рекомендуется создать вместо этого класс на 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
  }

}

Copy-icon
  • Файл контекста приложения сайта 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>

Copy-icon
  • Файл конфигурации сайта 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>

Copy-icon
  • Шаблон:

<!-- Now the bean can be use just like DC CMS built-in services -->

<i class="fa ${navIconService.getNavIcon(navItem)}">

Copy-icon

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

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

API