Использование шаблонизатора Pebble #

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

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

Шаблоны обычно представляют собой обычные файлы на жёстком диске, содержащие текст на целевом языке (в нашем случае на HTML), а также управляющие конструкции на языке шаблона.

Шаблонизаторы предоставляют средства для обработки поступающих данных:

Вставка данных в шаблон.
Обход списков.
Выполнение условной логики в зависимости от данных.
Фильтрация данных.

Шаблоны также могут быть разделены между несколькими файлами и иметь сложную структуру.

В рамках данного курса будет рассмотрен шаблонизатор Pebble, т.к. он реализует синтаксис, который используется в популярных шаблонизаторах для других платформ Twig(PHP) и Jinja(Python). Вы можете использовать русскоязычные ресурсы по Twig и Jinja для ознакомления с базовым синтаксисом шаблонизатора Pebble.

Документация #

Постановка задачи #

Добавьте в приложение по работе со списком треугольников отображение HTML-документов с помощью шаблонизатора Pebble. Данная подсистема должна заменить классы-виды, которые использовались для формирования HTML-документов.

Требования к реализации #

Для оформления страниц сайта используйте CSS-фреймворк.
Для разработки страниц с динамическим содержимым используйте шаблонизатор Pebble.
В рамках данной работы «динамическое» содержимое будет зафиксировано в исходном коде приложения.\
Исходный код приложения должен

Задача № 1. Настройка раздачи статического содержимого #

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

Расположите статические файлы фреймворка в каталоге src/main/resources/ru/yarsu/public.
В файле маршрутизации добавьте вызов функции static последним элементом. В качестве аргумента передайте данной функции загрузчик данных из ресурсов приложения Classpath. В качестве аргумента передайте ему путь к публичному каталогу /ru/yarsu/public.

Подключение шаблонизатора к проекту #

При создании приложения с использованием мастера или при получении шаблона приложения с данного сайта к проекту уже был подключена библиотека Pebble.

Для подключения библиотеки необходимо поправить конфигурацию системы сборки Gradle, файл build.gradle. В рамках секции dependencies необходимо добавить поддержку шаблонизатора Pebble для библиотеки http4k. Эта библиотека транзитивно зависит от библиотеки Pebble.

dependencies {
    implementation("org.http4k:http4k-template-pebble:${http4kVersion}")
}

В файле gradle.properties необходимо проверить, что переменная http4kVersion задана.

Настройка среды разработки IDEA #

Для удобного написания Pebble файлов внутри среды разработки IDEA было разработано расширение. Оно бесплатное и рекомендуется для установки. Страница дополнения: Pebble.

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

Задача № 2. Настройка шаблонизатора и базовое его использование #

Создайте файл MainPageVM.peb в каталоге src/main/resources/ru/yarsu/web/models.
Внутри файла разместите HTML-документ со статическим содержимым.
- В коде HTML-документа должно присутствовать подключение CSS и JS-файлов CSS-фреймворка.
- На данной странице должно находится описание системы.
- На странице должна быть навигационная панель, включающая ссылки на главную страницу и страницу со списком треугольников.
Создайте класс-модель, описывающий данные, которые передаются в шаблон для отображения. В данном случае никаких данных не передаётся, поэтому создайте класс ru.yarsu.web.models.MainPageVM без полей. Унаследуйте этот класс от интерфейса org.http4k.template.ViewModel.
В стартовой функции приложения создайте объект класса org.http4k.template.PebbleTemplates. Настройте его на горячую перезагрузку шаблонов приложения из каталога src/main/resources/. дальнейшем рассматривайте этот объект как объект суперкласса org.http4k.template.TemplateRenderer, это позволит в будущем перейти на другие шаблонизаторы, если потребуется.
Создайте обработчик HTTP-запроса для стартовой страницы приложения. Вместо перенаправления на страницу со списком треугольников необходимо вывести созданную на предыдущих шагах страницу.
1. Назовите класс ru.yarsu.web.handlers.ShowAppInfoHandler.
2. В качестве параметра конструктора укажите объект класса TemplateRenderer. Он будет использован для формирования тела ответа HTTP-запроса.
3. В рамках обработки HTTP-запроса создайте объект класса MainPageVM.
4. С помощью созданного объекта и объекта класса TemplateRenderer создайте строку с HTML-документом.
5. Верните ответ, в теле которого передаётся созданный документ.
Модифицируйте функцию-маршрутизатор следующим образом.
1. Добавьте ей аргумент template типа TemplateRenderer.
2. Вместо обработчика по перенаправлению запроса используйте обработчик ShowAppInfoHandler. Передайте в конструктор обработчика ссылку на объект TemplateRenderer.
В рамках стартовой функции приложения передайте ссылку на объект TemplateRenderer при вызове функции по созданию маршрутизатора, router.

Задача № 3. Использование базовой раскладки #

Создайте базовый файл раскладки.
1. Скопируйте файл MainPageVM.peb в файл layout.peb.
2. Вместо информации о приложении определите блок с наименованием content.
3. Вместо названия шаблона определите блок с наименованием title.
4. В качестве базового содержимого блока title используйте строку Список треугольников.
Используйте данную раскладку в файле MainPageVM.peb
1. Подключите базовую раскладку с помощью ключевого слова extend.
2. В качестве пути используйте ./layout.peb. В противном случае файл раскладки не будет найден.
3. Оформите блок title. Его содержимым должна быть строка — стартовая страница.
4. Оформите блок content. Его содержимым должно быть описание приложение, что составляет ядро данной страницы.
Проверьте, что при открытии пути по умолчанию продолжает корректно показываться страница.

Задача № 4. Создание шаблонов для страниц списка треугольников и конкретного треугольника #

Для каждого обработчика HTTP-запросов выполните следующее:

Определите класс-модели, содержащий все данные для отображения.
Создайте Pebble-шаблон.
1. Должен использовать базовую раскладку layout.peb.
2. Должен показывать содержимое модели внутри блока content.
Добавьте ссылку на объект TemplateRenderer в качестве аргумента конструктора класса HTTP-обработчика.
При выполнении обработки создайте объект нужного класса-модели.
С помощью шаблонизатора и класса-модели создайте тело для ответа.
Удалите ненужный класс из пакета ru.yarsu.web.view.