Entendendo temas Joomla!
From Joomla! Documentation
Estrutura de Diretório de Tema Típica
O CMS Joomla! usa uma estrutura de diretórios e arquivos que podem variar de um tema para outro.
- Temas para o Site - aqueles que modificam o visual de um site - podem ser encontrados no diretório
/templates. Por exemplo, se o tema se chamar "meutema", ele estará dentro desse diretório:
<path-to-Joomla!>/templates/meutema
- Temas para o Administrator - aqueles que modificam o visual da área de administração do site - podem ser encontrados no diretório
/administrator/templatesdirectory. Por exemplo, se o tema do administrador se chamar "meutemaadmin", ele estará dentro do diretório:
<path-to-Joomla!>/administrator/templates/meutemaadmin
Diretórios de Temas
Um template Joomla! típico inclui os seguintes diretórios:
- css - contém todos os arquivos .css
- html - contém as substituições do temao para exibição de páginas do sistema e de módulos
- images - contém todas as imagens usadas pelo template
- language - contém arquivos de idiomas adicionais usados pelo temantains additional language files used by the template
Dependendo da complexidade e projeto do tema, também pode conter:
- js - contém arquivos JavaScript usados em funcionalidades adicionais pelo template
Estrutura de Exemplo com Arquivos
O caminho típico de um tema é <root>/public_html/<nome-do-domínio>/template/<nome do seu tema> que contém os seguintes diretórios e arquivos baseados no seu tema.
/css /html /images /javascript /language component.php error.php favicon.ico index.php templateDetails.xml template_preview.png template_thumbnail.png
Arquivos dos Temas
O mais comum é o tema ter pelo menos os seguintes arquivos:
- index.php
- Apresenta a lógica para exibição e posicionamento de módulos e componentes.
- component.php
- Apresenta a lógica para exibição da página pronta para impressão, envio por e-mail etc.
- error.php
- Apresenta uma maneira de mostrar problemas, como a página 404, Páginas não encotrada.
- favicon.ico
- arquivo do favicon
- template.css
- Contém os aspectos de formatação e apresentação do tema, como margens, fontes, cabeçalhos, contorno de imagem, listagens etc. O arquivo .css pode estar localizado dentro do diretório
/css.
- templateDetails.xml
- Guarda a meta-informação relacionada ao tema e é usado pelo Instalador e Gerenciador de Temas.
- template_preview.ext - substitua .ext pela extensão do formato da imagem (.jpg, .png, .gif)
- Geralmente uma imagem de 600x400 pixel que é apresentada quando se clica sobre a miniatura no Gerenciador de Temas: Temas, mas não no Gerenciador de Temas:Estilos. O administrador vê uma janela popup modal do tema antes de aplicá-lo ao Site.
- template_thumbnail.ext - substitua .ext com o formato de extensão da imagem (.jpg, .png, .gif)
- Geralmente uma imagem de 200x150 exibida na listagem no Gerenciador de Temas:Temas, mas não no Gerenciador de Temas:Estilos. O administrador pode ver essa miniatura antes de aplicar o tema ao Site.
O arquivo templateDetails.xml é obrigatório para os temas Joomla! e pode ser encontrado no diretório raiz do tema de qualquer tema dentro do diretório templates do Joomla!. Este arquivo XML contém os meta-dados básicos que o Joomla! necessita para exibir e fornecê-lo como opção de tema no backend. Ele também contém uma variedade de outros meta-dados que são usados para prover informações sobre o tema e os autores do tema e também define os arquivos e pastas que são utilizados pelo tema. Ele também define os arquivos de idioma, bem como os parâmetros e configurações que o tema vai oferecer no backend.
The templateDetails.xml file uses a fairly basic XML format and structure. The XML data in this file is separated into sections and specifically formatted in to render the various pieces and parameters. The XML data is read and parsed by powerful tools in the Joomla! core, then rendered to register the template and create the display seen in the Template Manager. This provides template developers a relatively simple method for creating assignments, settings and parameters for use in the template.
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
The top two lines of every templateDetails.xml file need to start with defining the XML format and 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">The next line is also required as it tells Joomla! that the data in this file is to be used for an extension, in this case a template. All template data is contained within this <extension> tag, and the file concludes by closing this tag </extension>.
<extension version="3.1" type="template" client="site">Basic Details
The first section is generally where template developers include information about the template. Information such as names, dates, contact information, copyrights, version number and a basic description are common. This data is used in the Template Manager and is shown in the list of available templates and can be displayed in the template editing screens as well.
Template Basic Details as seen in Template Manager > Templates
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>You may notice that the final line of this code, the description, contains a language string and not the actual description. This string references a language file in the template where the actual description is defined and written. This is a preferred method in Joomla! for extensions that are distributed for public use to accommodate international language support, however one could simply type the description if translation is not a concern. The language files are also defined in the templateDetails.xml file, in the language section, which is covered in more detail later in this article.
Template Description seen in Protostar Editor
Folder Structure
All Folders related to the template installation are listed here. All files and folders located in the root of the template directory during installation need to be listed here. Any files contained inside a folder that is listed are automatically included. Each folder contains full path information starting at the template root. The Administrator's Installer uses this information when storing the files during installation.
Below is the file and folder structure from the default Protostar template. This is a fairly standard file structure for a basic Joomla! template.
<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>Visão do diretório de arquivos do J3 Protostar
Module Positions
The available Module Positions that can be used in the template are defined in this area.
These are the module positions defined in the default Protostar template:
<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>The list of positions are contained within the <positions> tag. Each <position> tag creates a module position that is available from the position list in the module manager and in other areas of Joomla! where module positions can be selected.
The simple format of the position list means it can be easily customized. For example, to add a new module position to the list, simply add a new <position> tag inside the <positions> tag with a unique name using all lowercase letters with no spaces. Keep in mind, this only adds the position to the backend and additional development in other template files is required to render the new position on the front end.
Languages
Some templates may include language files to allow translation of static text in the template. Notice that the language folder is defined and the two language files inside are also included. Even though the language folder was defined earlier, these files need their own definitions. This method tells Joomla! where the language files that contain strings used by the template reside.
The first file holds the language file for text that will be viewed by the User. The second file, with the .sys, or system, extension is for text that will be viewed in the Administrator area.
This is the language folder and file structure from the default Protostar template:
<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>Language strings are used in templates and throughout Joomla! for the purpose of utilizing the extensive international language support features in Joomla!. This method provides developers and users with a relatively simple method to translate any text that is used in templates and extension screens. Joomla! will check the language files for any language strings that are used and load the corresponding text in the language chosen by the user in place of the string. In this instance, there are only files for English (en-GB), any text translations in other languages must be provided by Users or Developers before they can be used by Joomla!.
More information about Language Files:
Parâmetros
A template may offer display options and other parameters that can be chosen by the Administrator in the Template Manager. For instance, the default Protostar template allows the Administrator to change various colors, fonts and add a logo, these parameters are found under the Advanced tab, which is also defined and created by the XML parameters.
Template parameters are contained inside a <config> tag, which contains a <fields> tag with a name attribute of "params". Inside the <fields> tag is where the parameter groups and individual parameters are defined. The <fieldset> tag is used to create groups of parameters. Individual parameters are defined with the <field> tag.
Each <fieldset>, and each <field> parameter within a <fieldset>, require a unique name defined by the name attribute. This name defines the parameter itself and is used to pass settings to the front end files. Each parameter should also contain a label attribute and description attribute. The label text appears with the parameter in the settings screen to identify what the setting is used for and more detailed information can be included in the description.
A parameter field can be virtually any type of form input with corresponding options, this is selected by the type attribute. Any necessary options, such as radio button or select choices, are defined in <option> tags. CSS class names can be defined with the class attribute and a default parameter setting can be defined using the default attribute.
Below are the parameter definitions in the default Protostar Template. In this example, all Labels, Descriptions and Options are using language string definitions from the Language files defined in the previous section, as well as some from the Joomla! core, so they can be translated into different languages as necessary.
<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>The Protostar template illustrates a few different ways that XML can be used in a template interface, but there are many more possibilities. In this example, the <fieldset name="advanced"> tag encloses all of the parameters and it uses the name attribute to create the "Advanced" tab in the interface. All that is necessary to create another tab in the interface is another <fieldset> tag with a different name attribute. With this in mind, it is relatively simple to create as many additional tabs and parameters as necessary in a template.