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

Дело в том, что функция theme_var() сначала проверяет установлена ли запрашиваемая переменная в заголовке страницы page.header (для проверки используется PHP функция isset). Если переменная не установлена, происходит обращение к переменной из настроек темы оформления.

{% set grid_size = theme_var('grid-size') %}

В приведённом коде переменной grid_size будет присвоено значение page.header['grid-size], если оно установлено в заголовке страницы, или config.theme['grid-size']. Если переменная config.theme['grid-size] не определена, функция возвращает значение по умолчанию, равное null. Собственное значение по умолчанию устанавливается передачей функции второго параметра.

{% set grid_size = theme_var('grid-size', 'grid-md') %}

Поэтому, главное, что следует иметь в виду при использовании функции theme_var: результат вызова функции theme_var('var_name') может отличаться от прямого обращения к переменной config.theme.var_name.

Вместе с этим функция theme_var делает проще использование переназначенных переменных темы оформления на уровне страницы. Но и здесь нельзя оставлять без внимания следующий нюанс: для страницы функция возвращает значение переменной, установленной на уровне page.header, это значит, что при запросе значения переменной theme_var('title), будет возвращено значение стандартной переменной page.header.title, содержащей заголок страницы и не относящейся к переменным темы оформления. При этом переменная config.theme.title, непосредственно относящаяся к теме оформления, будет проигнорирована.

Во избежание описанного конфликта при использовании функции theme_var() не следует использовать в настройках темы оформления переменные с именами, занятыми стандартными переменными страниц Grav.

Теперь вы точно знаете, как правильно использовать функцию Twig theme_var() в шаблонах оформления Grav. Всё рассмотренное актуально для текущей на момент публикации версии системы управления контентом Grav 1.5.3.