Esquemas do tema

Estruturas de ficheiros de layout

Num tema, cada extensão que gera resultado html coloca o código de saída num ficheiro de modelo dentro da estrutura de ficheiros da extensão, muitas vezes numa pasta designada tmpl. Alguns exemplos:

• /modules/mod_login/tmpl/default.php
• /modules/mod_login/tmpl/default_logout.php
• /components/com_content/tmpl/article/default.php
• /plugins/content/vote/tmpl/vote.php

Numa sobreposição de tema, é criado um ficheiro com o mesmo nome dentro da estrutura de ficheiros do tema, que é utilizado em vez do ficheiro da estrutura de ficheiros da extensão. Exemplos correspondentes:

• /templates/cassiopeia/html/mod_login/default.php
• /templates/cassiopeia/html/mod_login/default_logout.php
• /templates/cassiopeia/html/com_content/article/default.php
• /templates/cassiopeia/html/plg_content_vote/vote.php

Isto permite personalizar o resultado consoante as suas necessidades. No entanto, não tem a opção de escolher se deve ou não utilizar a sua sobreposição. Ela é sempre utilizada.

Num layout alternativo de tema, cria-se um ficheiro com um nome diferente do original mas na mesma pasta do tema. O novo nome não deve conter um carácter de sublinhado. Também deve criar qualquer ficheiro que partilhe a primeira parte do nome original. Um exemplo:

• /templates/cassiopeia/html/mod_login/expires.php
• /templates/cassiopeia/html/mod_login/expires_logout.php

Torna-se então possível escolher se se deve utilizar o layout predefinido original ou o layout alternativo. A escolha é feita no formulário de edição do módulo ou componente (separador Avançado para módulos, separador Opções para Artigos). Note que nem todas as extensões permitem sobreposições ou layouts alternativos.

Atenção: os plugins não fornecem um mecanismo para selecionar layouts alternativos.

Layouts alternativos de módulo

Criar um layout alternativo para um módulo é semelhante a criar uma sobreposição de tema para um módulo. Em ambos os casos, cria-se uma pasta chamada templates/.../html/. Por exemplo, a pasta para uma sobreposição de tema ou layout alternativo "mod_login" para o tema cassiopeia seria templates/cassiopeia/html/mod_login/.

Existem duas diferenças importantes entre uma sobreposição de tema e um layout alternativo. A primeira é o nome do ficheiro. Para a sobreposição de tema, o ficheiro seria designado default.php para corresponder ao nome do ficheiro nuclear. Para um layout alternativo, utiliza-se um nome diferente. A única regra é que o nome do ficheiro não deve ter sublinhados.

A segunda diferença importante é que, ao contrário dos ficheiros de sobreposição de tema, que são utilizados automaticamente sempre que o módulo é exibido através do tema com a sobreposição, um ficheiro de layout alternativo só é utilizado se o selecionar como parâmetro nas configurações do módulo.

Um exemplo prático — mod_login

• Ir a Sistema → Temas do sítio → Detalhes e ficheiros do Cassiopeia
• Selecionar o separador Criar sobreposições.
• Na lista de módulos, selecionar o item mod_login.
• No separador Editor, selecionar html → mod_login para ver as cópias recém-criadas dos modelos de saída do mod_login.
• Renomear default.php para outro nome sem sublinhado, expires.php neste exemplo.
• Renomear default_logout.php para expires_logout.php.

Tem agora dois ficheiros com exatamente o mesmo conteúdo dos originais. Altere o conteúdo de expires_logout.php para adicionar uma mensagem a informar o utilizador a que horas a sessão irá expirar após cada carregamento de página.

Na linha 16, imediatamente abaixo das declarações use existentes, adicione o seguinte:

use Joomla\CMS\Factory;

date_default_timezone_set('Europe/London');
$config = Factory::getContainer()->get('config');
$lifetime = $config->get('lifetime', 0);
$time = time() + $lifetime * 60;
$endTime = date('H:i:s', $time); // time() returns a time in seconds already

E na linha 36, imediatamente a seguir à linha que contém a instrução endif, adicione este código:

<p class="text-center">
A sua sessão irá expirar às <br><?php echo $endTime; ?>
</p>

Feche os ficheiros do Cassiopeia. Selecione Conteúdo → Módulos do sítio e abra o módulo Login. No separador Avançado, no item Layout, irá encontrar uma escolha entre -- Do módulo -- / Predefinido e -- Do tema cassiopeia -- / expires.

Uma forma de utilizar esta funcionalidade é ter dois formulários de Login, um com acesso Público e outro com acesso de Superutilizadores. Neste último, selecione a opção expires e apenas os superutilizadores verão o lembrete da hora de expiração da sessão.

É importante compreender que, se especificado no ecrã de parâmetros do módulo, um ficheiro de layout alternativo para um módulo será utilizado para esse módulo independentemente do tema utilizado para exibir a página onde o módulo é mostrado. É, portanto, da responsabilidade do administrador garantir que o ficheiro de layout funcionará conforme pretendido em quaisquer temas onde este módulo possa ser mostrado.

Tradução

Pode traduzir o nome do ficheiro utilizando as Sobreposições de idioma. Experimente o seguinte procedimento:

• Selecione Sistema → Painel de gestão → Sobreposições de idioma
• Selecione o seu idioma e a localização Administrador.
• Selecione o botão Novo e preencha o formulário. Neste exemplo, a chave de idioma é TPL_CASSIOPEIA_MOD_LOGIN_LAYOUT_EXPIRES e o texto poderá ser Login / Logout com tempo de expiração
• Guardar e fechar e voltar ao formulário do módulo Login.

O campo de formulário de seleção de layout do módulo com expires traduzido:

Layouts alternativos de componentes

Os layouts alternativos de componentes funcionam de forma semelhante aos layouts de módulos. É colocado um ficheiro na mesma pasta onde colocaria um ficheiro de sobreposição de tema. Por exemplo, para criar um layout alternativo para um artigo no tema "cassiopeia", colocaria um ficheiro na pasta templates/cassiopeia/html/com_content/article/. Tal como com os layouts de módulos, o ficheiro não deve ter o mesmo nome que o ficheiro nuclear e não deve incluir sublinhados no nome. Além disso, não deve existir um ficheiro XML com o mesmo nome nesta pasta. (Discutiremos os ficheiros XML mais abaixo, em Layouts alternativos de itens de menu.)

Pode definir um valor global para os layouts de componentes na janela de opções do componente. Por exemplo, na janela Artigos — Opções, existe um parâmetro Escolher um esquema, conforme mostrado abaixo:

Tal como com os layouts de módulos, os layouts de componentes são mostrados como opções de parâmetro no ecrã de edição individual do componente. Por exemplo, para um artigo, o parâmetro aparece no separador Artigos — Editar opções, conforme mostrado abaixo.

Tal como acontece com outros parâmetros, a configuração Utilizar global irá usar a definição do parâmetro Opções. A configuração Predefinição do componente irá utilizar o layout predefinido do componente. Os layouts alternativos que criou para diferentes temas são apresentados sob cada cabeçalho de tema.

Os nomes dos ficheiros podem ser traduzidos. A linha abaixo:

    TPL_CASSIOPEIA_COM_CONTENT_ARTICLE_LAYOUT_MYLAYOUT="Title Only No XML"

irá traduzir um ficheiro chamado "mylayout.php" como "Title Only No XML".

Pode ter mais do que um ficheiro para um layout. O ficheiro inicial deve ser nomeado sem sublinhados e quaisquer ficheiros adicionais devem ter sublinhados.

Os layouts alternativos de componentes podem ser utilizados com artigos, contactos ou sinais de notícias.

Os layouts alternativos de componentes só são utilizados quando duas condições são cumpridas: (1) são especificados nos parâmetros do componente; e (2) não existe nenhum item de menu para este componente específico. Por exemplo, se tiver um ou mais itens de menu do tipo "Artigo único" configurados para um determinado artigo, então o layout alternativo para esse artigo não será utilizado. Em vez disso, será utilizado o layout especificado no item de menu. Isto é consistente com a forma geral como os parâmetros dos componentes funcionam, em que o mais específico (neste caso, um item de menu de artigo único) sobrepõe-se ao menos específico (neste caso, os parâmetros do artigo).

Layouts alternativos de categorias

Os layouts alternativos de categorias funcionam como os layouts de componentes. As regras para especificar ficheiros de layout são as mesmas. A única diferença é que a pasta é a pasta da categoria, não a pasta do componente. Por exemplo, um layout alternativo de categoria de contactos para o cassiopeia iria para a pasta templates/cassiopeia/html/com_contact/category.

Pode definir layouts de categoria globalmente, no ecrã Opções de cada componente. Abaixo está um exemplo do formulário Contactos — Opções / Categoria:

Os layouts alternativos de categorias aparecem quando adiciona ou edita uma categoria no formulário Componente — Editar categoria / Opções, conforme mostrado abaixo.

Os layouts alternativos de categorias podem ser utilizados para artigos, faixas, contactos e sinais de notícias.

Tal como acontece com os layouts de componentes, um layout de categoria só será utilizado se:

1. estiver selecionado nos parâmetros globais ou de categoria.
2. não existir nenhum item de menu especificamente para a categoria.

Se existir um item de menu configurado para uma categoria específica, será utilizado o layout selecionado no menu em vez do layout alternativo de categoria.

Blogue e lista de categoria de artigos

Para artigos, existem dois layouts de categoria nucleares disponíveis: Blogue e Lista. Cada um destes layouts aparece no formulário Artigos — Opções, no separador Categoria, sob o cabeçalho "Do componente". Os layouts alternativos também aparecem na lista, permitindo que Blogue, Lista ou layouts de tema alternativos sejam selecionados como o layout de categoria predefinido, quer globalmente, quer ao editar uma categoria de artigo única.

Isto significa que, tal como noutras opções de layout, pode controlar se as hiperligações de categorias de artigos utilizam layouts de blogue ou de lista. É importante perceber que, tal como outros parâmetros de layout, esta opção só terá efeito quando não existir um item de menu de categoria única para a categoria.

Itens de menu alternativos

Os itens de menu alternativos têm uma diferença importante em relação aos outros. Para criar um layout alternativo para um item de menu, deve incluir um ficheiro XML cujo nome corresponda ao nome do ficheiro de layout inicial. Por exemplo, para criar um item de menu alternativo chamado "myarticle" para um artigo no tema cassiopeia, criaria dois ficheiros na pasta templates/cassiopeia/html/com_content/article chamados myarticle.php e myarticle.xml. Se quisesse incluir mais ficheiros de layout, adicionaria esses ficheiros com sublinhados nos nomes dos ficheiros.

O ficheiro XML utiliza o mesmo formato que os ficheiros XML nucleares de itens de menu. Isto permite-lhe não só criar um layout personalizado para este item de menu, mas também criar parâmetros personalizados. Por exemplo, poderia ocultar alguns parâmetros ou adicionar novos parâmetros.

Os itens de menu alternativos aparecem quando seleciona um tipo de item de menu, como mostrado abaixo.

Os itens de menu alternativos são utilizados e funcionam da mesma forma que os itens de menu normais. Como já se baseiam em layouts personalizados, as sobreposições de tema não se aplicam aos itens de menu alternativos.

Como indicado acima, os layouts de itens de menu têm prioridade sobre os layouts alternativos de componentes ou categorias.

A tradução de itens de menu alternativos é feita com as seguintes etiquetas nos ficheiros XML. O formato é "TPL_"<nome do tema>_<componente>_<vista>_<nome do item de menu>_<tipo de etiqueta>. Por exemplo, as linhas abaixo traduzirão o título, a opção e a descrição de um item de menu alternativo chamado "catmenuitem".

    TPL_CASSIOPEIA_COM_CONTENT_CATEGORY_VIEW_CATMENUITEM_TITLE="cassiopeia Custom Category Layout"
    TPL_CASSIOPEIA_COM_CONTENT_CATEGORY_VIEW_CATMENUITEM_OPTION="cassiopeia Custom"
    TPL_CASSIOPEIA_COM_CONTENT_CATEGORY_VIEW_CATMENUITEM_DESC="Description for cassiopeia custom category layout."

Estas cadeias de texto têm de ser adicionadas a administrator/language/overrides/en-GB.override.ini, mas pode utilizar o formulário de Sobreposições de idioma descrito acima.

O ficheiro catmenuitem.xml começaria com:

<?xml version="1.0" encoding="utf-8"?>
<metadata>
   <layout title="TPL_CASSIOPEIA_COM_CONTENT_CATEGORY_VIEW_CATMENUITEM_TITLE" option="TPL_CASSIOPEIA_COM_CONTENT_CATEGORY_VIEW_CATMENUITEM_OPTION">
      <help
         key = "JHELP_MENUS_MENU_ITEM_ARTICLE_SINGLE_ARTICLE"
      />
      <message>
         <![CDATA[TPL_CASSIOPEIA_COM_CONTENT_CATEGORY_VIEW_CATMENUITEM_DESC]]>
      </message>
   </layout>

Controlar o tema para itens de menu alternativos

Como referido acima, a presença de um ficheiro XML torna um layout alternativo num item de menu. O formato do ficheiro XML é o mesmo que o formato dos ficheiros XML de itens de menu nucleares. Com este ficheiro XML, pode adicionar os parâmetros que deseja incluir para este item de menu. Podem ser os mesmos de um dos itens de menu nucleares, ou pode omitir parâmetros nucleares ou adicionar novos. Note que, se adicionar novos parâmetros, estes podem ser utilizados no ficheiro de layout mas não serão utilizados nos ficheiros nucleares de modelo ou de vista.

Também é possível sobrepor as configurações de parâmetros nucleares. Um exemplo disto é controlar com que temas um layout de item de menu alternativo pode ser exibido. Em alguns casos, pode querer permitir que um item de menu personalizado seja exibido com qualquer tema do sítio. Noutros casos, pode querer limitar o layout desse item de menu a um tema específico. Nesta situação, bastaria adicionar o seguinte parâmetro ao ficheiro XML do item de menu:

<fields>
  <field
    name="template_style_id"
    type="templatestyle"
    label="COM_MENUS_ITEM_FIELD_TEMPLATE_LABEL"
    description="COM_MENUS_ITEM_FIELD_TEMPLATE_DESC"
    filter="int"
    template="cassiopeia"
    class="inputbox">
  </field>
 </fields>

Isto irá sobrepor o parâmetro nuclear template_style_id. Definir o tema como "cassiopeia" neste caso irá limitar o utilizador a selecionar apenas estilos de tema do tema "cassiopeia".

Mais informações

• Noções básicas de temas
• Pastas e ficheiros do tema Cassiopeia
• Personalização do tema Cassiopeia
• Sobreposições de tema
• Layouts de tema
• Tema Cassiopeia simplificado — um caso de estudo — um tema simples baseado no Cassiopeia