Интеграция с @yamato-daiwa/es-extensions (YDEE)

После включения файла Functionality.pug (находится в корневой директории npm-пакета @yamato-daiwa/frontend) становятся доступна вся функциональность библиотеки «@yamato-daiwa/es-extensions» (сокращённо: «YDEE») версии 1.7 кроме той, которая прекращает своё существование после транспайлинга TypeScript в JavaScript (интерфейсы, псевдонимы типов и т.д.).

include ../../node_modules/@yamato-daiwa/frontend/Functionality.pug

В случае Вашего pug-файла относительный путь к директории node_modules может быть другим.

Минимальная требуемая версия препроцессора Pug: 3.0.

При использовании шаблонов страниц файл Functionality.pug уже подключён; повторное его подключение приведёт к ошибке.

Основной случай, когда такая функциональность востребована — простейший мокинг данных на стадии вёрстки (статического превью). Вот как, например, можно быстро написать разметку 16 карточек товаров с пускай и бессмысленными, но данными:

ul.ProductsList

  each index in Array.from(new Array(16).keys())

    li.ProductCard

      - const productTitle = getRandomString({ minimalCharactersCount: 6, minimalCharactersCount: 32 });

      span.ProductCard-Title= productTitle

      img.ProductCard-Photo(
        src=getRandomObjectPropertyValue(DummyImagesURIs)
        alt=`Фотография товар «${ productTitle }»`
      )

      span.ProductCard-PriceLabel
        span.ProductCard-PriceLabel-Amount= getRandomInteger({ minimalValue: 100, maximalValue: 100000 })
        span.ProductCard-PriceLabel-Currency ₽

Здесь были использованы функции getRandomString, getRandomObjectPropertyValue и getRandomInteger из YDEE, при этом константа DummyImagesURIs типа «ассоциативный массив» является частью YDF. В результате, для каждой карточки будет сгенерирован HTML-код, подобный приведённому ниже (значение аттрибута src у тэга img частично опущено, чтобы не занимать место):

<li class="ProductCard">

  <span class="ProductCard-Title">5XDoHI8G9qbjrvfFAq0ZrjX2KP4qcFsHzDXS9IW6nJjOnvB0FQgulYL</span>

  <img
    class="ProductCard-Photo"
    src="data:image/svg+xml;base64,PHN2ZyB4b(...)"
    alt="Фотография товара «5XDoHI8G9qbjrvfFAq0ZrjX2KP4qcFsHzDXS9IW6nJjOnvB0FQgulYL»"
  >

  <span class="ProductCard-PriceLabel">
    <span class="ProductCard-PriceLabel-Amount">8301</span>
    <span class="ProductCard-PriceLabel-Currency">₽</span>
  </span>

</li>

Однако, даже если Вы не планируете такое использование YDEE, она всё равно необходима для нормальной работы функциональности YDF, связанной с разметкой, например для валидации параметров Pug-примесей:

include ../../node_modules/@yamato-daiwa/frontend/Components.pug

+Badge--YDF({ value: [] })

Неверное использование компонента Badge (реализован с помощью Pug-примеси): у свойства value единственного параметра указано значение неверного типа, кроме того, отсутствует обязательное свойство. Однако поскольку с использованием YDEE реализована валидация свойств примеси, то преобразование Pug в HTML завершится с ошибкой, при этом в консоли отобразится информация, благодаря которой при владении базовым английским можно будет самостоятельно исправить ошибки без обращения к документации.

Ответы на часто задаваемые вопросы и критику

Критика

То есть в Pug-коде содержится почти весь код библиотеки YDEE? Это не перебор?

Ответ

Любая функциональность добавляется в YD-библиотеки только после того, как в ней появляется практическая необходимость. В отношении интеграции с YDEE практическая необходимость была и есть — примеры прямого и опосредованного использования были приведены выше. Если в какой-то функциональности необходимость со временем исчезает, то мы её заменяем на новую или в редких случаях удаляем (хотя YDF — библиотека, опубликованная относительно недавно, она и её прототипы проходили альфа-тестирование несколько лет). Однако потребность в интеграции с YDEE устойчивая, а потому её удаление не планируется.

Вопрос

Не снизит ли наличие YDEE-кода скорость преобразования Pug-кода в HTML при использовании с MVC-фреймворками на серверной стороне?

Ответ

Снизит, и значительно (где-то на 2-3 секунды, но для формирования ответа сервером это считается неприемлемым).

Интеграция с YDEE предназначена в основном для стадии вёрстки (статического превью ), однако при условии, что преобразование из Pug в HTML осуществляется заранее до публикации каждой версии сайта или приложения , интеграцию с YDEE можно использовать и на других этапах разработки.

Вероятно, Вы задаёте этот вопрос потому, что хотите знать, что делать в случаях, когда функциональность YDEE нужна и на стадии создания интерактивного сайта или приложения с рендерингом на серверной стороне и использованием паттерна MVC, например для того, чтобы работала валидация параметров Pug-примесей (в частности примесей GUI компонентов ) или чтобы по-прежнему можно было пользоваться шаблонами страниц , но без потерь в производительности. По этому вопросу было подготовлено отдельное руководство , но если кратко, то необходимо организовать двухэтапное преобразование исходного Pug-кода в выходной HTML-код. На первом этапе формируются промежуточные файлы-шаблоны, каждый из которых неизменен вне зависимости от динамических данных (таких данные из базы данных). При этом, эти файлы-шаблоны формируются только один раз перед публикацией (деплоем) каждой версии сайта или приложения. На втором этапе подставляются динамические данные в промежуточный шаблон, в результате чего формируется окончательный HTML-код.