Как передать Дополнительные параметры в шаблон из админки Joomla 3

В этой статье рассмотрим, как при создании шаблона сайта Joomla 3 настроить дополнительные поля, значение которых можно редактировать в админке. Для этого потребуется внести дополнительные данные в файл конфигурации шаблона templateDetails.xml. Сразу рассмотрим, как это сделать в режиме поддержки мультиязычности админки и то, как подключить данные дополнительных полей шаблона, заданных в админке в сам шаблон сайта.

Настройка передачи Дополнительных полей шаблона в файле конфигурации шаблона templateDetails.xml

Группа полей <config> конфига templateDetails.xml

Как вскользь упоминалось в статье по конфиг шаблона templateDetails.xml, есть группа параметров <config>, в которой можно задать параметры, которые попадут на вкладку «Дополнительные параметры» в настройках шаблона в Менеджере шаблонов Joomla. До тех пор, пока в конфиге не заданы эти параметры, вкладка «Дополнительные параметры» просто не будет отображаться.

Для того, чтобы задать дополнительный параметр, нужно воспользоваться рядом блоков, которые рассмотрим на примере одного поля, задающего цвет фона страницы:

<config>
	<fields name="params">
		<fieldset name="advanced">
			<field 
				name="templateBackgroundColor" 
				type="color" 
				label="TPL_REZON_BACKGROUND_COLOR_LABEL"
				description="TPL_REZON_BACKGROUND_COLOR_DESC" 
				class="" 
				default="#F4F6F7"
			/>
		</fieldset>
	</fields>
</config>

Итак,

1. в контейнер <config> нужно вложить контейнер <fields> с параметром name="params".
2. в этот контейнер <fields name="params"> нужно вложить контейнер <fieldset> с параметром name="advanced".
3. в образовавшийся контейнер <fieldset name="advanced"> будем вкладывать поля с помощью контейнеров <field /> с параметрами, которые будут служить указанием того, что это за поле и как его обрабатывать.

Параметры поля <field /> для формирования дополнительных настраиваемых полей в шаблоне сайта Joomla

Дополнительные поля — это начиная с версии 3.8 Joomla, — стандартное расширение Joomla, поддерживаемое ядром. Поэтому набор полей стандартизирован, как и их параметры. Параметры поля, которые нужно описать в конфиге следующие:

• Параметр «name» задаёт имя, по которому можно обратиться для того, чтобы задать, прочитать и изменить значение поля.
• Параметр «type» задаёт тип поля. Все возможные типы настраиваемых полей Joomla имеет смысл рассмотреть в отдельной статье. Пока просто перечислю их: календарь, чекбокс, цвет, редактор, e-mail, галерея, изображение, целое число, список, медиа, радио, SQL, телефон, текст, текстовая область, часовой пояс, URL, пользователь, группа пользователей.
• Параметр «label» задаёт подпись поля, отображаемое в админке (можно пользоваться языковыми константами).
• Параметр «description» задаёт расширенное описание поля, которое высвечивается в виде подсказки в админке (можно пользоваться языковыми константами).
• Параметр «class» позволяет задать css-класс для вывода поля в админке
• Параметр «default» задаёт значение по умолчанию, которое будет использовано, если его не менять в админке.
  • другие параметры, которые пока не рассматриваю.

Для работы с настраиваемыми полями шаблона пока достаточно знать эти параметры для создания полноценного дополнительного функционала управления шаблоном в админке.

Поддержка мультиязычности при создании дополнительных полей шаблона в админке Joomla

В примере выше видно, что при задании значений параметров label и description поля использованы языковые константы, которые нужно задать в языковых файлах шаблона ru-RU.tpl_rezon.ini и en-GB.tpl_rezon.ini, для того, чтобы эти константы были выведены в виде текста, а не в виде названия константы.

Пример:

TPL_REZON_BACKGROUND_COLOR_LABEL="Цвет фона сайта"
TPL_REZON_BACKGROUND_COLOR_DESC="Для того, чтобы поменять цвет фона сайта, нужно выбрать цвет и сохранить изменения в шаблоне."

Важное замечание

При добавлении языковых констант в шаблон сайта, Joomla нужно их прочитать и перенести в языковые файлы шаблона, которые находятся тут:

language/ru-RU/ru-RU.tpl_rezon.ini
language/en-GB/en-GB.tpl_rezon.ini

А это происходит только при обновлении шаблона с сервера репозитория или при переустановке шаблона. Поэтому, для того, чтобы языковые константы обновились, нужно обновить или переустановить шаблон. Если это делать лень, можно ручками перенести значения этих констант в то место, откуда Joomla их берёт. Иначе, даже при заданных значениях в папке шаблона, они не будут применены и вместо их значений будет выдаваться их названия. Как обновить значения языковых констант шаблона без его переустановки или накатывания обновления, я пока не нашёл.

Чтение и применение значений дополнительных параметров шаблона

Осталось разобраться с тем, как прочитать значения дополнительных параметров шаблона и применить их при рендеринге.

Подключение и чтение дополнительных параметров происходит так:

$app = JFactory::getApplication();
$params = $app->getTemplate(true)->params;

Перед использованием, лучше убедиться, что параметр задан и только потом его использовать. Например с нашим параметром задания цвета фона страницы:

if ($this->params->get('templateBackgroundColor'))
{
	$this->addStyleDeclaration('
	body {
		background-color: ' . $this->params->get('templateBackgroundColor') . ';
	}');
}

Как видно на примере, вызов значения параметра происходит по его имени, заданному в name при описании в файле templateDetails.xml.

Выводы

Если всё сделано правильно, то дополнительные поля начинают работать сразу после установки шаблона и их можно менять и устанавливать в админке Joomla. Единственное неудобство в том, что языковые константа не подхватываются автоматически (для этого требуется их перенести в папку language Joomla или переустановить шаблон).

Синтаксис задания и вызова этих параметров предельно прост и позволяет использовать дополнительные параметры для придания гибкости в настройках шаблона. Поведение шаблона в зависимости от параметров — это уже вопрос программирования шаблона и фантазии его автора.

Заберите ссылку на статью к себе, чтобы потом легко её найти!
Раз уж досюда дочитали, то может может есть желание рассказать об этом месте своим друзьям, знакомым и просто мимо проходящим?
Не надо себя сдерживать! ;)