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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

  1. Расположите статические файлы фреймворка в каталоге src/main/resources/ru/yarsu/public.
  2. В файле маршрутизации добавьте вызов функции 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. Настройка шаблонизатора и базовое его использование #

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

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

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

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

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

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

© A. M. Васильев, 2023, CC BY-SA 4.0, andrey@crafted.su