User Documentation Localização e finalidade
Pode ver um exemplo de um ficheiro templateDetails.xml listado em Sistema → Temas do sítio → Detalhes e ficheiros do Cassiopeia. Também pode editá-lo aí, se tiver uma boa razão para o fazer. Caso contrário, não lhe mexa! Todos os temas têm um ficheiro deste tipo e um tema-filho inicialmente consiste numa estrutura de ficheiros que contém apenas este ficheiro.
O ficheiro templateDetails.xml contém os dados de que o Joomla! necessita para gerir e exibir o tema. Isto inclui metadados utilizados para fornecer informações sobre o tema, as localizações das pastas e ficheiros, as posições de módulo do tema e as opções de configuração selecionáveis pelo utilizador. O conteúdo do ficheiro templateDetails.xml varia de tema para tema.
Cassiopeia templateDetails.xml
Os ficheiros em formato xml têm uma estrutura bem definida. Um ficheiro xml deve ter a sintaxe correta, caso contrário não funcionará!
Formato XML
A primeira linha de cada templateDetails.xml deve começar com a definição do tipo de documento XML.
A linha seguinte indica ao Joomla! que os dados neste ficheiro são para uma extensão de tema do sítio. Todos os dados do tema estão contidos entre as tags de abertura e de fecho.
<extension type="template" client="site">
...
</extension>
Metadados
A primeira secção dos dados do tema normalmente define informações do tema, por exemplo: nomes, datas, informações de contacto, direitos de autor, número de versão e descrição.
<extension version="3.1" type="template" client="site">
<name>cassiopeia</name>
<version>1.0</version>
<creationDate>2017-02</creationDate>
<author>Joomla! Project</author>
<authorEmail>Este endereço de email está protegido contra piratas. Necessita ter o JavaScript autorizado para o visualizar. </authorEmail>
<copyright>(C) 2017 Open Source Matters, Inc.</copyright>
<description>TPL_CASSIOPEIA_XML_DESCRIPTION</description>
<inheritable>1</inheritable>
Note que um tema que pode ter temas-filhos tem o valor inheritable definido como 1. Os temas-filhos têm este valor definido como 0. Estes dados são utilizados na listagem Temas — Temas (Sítio), como se mostra abaixo.
A descrição contém uma chave de idioma e não a cadeia de texto de descrição real. A chave é substituída pelo texto obtido de um ficheiro de idioma em tempo de execução. Os ficheiros de idioma são definidos na secção de idiomas do templateDetails.xml.
Pastas e ficheiros
As pastas e ficheiros do tema Cassiopeia são guardados em dois locais distintos. Os ficheiros php e relacionados são guardados na pasta site/templates. Os ficheiros de media (css, imagens, js e scss) são guardados na pasta site/media. Essas localizações são definidas no ficheiro xml da seguinte forma:
<files>
<filename>component.php</filename>
<filename>error.php</filename>
<filename>index.php</filename>
<filename>joomla.asset.json</filename>
<filename>offline.php</filename>
<filename>templateDetails.xml</filename>
<folder>html</folder>
</files>
<media destination="templates/site/cassiopeia" folder="media">
<folder>js</folder>
<folder>css</folder>
<folder>scss</folder>
<folder>images</folder>
</media>
Este é o padrão visto em todos os temas modernos do Joomla 4 e 5. A estrutura pode ser vista no formulário Temas — Personalizar (Cassiopeia):
Posições de módulo
As posições de módulo disponíveis são definidas da seguinte forma:
<positions>
<position>topbar</position>
<position>below-top</position>
<position>menu</position>
<position>search</position>
<position>banner</position>
<position>top-a</position>
<position>top-b</position>
<position>main-top</position>
<position>main-bottom</position>
<position>breadcrumbs</position>
<position>sidebar-left</position>
<position>sidebar-right</position>
<position>bottom-a</position>
<position>bottom-b</position>
<position>footer</position>
<position>debug</position>
</positions>
Cada etiqueta cria uma posição de módulo que fica disponível na lista de posições num formulário de edição de módulo. O formato simples da lista de posições significa que pode ser personalizado facilmente. Por exemplo, para adicionar uma nova posição de módulo à lista num tema descendente, basta adicionar uma nova etiqueta dentro da etiqueta com um nome único, usando apenas letras minúsculas sem espaços. Tenha em conta que isto apenas adiciona a posição aos formulários de edição de módulo, sendo necessário desenvolvimento adicional noutros ficheiros do tema para apresentar a nova posição no sítio.
O Cassiopeia já tem posições de tema suficientes! Se acha que precisa de mais uma, provavelmente está enganado. Lembre-se de que qualquer número de módulos pode ser atribuído a uma única posição e ordenado na página da lista de módulos. Posições disponíveis:
Também pode ver as posições de módulo em qualquer tema: em Sistema → Temas do sítio selecione o botão Opções na Barra de ferramentas. No formulário Opções, defina o campo Pré-visualizar posições de módulo como Ativado. Guardar e fechar. Vá ao seu sítio e adicione ?tp=1 ao final de qualquer URL (ou &tp=1 se já existir um ? no URL). O Joomla irá exibir todas as posições de tema disponíveis, mesmo as que não tenham sido usadas:
Idiomas
Os ficheiros de idioma permitem a tradução de texto estático no tema. O ficheiro tpl_cassiopeia.ini contém as traduções de chave para texto que serão vistas pelo utilizador. O ficheiro tpl_cassiopeia.sys.ini contém as traduções de chave para texto que serão vistas pelo administrador.
<languages folder="language">
<language tag="en-GB">en-GB/tpl_cassiopeia.ini</language>
<language tag="en-GB">en-GB/tpl_cassiopeia.sys.ini</language>
</languages>
Os ficheiros de idioma para o idioma predefinido inglês GB estão armazenados em site/language/en-GB/. Outros idiomas seriam armazenados de forma semelhante em ficheiros com o código ISO de idioma apropriado, por exemplo fr-FR para francês de França ou de-DE para alemão da Alemanha (que pode ser diferente do alemão suíço e do alemão austríaco).
Opções
Um tema pode oferecer opções de exibição que podem ser escolhidas pelo Administrador no formulário Temas — Editar estilo. Por exemplo, o separador Avançado do tema Cassiopeia permite a um Administrador alterar a Marca, adicionar um Logótipo, selecionar um Esquema de tipos de letra, e mais.
As opções do tema são definidas numa estrutura que cria campos dentro de conjuntos de campos. Cada conjunto de campos aparece como um separador no formulário de edição. Esta é a estrutura que cria o separador Avançado visto acima.
<config>
<fields name="params">
<fieldset name="advanced">
<field
name="brand"
type="radio"
label="TPL_CASSIOPEIA_BRAND_LABEL"
default="1"
layout="joomla.form.field.radio.switcher"
filter="boolean"
>
<option value="0">JNO</option>
<option value="1">JYES</option>
</field>
...
</fieldset>
</fields>
</config>
As opções individuais são definidas com a etiqueta <field>. Cada <fieldset>, e cada parâmetro <field> dentro de um <fieldset>, requer um nome único definido por um atributo name. Este nome define o próprio parâmetro e é usado para passar configurações para os ficheiros do frontend. Cada parâmetro também contém um atributo label e um atributo description. O texto do rótulo aparece junto ao parâmetro no ecrã de configurações para identificar para que serve a definição e informações mais detalhadas podem ser incluídas na descrição.
Um campo de parâmetro pode ser praticamente qualquer tipo de entrada de formulário com as opções correspondentes. Isto é selecionado pelo atributo type. Quaisquer opções necessárias, como escolhas de botão de rádio ou de seleção, são definidas em etiquetas <option>. Os nomes das classes CSS podem ser definidos com o atributo class e um valor predefinido pode ser definido usando o atributo default.
Abaixo estão as definições de opções no tema Cassiopeia predefinido. Neste exemplo, todos os Rótulos, Descrições e Opções estão a usar definições de cadeias de idioma dos ficheiros de idioma definidos na secção anterior, bem como algumas do núcleo do Joomla!, para que possam ser traduzidos para diferentes idiomas conforme necessário.
<config>
<fields name="params">
<fieldset name="advanced">
<field
name="brand"
type="radio"
label="TPL_CASSIOPEIA_BRAND_LABEL"
default="1"
layout="joomla.form.field.radio.switcher"
filter="boolean"
>
<option value="0">JNO</option>
<option value="1">JYES</option>
</field>
<field
name="logoFile"
type="media"
default=""
label="TPL_CASSIOPEIA_LOGO_LABEL"
showon="brand:1"
/>
<field
name="siteTitle"
type="text"
default=""
label="TPL_CASSIOPEIA_TITLE"
filter="string"
showon="brand:1"
/>
<field
name="siteDescription"
type="text"
default=""
label="TPL_CASSIOPEIA_TAGLINE_LABEL"
description="TPL_CASSIOPEIA_TAGLINE_DESC"
filter="string"
showon="brand:1"
/>
<field
name="useFontScheme"
type="groupedlist"
label="TPL_CASSIOPEIA_FONT_LABEL"
default="0"
>
<option value="0">JNONE</option>
<group label="TPL_CASSIOPEIA_FONT_GROUP_LOCAL">
<option value="media/templates/site/cassiopeia/css/global/fonts-local_roboto.css">Roboto (local)</option>
</group>
<group label="TPL_CASSIOPEIA_FONT_GROUP_WEB">
<option value="https://fonts.googleapis.com/css2?family=Fira+Sans:wght@100;300;400;700&display=swap">Fira Sans (web)</option>
<option value="https://fonts.googleapis.com/css2?family=Noto+Sans:wght@100;300;400;700&family=Roboto:wght@100;300;400;700&display=swap">Roboto + Noto Sans (web)</option>
</group>
</field>
<field
name="noteFontScheme"
type="note"
description="TPL_CASSIOPEIA_FONT_NOTE_TEXT"
class="alert alert-warning"
/>
<field
name="colorName"
type="filelist"
label="TPL_CASSIOPEIA_COLOR_NAME_LABEL"
default="colors_standard"
fileFilter="^custom.+[^min]\.css$"
exclude="^colors.+"
stripext="true"
hide_none="true"
hide_default="true"
directory="media/templates/site/cassiopeia/css/global/"
validate="options"
>
<option value="colors_standard">TPL_CASSIOPEIA_COLOR_NAME_STANDARD</option>
<option value="colors_alternative">TPL_CASSIOPEIA_COLOR_NAME_ALTERNATIVE</option>
</field>
<field
name="fluidContainer"
type="radio"
layout="joomla.form.field.radio.switcher"
default="0"
label="TPL_CASSIOPEIA_FLUID_LABEL"
>
<option value="0">TPL_CASSIOPEIA_STATIC</option>
<option value="1">TPL_CASSIOPEIA_FLUID</option>
</field>
<field
name="stickyHeader"
type="radio"
label="TPL_CASSIOPEIA_STICKY_LABEL"
layout="joomla.form.field.radio.switcher"
default="0"
filter="integer"
>
<option value="0">JNO</option>
<option value="1">JYES</option>
</field>
<field
name="backTop"
type="radio"
label="TPL_CASSIOPEIA_BACKTOTOP_LABEL"
layout="joomla.form.field.radio.switcher"
default="0"
filter="integer"
>
<option value="0">JNO</option>
<option value="1">JYES</option>
</field>
</fieldset>
</fields>
</config>
Neste exemplo, a etiqueta <fieldset name="advanced"> envolve todos os parâmetros e utiliza o atributo name para criar o separador Advanced na interface. Tudo o que é necessário para criar outro separador na interface é outra etiqueta <fieldset> com um atributo name diferente. Tendo isto em conta, é relativamente simples criar tantos separadores e parâmetros adicionais quantos forem necessários num tema.
Uma utilização potencial de parâmetros extra é em sobreposições ou esquemas tanto para temas hospedeiros como descendentes.
Resumo
Este é o ficheiro templateDetails.xml utilizado pelo Cassiopeia:
<?xml version="1.0" encoding="utf-8"?>
<extension type="template" client="site">
<name>cassiopeia</name>
<version>1.0</version>
<creationDate>2017-02</creationDate>
<author>Joomla! Project</author>
<authorEmail>Este endereço de email está protegido contra piratas. Necessita ter o JavaScript autorizado para o visualizar. </authorEmail>
<copyright>(C) 2017 Open Source Matters, Inc.</copyright>
<description>TPL_CASSIOPEIA_XML_DESCRIPTION</description>
<inheritable>1</inheritable>
<files>
<filename>component.php</filename>
<filename>error.php</filename>
<filename>index.php</filename>
<filename>joomla.asset.json</filename>
<filename>offline.php</filename>
<filename>templateDetails.xml</filename>
<folder>html</folder>
</files>
<media destination="templates/site/cassiopeia" folder="media">
<folder>js</folder>
<folder>css</folder>
<folder>scss</folder>
<folder>images</folder>
</media>
<positions>
<position>topbar</position>
<position>below-top</position>
<position>menu</position>
<position>search</position>
<position>banner</position>
<position>top-a</position>
<position>top-b</position>
<position>main-top</position>
<position>main-bottom</position>
<position>breadcrumbs</position>
<position>sidebar-left</position>
<position>sidebar-right</position>
<position>bottom-a</position>
<position>bottom-b</position>
<position>footer</position>
<position>debug</position>
</positions>
<languages folder="language">
<language tag="en-GB">en-GB/tpl_cassiopeia.ini</language>
<language tag="en-GB">en-GB/tpl_cassiopeia.sys.ini</language>
</languages>
<config>
<fields name="params">
<fieldset name="advanced">
<field
name="brand"
type="radio"
label="TPL_CASSIOPEIA_BRAND_LABEL"
default="1"
layout="joomla.form.field.radio.switcher"
filter="boolean"
>
<option value="0">JNO</option>
<option value="1">JYES</option>
</field>
<field
name="logoFile"
type="media"
default=""
label="TPL_CASSIOPEIA_LOGO_LABEL"
showon="brand:1"
/>
<field
name="siteTitle"
type="text"
default=""
label="TPL_CASSIOPEIA_TITLE"
filter="string"
showon="brand:1"
/>
<field
name="siteDescription"
type="text"
default=""
label="TPL_CASSIOPEIA_TAGLINE_LABEL"
description="TPL_CASSIOPEIA_TAGLINE_DESC"
filter="string"
showon="brand:1"
/>
<field
name="useFontScheme"
type="groupedlist"
label="TPL_CASSIOPEIA_FONT_LABEL"
default="0"
>
<option value="0">JNONE</option>
<group label="TPL_CASSIOPEIA_FONT_GROUP_LOCAL">
<option value="media/templates/site/cassiopeia/css/global/fonts-local_roboto.css">Roboto (local)</option>
</group>
<group label="TPL_CASSIOPEIA_FONT_GROUP_WEB">
<option value="https://fonts.googleapis.com/css2?family=Fira+Sans:wght@100;300;400;700&display=swap">Fira Sans (web)</option>
<option value="https://fonts.googleapis.com/css2?family=Noto+Sans:wght@100;300;400;700&family=Roboto:wght@100;300;400;700&display=swap">Roboto + Noto Sans (web)</option>
</group>
</field>
<field
name="noteFontScheme"
type="note"
description="TPL_CASSIOPEIA_FONT_NOTE_TEXT"
class="alert alert-warning"
/>
<field
name="colorName"
type="filelist"
label="TPL_CASSIOPEIA_COLOR_NAME_LABEL"
default="colors_standard"
fileFilter="^custom.+[^min]\.css$"
exclude="^colors.+"
stripext="true"
hide_none="true"
hide_default="true"
directory="media/templates/site/cassiopeia/css/global/"
validate="options"
>
<option value="colors_standard">TPL_CASSIOPEIA_COLOR_NAME_STANDARD</option>
<option value="colors_alternative">TPL_CASSIOPEIA_COLOR_NAME_ALTERNATIVE</option>
</field>
<field
name="fluidContainer"
type="radio"
layout="joomla.form.field.radio.switcher"
default="0"
label="TPL_CASSIOPEIA_FLUID_LABEL"
>
<option value="0">TPL_CASSIOPEIA_STATIC</option>
<option value="1">TPL_CASSIOPEIA_FLUID</option>
</field>
<field
name="stickyHeader"
type="radio"
label="TPL_CASSIOPEIA_STICKY_LABEL"
layout="joomla.form.field.radio.switcher"
default="0"
filter="integer"
>
<option value="0">JNO</option>
<option value="1">JYES</option>
</field>
<field
name="backTop"
type="radio"
label="TPL_CASSIOPEIA_BACKTOTOP_LABEL"
layout="joomla.form.field.radio.switcher"
default="0"
filter="integer"
>
<option value="0">JNO</option>
<option value="1">JYES</option>
</field>
</fieldset>
</fields>
</config>
</extension>