Какова цель файла templateDetails.xml?

From Joomla! Documentation

This page is a translated version of the page What is the purpose of the templateDetails.xml file? and the translation is 65% complete.

Other languages:
Deutsch • ‎English • ‎español • ‎français • ‎Nederlands • ‎português do Brasil • ‎русский

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

Файл templateDetails.xml использует довольно простой формат и структуру XML. XML-данные в этом файле разделяются на разделы и специально отформатированы для визуализации различных частей и параметров. XML-данные считываются и анализируются мощными инструментами в Joomla! затем визуализируется для регистрации шаблона и создания отображения в Менеджере шаблонов. Это предоставляет разработчикам шаблонов относительно простой способ создания назначений, настроек и параметров для использования в шаблоне.

The implementation of templateDetails.xml will vary from template to template, it can be simple or complex depending on what features the template offers. The default Joomla! 3 Protostar template serves as an excellent example to demonstrate how this file is used. The various sections of this file are explained below.

XML Format

Две верхние строки каждого файла templateDetails.xml должны начинаться с определения формата XML и типа doctype.

<?xml version="1.0" encoding="utf-8"?>
<!DOCTYPE install PUBLIC "-//Joomla! 2.5//DTD template 1.0//EN" "http://www.joomla.org/xml/dtd/2.5/template-install.dtd">

Следующая строка также требуется, поскольку она сообщает Joomla! что данные в этом файле должны использоваться для расширения, в данном случае шаблона. Все данные шаблона содержатся в этом теге <extension>, и файл заканчивается закрытием этого тега </ extension>.

<extension version="3.1" type="template" client="site">

Basic Details

Первый раздел, как правило, где разработчики шаблонов включают информацию о шаблоне. Обычная информация, такая как имена, даты, контактная информация, авторские права, номер версии и базовое описание. Эти данные используются в диспетчере шаблонов и отображаются в списке доступных шаблонов и могут отображаться также на экранах редактирования шаблонов.

Template Basic Details as seen in Template Manager > Templates

Template Details example

Protostar XML code for basic details:

<extension version="3.1" type="template" client="site">
	<name>protostar</name>
	<version>1.0</version>
	<creationDate>4/30/2012</creationDate>
	<author>Kyle Ledbetter</author>
	<authorEmail>admin@joomla.org</authorEmail>
	<copyright>Copyright (C) 2005 - 2014 Open Source Matters, Inc. All rights reserved.</copyright>
	<description>TPL_PROTOSTAR_XML_DESCRIPTION</description>

Вы можете заметить, что в последней строке этого кода, описание, содержит строку языка, а не фактическое описание. Эта строка ссылается на языковой файл в шаблоне, где фактическое описание определено и написано. Это предпочтительный метод в Joomla! для расширений, которые распространяются для общего пользования для поддержки международной языковой поддержки, однако можно просто ввести описание, если перевод не вызывает беспокойства. Языковые файлы также определены в файле templateDetails.xml в разделе языка, который более подробно рассматривается ниже в этой статье.

Template Description seen in Protostar Editor

Template Details example

Folder Structure

Все папки, связанные с установкой шаблона, перечислены здесь. Все файлы и папки, расположенные в корневом каталоге шаблона во время установки, должны быть перечислены здесь. Любые файлы, содержащиеся в указанной папке, автоматически включаются. Каждая папка содержит полную информацию о пути, начиная с корня шаблона. Установщик администратора использует эту информацию при хранении файлов во время установки.

Ниже представлена структура файлов и папок из шаблона Protostar по умолчанию. Это довольно стандартная файловая структура для базового Joomla! шаблон.

	<files>
		<filename>component.php</filename>
		<filename>error.php</filename>
		<filename>favicon.ico</filename>
		<filename>index.php</filename>
		<filename>templateDetails.xml</filename>
		<filename>template_preview.png</filename>
		<filename>template_thumbnail.png</filename>
		<folder>css</folder>
		<folder>html</folder>
		<folder>images</folder>
		<folder>img</folder>
		<folder>js</folder>
		<folder>language</folder>
		<folder>less</folder>
	</files>

File directory view of J3 Protostar

J3 protostar file structure en.jpg

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

Это позиции модуля, определенные в шаблоне Protostar по умолчанию:

	<positions>
		<position>banner</position>
		<position>debug</position>
		<position>position-0</position>
		<position>position-1</position>
		<position>position-2</position>
		<position>position-3</position>
		<position>position-4</position>
		<position>position-5</position>
		<position>position-6</position>
		<position>position-7</position>
		<position>position-8</position>
		<position>position-9</position>
		<position>position-10</position>
		<position>position-11</position>
		<position>position-12</position>
		<position>position-13</position>
		<position>position-14</position>
		<position>footer</position>
	</positions>

Список позиций содержится в теге <position>. Каждый тег <position> создает позицию модуля, доступную из списка позиций в диспетчере модулей и в других областях Joomla! где могут быть выбраны позиции модуля.

Простой формат списка позиций означает, что его можно легко настроить. Например, чтобы добавить новую позицию модуля в список, просто добавьте новый тег <position> внутри тега <position> с уникальным именем, используя все строчные буквы без пробелов. Имейте в виду, что это только добавляет позицию в бэкэнд, а дополнительная разработка в других файлах шаблонов требуется для рендеринга новой позиции на лицевой стороне.

Languages

Некоторые шаблоны могут включать языковые файлы, позволяющие переносить статический текст в шаблоне. Обратите внимание, что языковая папка определена, а также включены два языковых файла внутри. Несмотря на то, что языковая папка была определена ранее, эти файлы должны иметь свои собственные определения. Этот метод сообщает Joomla! где хранятся языковые файлы, содержащие строки, используемые шаблоном.

Первый файл содержит языковой файл для текста, который будет просматриваться пользователем. Второй файл, с расширением .sys или системой, предназначен для текста, который будет отображаться в области «Администратор».

Это языковая папка и структура файлов из шаблона Protostar по умолчанию:

	<languages folder="language">
		<language tag="en-GB">en-GB/en-GB.tpl_protostar.ini</language>
		<language tag="en-GB">en-GB/en-GB.tpl_protostar.sys.ini</language>
	</languages>

Языковые строки используются в шаблонах и во всем Joomla! с целью использования обширных функций поддержки международного языка в Joomla!. Этот метод предоставляет разработчикам и пользователям относительно простой метод перевода любого текста, который используется в шаблонах и расширениях. Joomla! проверит языковые файлы для любых используемых языковых строк и загрузит соответствующий текст на выбранном пользователем языке вместо строки. В этом случае есть только файлы для английского языка (en-GB), любые текстовые переводы на других языках должны предоставляться Пользователями или Разработчиками, прежде чем они смогут использоваться Joomla!.

Дополнительная информация о языковых файлах:

Параметры

Экран расширенных параметров Protostar

Шаблон может предлагать параметры отображения и другие параметры, которые могут быть выбраны Администратором в Диспетчере шаблонов. Например, шаблон Protostar по умолчанию позволяет администратору изменять различные цвета, шрифты и добавлять логотип, эти параметры находятся на вкладке «Дополнительно», которая также определяется и создается параметрами XML.

Параметры шаблона содержатся внутри тега <config>, который содержит тег <fields> с атрибутом 'name' 'params. Внутри тега <fields> указаны группы параметров и отдельные параметры. Тег <fieldset> используется для создания групп параметров. Индивидуальные параметры определяются тегом <field>.

Каждый <fieldset> и каждый параметр <field> в <fieldset> требуют уникального имени, определяемого атрибутом name 'name ». Это имя определяет сам параметр и используется для передачи настроек в файлы фронтэнд. Каждый параметр должен также содержать атрибут 'label' 'и' description '. Текст метки отображается с параметром на экране настроек, чтобы определить, для чего используется параметр, и более подробная информация может быть включена в описание.

Поле параметров может быть фактически любым типом ввода формы с соответствующими параметрами, это выбирается атрибутом типа . Любые необходимые параметры, такие как переключатель или выбор select, определяются в тегах <option>. Имена классов CSS могут быть определены с помощью атрибута 'class' . и параметр параметра по умолчанию может быть определен с использованием атрибута 'default' .

Ниже приведены определения параметров в шаблоне Protostar по умолчанию. В этом примере все ярлыки, описания и параметры используют определения языковой строки из языковых файлов, определенных в предыдущем разделе, а также некоторые из Joomla! так что они могут быть переведены на разные языки по мере необходимости.

	<config>
		<fields name="params">
			<fieldset name="advanced">
				<field name="templateColor" class="" type="color" default="#08C"
					label="TPL_PROTOSTAR_COLOR_LABEL"
					description="TPL_PROTOSTAR_COLOR_DESC" />

				<field name="templateBackgroundColor" class="" type="color" default="#F4F6F7"
					label="TPL_PROTOSTAR_BACKGROUND_COLOR_LABEL"
					description="TPL_PROTOSTAR_BACKGROUND_COLOR_DESC" />

				<field name="logoFile" class="" type="media" default=""
					label="TPL_PROTOSTAR_LOGO_LABEL"
					description="TPL_PROTOSTAR_LOGO_DESC" />
					
				<field name="sitetitle"  type="text" default=""
					label="JGLOBAL_TITLE"
					description="JFIELD_ALT_PAGE_TITLE_LABEL"
					filter="string" />

				<field name="sitedescription"  type="text" default=""
					label="JGLOBAL_DESCRIPTION"
					description="JGLOBAL_SUBHEADING_DESC"
					filter="string" />

				<field name="googleFont"
					type="radio"
					class="btn-group btn-group-yesno"
					default="1"
					label="TPL_PROTOSTAR_FONT_LABEL"
					description="TPL_PROTOSTAR_FONT_DESC"
				>
					<option value="1">JYES</option>
					<option value="0">JNO</option>
				</field>

				<field name="googleFontName" class="" type="text" default="Open+Sans"
					label="TPL_PROTOSTAR_FONT_NAME_LABEL"
					description="TPL_PROTOSTAR_FONT_NAME_DESC" />

				<field name="fluidContainer"
					type="radio"
					class="btn-group btn-group-yesno"
					default="0"
					label="TPL_PROTOSTAR_FLUID_LABEL"
					description="TPL_PROTOSTAR_FLUID_DESC"
				>
					<option value="1">TPL_PROTOSTAR_FLUID</option>
					<option value="0">TPL_PROTOSTAR_STATIC</option>
				</field>
			</fieldset>
		</fields>
	</config>

Шаблон Protostar иллюстрирует несколько различных способов использования XML в интерфейсе шаблона, но есть еще много возможностей. В этом примере тег <fieldset name = "advanced>> содержит все параметры и использует атрибут 'name' для создания вкладки« Дополнительно »в интерфейсе. Все, что необходимо для создания другой вкладки в интерфейсе, это другой тег <fieldset> с другим атрибутом 'name' . Имея это в виду, относительно просто создать как можно больше дополнительных вкладок и параметров в шаблоне.

Additional Resources