Усовершенствованные рукоятки
Извлечение схем из ваших шаблонов Handlebar, даже если задействованы пользовательские помощники
Barhandles — это доказательство концепции, целью которой является извлечение схемы документа из ваших документов Handlebars. Действительно полезно, если вы занимаетесь созданием шаблонов документов и хотите проверить, действительно ли то, что вы передаете, является тем, что ему нужно.
Я уже писал о Barhandles раньше, но просто напомню, как вы его используете:
… и тогда это то, что вы получаете:
Схема, которую он создает, на самом деле не является стандартным языком схемы, но с помощью простого преобразования вы можете можно превратить ее в схему JSON или JOI или любой другой вариант языка схемы, который вам нравится, что в вышеупомянутом документе объясняет, как сделать.
Все хорошо, верно?
Ну не совсем. Barhandles хорошо работает с любыми стандартными помощниками Handlebars. Однако вы вряд ли когда-либо будете использовать Handlebars, не зарегистрировав кучу хелперов самостоятельно. И, к сожалению, у каждого помощника могут быть свои ожидания относительно того, чего ожидать от передачи данных, в зависимости от его конфигурации.
Возьмем {{#with}} в качестве примера. Этот помощник встроен в Handlebars по умолчанию, и он очень полезен, если у вас есть блок контента, в котором вы постоянно ссылаетесь на данные, вложенные в структуру данных, которую вы передаете.
С {{#with}} кусок содержимого Handlebars выглядит следующим образом:
… можно переписать как:
… что очень полезно.
Однако, если бы Barhandles обрабатывал {{#with}} как любую другую директиву, то создаваемая ею схема ожидала бы присутствия этих свойств при передаче данных:
owner.addressstreetcityzipcode
… что явно не соответствует ожидаемому шаблону.
По этой причине Barhandles обращается с {{#with}} немного иначе, чем с другими помощниками. В случае директивы {{#with}} она фактически меняет контекст любых встроенных ссылок на то, что передается в качестве первого аргумента {{#with}}. В результате он правильно находит, что действительно нужно передать:
owner.addressowner.address.streetowner.address.cityowner.address.zipcode
Таким образом, хелпер {{#with}} обрабатывается иначе, чем большинство других хелперов в Handlebars. Однако ваши собственные помощники могут иметь аналогичные требования к обработке. Вот почему Barhandles позволяет вам настроить, как вы хотите, чтобы ваши собственные помощники обращались.
Но как?
Секрет указания того, как вы хотите, чтобы Barhandles интерпретировал ваши собственные помощники, заключается в передаче некоторых параметров конфигурации в качестве второго аргумента.
Если у вас есть хелпер, для которого вы хотите настроить, как Barhandles его обрабатывает, вы добавляете новую запись в объект параметров с именем хелпера в качестве ключа и объектом с настройками конфигурации в качестве значения.
Теперь, если у вас есть похожий на {{#with}} помощник по имени withAlike, то именно так вы сообщаете Barhandles о его существовании, и таким же образом вы убеждаетесь, что с ним обращаются аналогичным образом.
Параметры конфигурации помощника
В предыдущем примере я показал один параметр конфигурации, который можно связать с директивой, но их больше. В настоящее время существует три разных параметра, влияющих на то, как Barhandles обрабатывает встречающуюся директиву:
Изменение контекста
Если у вас есть помощник, который изменяет контекст всех ссылок, вложенных внутрь, вы используете contextParam, чтобы указать, какой из параметров этого помощника фактически определяет этот контекст. Это может иметь значение только в {{#with}} похожих ситуациях, но если вы когда-нибудь столкнетесь с этим, то теперь, по крайней мере, вы знаете, как сообщить об этом Barhandles.
Предположим, у вас есть помощник {{#propertyList {type} {object}}}, который генерирует шаблонный HTML-код для списка свойств, а затем устанавливает контекст того, что находится внутри, на то, что у вас есть в качестве второго аргумента. В этом случае вам нужно будет настроить Barhandles, передав:
Установка аргументов как необязательных
По умолчанию Barhandles предполагает, что если вы включаете ссылки на переменные в свою структуру данных, эти ссылки должны присутствовать в структуре данных, которую вы передаете. Однако в некоторых обстоятельствах это может быть неразумным значением по умолчанию.
Предположим, что у вас есть директива с именем join, которая объединяет некоторые переменные в удобочитаемом виде:
Если переменные установлены на «Боб», «Алиса», «Джо», то хелпер будет отображать Bob, Alice and Joe. Однако, если третье имя не будет задано в переданных данных, тогда этот конкретный помощник будет согласен с этим и просто отобразит Bob and Alice.
Если бы у вас не было способа определить, как Barhandles обрабатывает эти ситуации, тогда предполагалась бы структура данных, которая предполагает, что все эти свойства являются обязательными. Однако на самом деле мы ожидаем, что ни одно из этих свойств не потребуется.
Чтобы Barhandles знали об этом, вы должны передать следующую конфигурацию:
Это говорит Barhandles рассматривать любые ссылки внутри этой директивы как необязательные.
трансмогрифицировать
Название уже выдает это: это самый сложный момент, и у вас, вероятно, никогда не будет причин его использовать. У меня никогда не было причин использовать его для моих пользовательских помощников, но он используется для вспомогательных регистров Handlebars по умолчанию, так что вы должны знать об этом, и это может быть полезным.
Типичный пример — {{#each}}. С помощью этой директивы вы перебираете элементы коллекции. Без опции transfogrify Barhandles выглядел бы следующим образом:
… и предположим, что шаблону требуется такой объект:
… что явно не то, что шаблон ожидает на самом деле.
Преобразование берет путь, указанный параметрами, которые устанавливают контекст (помните, вы можете сообщить об этом Barhandles с помощью опции contextParam) и переписывает этот путь во что-то, что имеет смысл для вывода Barhandles.
В этом случае, когда мы просматриваем массив, мы хотим, чтобы Barhandles увидел, что здесь действительно требуется, чтобы children был массивом. Мы делаем это, передавая transmogrifyoption, указывающий на функцию, которая переписывает путь, чтобы он имел смысл для Barhandles:
Резюме
Иногда Barhandles не может понять, как он должен относиться к пользовательским помощникам, которые вы регистрируете самостоятельно. Однако есть возможность передать некоторые параметры конфигурации, чтобы повлиять на поведение Barhandles, если он встретит эти пользовательские вспомогательные ссылки. Варианты конфигурации ограничены, и было бы действительно полезно рассмотреть более надежное решение для настройки в будущем, но это остается читателю в качестве упражнения.
Первоначально опубликовано на gist.github.com.
