Local e finalidade

Você pode ver um exemplo de um arquivo templateDetails.xml listado em Sistema → Temas do Site → Detalhes e Arquivos do Cassiopeia. Você também pode editá-lo lá, se tiver um bom motivo para isso. Caso contrário, deixe-o em paz! Todo tema possui um arquivo desses e um tema filho inicialmente consiste em uma estrutura de arquivos contendo apenas esse arquivo.

O arquivo templateDetails.xml contém os dados que o Joomla! precisa para gerenciar e exibir o tema. Isso inclui metadados usados para fornecer informações sobre o tema, os locais das pastas e arquivos, as posições de módulo do tema e as opções de configuração selecionáveis pelo usuário. O conteúdo do arquivo templateDetails.xml vai diferir de tema para tema.

Cassiopeia templateDetails.xml

Arquivos em formato xml têm uma estrutura bem definida. Um arquivo xml precisa ter a sintaxe correta ou não funcionará!

Formato XML

A primeira linha de todo templateDetails.xml deve começar com a definição do doctype XML.

A linha seguinte informa ao Joomla! que os dados neste arquivo são para uma extensão de tema de site. Todos os dados do tema estão contidos entre as marcações de abertura e fechamento.

<extension type="template" client="site">
...
</extension>

Metadados

A primeira seção dos dados do tema geralmente define informações do tema, por exemplo: nomes, datas, informações de contato, direitos autorais, 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á sendo protegido de spambots. Você precisa do JavaScript ativado para vê-lo.</authorEmail>
    <copyright>(C) 2017 Open Source Matters, Inc.</copyright>
    <description>TPL_CASSIOPEIA_XML_DESCRIPTION</description>
    <inheritable>1</inheritable>

Observe que um tema que pode ter temas filhos tem o valor inheritable definido como 1. Os temas filhos têm esse valor definido como 0. Esse dado é usado na listagem de Temas: Temas (Site), conforme mostrado abaixo.

site templates list

A descrição contém uma chave de idioma e não o texto real da descrição. A chave é substituída pelo texto obtido de um arquivo de idioma em tempo de execução. Os arquivos de idioma são definidos na seção de idiomas do templateDetails.xml.

templates edit style form

Pastas e arquivos

As pastas e arquivos do tema Cassiopeia são armazenados em dois locais separados. Os arquivos php e relacionados são armazenados na pasta site/templates. Os arquivos de mídia (css, imagens, js e scss) são armazenados na pasta site/media. Esses locais são definidos no arquivo 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):

templates customise cassiopeia page

Posições de módulo

As posições de módulo disponíveis são definidas como segue:

    <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 marcador cria uma posição de módulo que fica disponível na lista de posições em um formulário de edição de módulo. O formato simples da lista de posições significa que ela pode ser personalizada facilmente. Por exemplo, para adicionar uma nova posição de módulo à lista em um tema filho, basta adicionar um novo marcador dentro da tag com um nome único usando apenas letras minúsculas e sem espaços. Tenha em mente que isso apenas adiciona a posição aos formulários de edição de módulo e será necessário desenvolvimento adicional em outros arquivos do tema para renderizar a nova posição no frontend.

Cassiopeia já tem posições de tema suficientes! Se você acha que precisa de mais uma, provavelmente está enganado. Lembre-se de que qualquer quantidade de módulos pode ser atribuída a uma única posição e ordenada na página de lista de Módulos. Posições disponíveis:

Cassiopeia template positions diagram

Você também pode ver as posições de módulo em qualquer tema: em Sistema → Temas do Site selecione o botão Opções na barra de ferramentas. No formulário de Opções, defina o campo Visualizar posições de módulo como Ativado. Salvar e fechar. Vá até o seu site e adicione ?tp=1 ao final de qualquer url (ou &tp=1 se já houver um ? na url). O Joomla exibirá todas as posições de tema disponíveis, mesmo as que não foram usadas:

Cassiopeia template positions

Idiomas

Os arquivos de idioma permitem a tradução de texto estático no tema. O arquivo tpl_cassiopeia.ini contém traduções de chave para texto que serão vistas pelo Usuário. O arquivo tpl_cassiopeia.sys.ini contém 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 arquivos de idioma para o idioma padrão Inglês GB ficam armazenados em site/language/en-GB/. Outros idiomas seriam armazenados de forma semelhante em arquivos com o código ISO de idioma apropriado, por exemplo fr-FR para o francês na França ou de-DE para o alemão na 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 Tema: Editar estilo. Por exemplo, a aba Avançado do tema Cassiopeia permite que um Administrador altere a Marca, adicione um Logotipo, selecione um Esquema de fontes, entre outros.

templates edit style form advanced tab

As opções do tema são definidas dentro de uma estrutura que cria campos dentro de grupos de campos (fieldsets). Cada grupo de campos aparece como uma aba no formulário de edição. Esta é a estrutura que cria a aba Avançado mostrada 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>

Opções individuais são definidas com o marcador <field>. Cada <fieldset>, e cada parâmetro <field> dentro de um <fieldset>, necessita de um nome exclusivo definido por um atributo name. Esse nome define o próprio parâmetro e é usado para passar as configurações para os arquivos do frontend. Cada parâmetro também contém um atributo label e um atributo description. O texto do rótulo aparece junto com o parâmetro na tela de configurações para identificar para que a configuração é usada 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. Isso é selecionado pelo atributo type. Quaisquer opções necessárias, como botões de rádio ou escolhas de seleção, são definidas em marcadores <option>. Nomes de classes CSS podem ser definidos com o atributo class e um valor padrão pode ser definido usando o atributo default.

Abaixo estão as definições de opções no tema Cassiopeia padrão. Neste exemplo, todos os Rótulos, Descrições e Opções estão usando definições de strings de idioma dos arquivos de idioma definidos na seção anterior, bem como algumas do núcleo do Joomla!, para que possam ser traduzidos para idiomas diferentes 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&amp;display=swap">Fira Sans (web)</option>
                        <option value="https://fonts.googleapis.com/css2?family=Noto+Sans:wght@100;300;400;700&amp;family=Roboto:wght@100;300;400;700&amp;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, o marcador <fieldset name="advanced"> engloba todos os parâmetros e usa o atributo name para criar a aba Advanced na interface. Tudo o que é necessário para criar outra aba na interface é outro marcador <fieldset> com um atributo name diferente. Com isso em mente, é relativamente simples criar quantas abas e parâmetros adicionais forem necessários em um tema.

Um uso potencial de parâmetros extras é em sobreposições ou disposições (layouts) para temas pai ou filho.

Resumo

Este é o arquivo templateDetails.xml usado 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á sendo protegido de spambots. Você precisa do JavaScript ativado para vê-lo.</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&amp;display=swap">Fira Sans (web)</option>
                        <option value="https://fonts.googleapis.com/css2?family=Noto+Sans:wght@100;300;400;700&amp;family=Roboto:wght@100;300;400;700&amp;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>