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

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

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

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

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

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

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

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

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

• Официальный сайт шаблонизатора Pebble
  • Базовое использование шаблонизатора
  • Pebble 3.2.2 API
• Общий синтаксис шаблона jinja2 в Python
• Русскоязычная документация по Twig
  • Twig для разработчиков шаблонов

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

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

Предлагаемый формат входного JSON-документа:

[
  { "sideA": 5.0, "sideB": 4.0, "sideC":  3.0},
  { "sideA": 6.2, "sideB": 4.5, "sideC":  5.6}
]

После запуска приложения должен появится каталог с названием portal, содержащий следующие документы:

• Файл index.html, содержащий краткую справку о всём портале. На странице должно отображаться количество треугольников, о которых известно приложению.
• Файл triangles.html, содержащий список треугольников в краткой форме. В рамках списка достаточно вывести информацию по порядковому номеру, периметру и ссылки на документ с полной информацией о треугольнике.
• Каталог triangles, который будет содержать отдельные файлы для каждого треугольника.
• Файлы triangles/triangles-1.html, triangles/triangles-2.html и т.д. по одному на каждый известный треугольник. На каждом файле должна выводиться детальная информация по треугольнику: длины его сторон, периметр и площадь.
• Каталог css, содержащий CSS-файлы.
• Каталог js, содержащий JavaScript-файлы CSS-фреймворка.

На каждой странице должна находится общая навигационная панель, на которой должны находится ссылки к стартовому файлу, index.html, и к списку треугольников triangles.html.

Необходимо обеспечить оформление элементов с помощью CSS-фреймворка.

Приложение должно корректно работать, если каталог portal не существует в момент старта приложения.

Шаг № 1. Считывание данных из JSON-документа #

1. Добавьте в приложение Jackson-библиотеку для работы с Kotlin.
2. Сформируйте список треугольников в файле triangles.json.
3. Создайте класс Triangle, содержащий три вещественных поля sideA, sideB и sideC.
4. Считайте данные из JSON-документа.
5. Преобразуйте считанную строку к списку объектов-треугольников: List<Triangle>.

Шаг № 2. Создание целевого каталога #

Каталог portal должен создаваться приложением каждый раз при запуске

1. Необходимо создать каталог portal.
2. Необходимо скопировать каталог css, содержащий CSS-файлы фреймворка, в каталог portal.
3. Необходимо скопировать каталог js, содержащий JavaScript-файлы фреймворка, в каталог portal.

Шаг № 3. Добавление шаблонизатора Pebble #

Для подключения библиотеки Pebbletemplates необходимо в файле build.gradle в разделе dependencies добавить следующую строку:

implementation 'io.pebbletemplates:pebble:3.2.2'

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

Укажите, что в ресурсах проекта src/main/resources будут находится шаблоны HTML-документов согласно официальной документации.

Шаг № 4. Создание базовой раскладки #

В каталоге src/main/resources создайте файл Layout.peb. Данный файл должен содержать элементы, общие для всех страниц:

• Указание типа документа.
• Заголовок с подключением CSS-файлов CSS-фреймворка.
• Тело документа с подключением JS-файлов CSS-фреймворка.
• Общая навигационная панель.
• Место для добавления содержимого наследуемых шаблонов.

Шаг № 5. Стартовая страница #

В каталоге src/main/resources создайте файл Home.peb. Данный файл должен содержать в себе шаблон стартовой страницы. Данный шаблон должен быть унаследован от файла-раскладки Layout.peb.

Единственный динамический элемент — количество треугольников в системе. Далее будем считать, что данные передаются в переменной triangleCount.

Создайте объект-шаблонизатора io.pebbletemplates.pebble.PebbleEngine. Данный объект будет использоваться далее всеми создаваемыми функциями.

Создайте функцию по созданию стартовой страницы приложения. В качестве аргументов данная функция должна принимать:

• Объект PebbleEngine.
• Количество треугольников.

Внутри данной функции необходимо создать файл index.html в каталоге portal:

1. Сформировать словарь с данными для передачи внутрь шаблона. Единственной парой будет строка triangleCount, которой соответствует переданное в качестве аргумента число.
2. Создать объект-шаблон. Для этих целей используйте метод getTemplate объекта PebbleEngine.
3. Открыть файл index.html на запись в него данных.
4. Записать результат применения шаблона к сформированным данным. Для применения используйте функцию evaluate.
5. Закрыть файл index.html.
6. Вызвать данную функцию внутри функции main, передав ей нужные аргументы.

Шаг № 6. Страница со списком треугольников #

В каталоге src/main/resources создайте файл TrianglesList.peb. Данный файл должен содержать в себе шаблон страницы со списком треугольников. Данный шаблон должен быть унаследован от файла-раскладки Layout.peb.

Единственный динамический элемент шаблона — список периметров треугольников. Для прохода по списку треугольников используйте тег for. Обратите внимание, что внутри тела данного тега можно обратиться к переменной loop.index, которая будет содержать порядковый номер элемента.

Используйте номер элемента в списке, чтобы сформировать путь к файлу с детальным описанием треугольника: portal/triangles/triangle-{{loop.index}}.html.

Создайте функцию по созданию файла со списком треугольников. В качестве аргументов данная функция должна принимать список треугольников и объект PebbleEngine.

1. Создайте список сторон треугольников. Для этого удобно воспользоваться функцией map над списком треугольников. Логику по вычислению периметра логично разместить внутри класса Triangle.
2. Сформируйте данные для передачи внутрь шаблона.
3. Сформируйте строку с HTML-документом списка треугольников.

Убедитесь, что пользователь может корректно переходить между стартовым файлом и списком треугольников.

Шаг № 7. Страницы с детальной информацией о треугольнике #

В каталоге src/main/resources создайте файл Triangle.peb. Данный файл должен содержать в себе шаблон страницы с детальной информацией о треугольнике. Данный шаблон должен быть унаследован от файла-раскладки Layout.peb.

Шаблон принимает в качестве аргумента два объекта: объект типа Triangle и порядковый номер треугольника. Внутри шаблона используйте методы класса для получения информации по всем параметрам треугольника: длины сторон, периметр и площадь.

Создайте функцию по созданию страниц с детальной информацией о треугольнике. Данная функция должна принимать в качестве аргументов список треугольников и объект PebbleEngine. Внутри данной функции:

1. Создайте объект-шаблон для формирования содержимого HTML-документа.
2. Пройдите в цикле по переданному массиву треугольников. Далее для каждого элемента в массиве выполните следующие шаги.
3. Сформируйте данные для передачи в шаблон: треугольник и порядковый номер.
4. Запишите результат применения шаблона к данным приложения.

В результате данной операции все файлы, написанные в задании, должны успешно создаваться.

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