Migrating a Template from Joomla 1.5 to 3.x/de

Wenn Du ein manuelles Update eines 1,5-Templates in Betracht ziehst, gibt es einige Dinge über die Du nachdenken solltest.

Erstens, welche Funktionen brachst Du? Um die Änderungen am Template durchzuführen, brauchst Du Grundkenntnisse in PHP, HTML, XML, CSS und eventuell etwas Javascript. Wenn Du nicht über ein grundlegendes Verständnis dieser Fähigkeiten verfügst, frische Deine Fähigkeiten auf oder suche Dir einen Profi.

Zweites, die notwendigen Erweiterungen Deines Templates musst Du mit den neuen Funktionen oder Design-Änderungen die Du in Deiner Migration geplant hast abwägen. Nutzt die Änderung das neue Bootstrap Framework Styling das in Joomla! 3 verfügbar ist? Oder muß die neue Webseite exakt der alten entsprechen. Einige neue Änderungen bei Joomla! 3 sind verpflichtend ( das bedeutet Dein Template wird nicht geladen ) andere sind Verbesserungen und Dein Template wird geladen, sieht aber vielleicht nicht so aus, wie Du möchtest.

Zum Zweck dieses Dokuments nehmen wir das einfachste Beispiel und schlagen vor, ein Spiegelbild des aktuellen 1.5 Templates anzufertigen. Für komplexere Templates oder gravierende Anpassungen musst Du möglicherweise einiges recherchieren oder jemanden der mehr Erfahrung mit Templates hat einstellen.

Überprüfung der Grundlagen von Templates

Einige Dinge haben sich nicht geändert. Du brauchst noch immer die gleichen Grundlagen eines Joomla! Templates: Die Ordner-Struktur ist eins dieser Dinge. Minimal auf der Root-Ebene brauchst Du 2 Dateien: "index.php" und "templateDetails.xml" ( beachte diesen Fall! ). Die meisten Templates enthalten noch mindestens 2 Ordner: einen Ordner "Bilder" in dem befinden sich alle Grafiken die Dein Template verwendet und einen Ordner für das CSS-Styling. Erweiterte Templates könnten Ordner enthalten mit Bezeichnungen wie z.B.: "html" für Komponenten - und Modul-Anpassungen, einen "language" Ordner für eigene Sprach-Overrides, "javascript" um benutzerdefinierte javascript-Routinen zu halten.

Vergewissere Dich, dass die Ordner in der XML-Datei des Templates existieren, die Du zu Joomla! hochlädst. Wenn Du eine Datei oder Ordner im XML deklarierst, dann muss dies auch vorhanden sein oder dein Template wird nicht geladen.

Ein Beispiel für eine Verbesserung in den Versionen ab 1,5 ist der Wegfall dass alle Dateinamen in den Unterordnern aufgelistet werden müssen. Für die Templates in Joomla! 3 genügt einfach eine Liste der Ordnernamen.

Für mehr Informationen über die Grundlagen eines Templates findest Du unter diesem Link: Erstellung eines einfachen Joomla! Templates

XML-Datei Änderungen

Was muss in der Datei templateDetails.xml geändert werden ( Template Manifest Datei )

Die Template Manifest-Datei enthält die Informationen, die Joomla! zum Installieren des Templates benötigt. Die XML-Manifest-Datei wurde fast vollständig seit Version 1.5 verändert, also mach Dich mit den Änderungen und Grundlagen vertraut. Dein Template wird nicht geladen, wenn diese Datei ist nicht korrekt ist.

Dokument Referenz-Typ Tag & der Installations/Erweiterungs Tag

Der XML Install Tag ist jetzt ein “Extension” Tag. Darüber hinaus ist jede Bezugnahme zum DOCTYPE Tag oder Versions-Nummer müssen sich jetzt auf Version 3.0 beziehen.

Die alten Zeilen sind etwa so wie diese:

<!DOCTYPE install PUBLIC "-//Joomla! 1.5//DTD template 1.0//EN" "http://dev.joomla.org/xml/1.5/template-install.dtd">
<install version="1.5" type="template">

Dies muss nun so Aussehen:

<!DOCTYPE install PUBLIC "-//Joomla! 2.5//DTD template 1.0//EN" "http://www.joomla.org/xml/dtd/2.5/template-install.dtd">
<extension version="3.1" type="template" client="site">

Ordner- und Datei Tags

Diese Regel ist immer treu geblieben ist und ist es noch immer: Wenn Du die Dateinamen oder Ordner in der XML-Datei auflistest müssen diese auch im hochgeladenen Template existieren. Dies hat sich in Joomla! 3 nicht geändert. Was sich geändert hat ist die 1,5 Anforderung, dass alle Dateinamen in einem Ordner aufgelistet werden sollen. Jetzt ist nur die Angabe des Namens des Ordners nötig. Zum Beispiel, die zuvor unter 1.5 in der XML genannten Dateinamen wurden wie folgt einzeln aufgeführt:

<images>
	<filename>images/arrow.png</filename>
	<filename>images/arrow2.png</filename>
	<filename>images/arrow3.png</filename>
	<filename>images/author.gif</filename>
</images>

Für ein Joomla! 3 - Template genügt diese Erklärung:

<folder>images</folder>

Modul Tags

Für 1.5 wurden die Modul-Positionen im Template definiert. Dies hat sich nicht geändert. Diese müssen noch immer aufgeführt werden.

Parameter

Parameter sind eine optionale Funktion von Templates, die dem Template-Autor Optionen für das Styling im Joomla! Administrationsbereich bieten. Bei Joomla! 1.5 Templates sind die Parameter in einer "parameters.ini" Datei auf der Root Ebene gelistet. Diese Datei wurde entfernt und die Parameter werden nun als Tags in der XML-Datei gespeichert.

Hier ist ein Beispiel für den Inhalt einer parameters.ini-Datei:

colorVariation=blue
backgroundVariation=blue

Um die Parameter in Joomla! 3 zu definieren, füge die folgenden Zeilen in der XML-Datei hinzu:

      <config>
		<fields name="params">
		     <fieldset name="advanced">
				<field name="colorVariation" class="" type="color" default="#08C"
					label="TPL PROTOSTAR COLOR LABEL"
					description="TPL PROTOSTAR COLOR DESC" />
				<field name="backgroundVariation" class="" type="color" default="#F4F6F7"
					label="TPL PROTOSTAR BACKGROUND COLOR LABEL"
					description="TPL PROTOSTAR BACKGROUND COLOR DESC" />
		    </fieldset>
		</fields>
     </config>

Für komplexere Parameter XML-Tags, solltest Du tiefer in der detaillierten Dokumentation nachlesen. Beachte auch, dass die index.php-Datei mit Bezug zu den Parameter-Variablen auch geändert werden muss .

Nutze diese Links für mehr Informationen über:

• Standard form field und Parameter Typen
• Erstellung einer einfachen templateDetails.xml Datei

index.php Datei

Was muss in der index.php -Datei geändert werden?

Index.php files are as widely varied as there are designers and programmers that write them. The index.php in a template for Joomla 3 is the compilation of the many versions that came before including 1.5, 1.6, 1.7,2.5, etc. This template file is the "bloodstream" providing life to your skin, and it has access to every piece of Joomla's framework available and can use these pieces to manipulate what your site is going to look like to your users. This has always been true and still is. Template designers and programmers have taken advantage of this fact in previous versions and will continue to, so this file needs the most careful research and planning.

Changes that were made to the framework for Joomla 3 may cause problems to some older templates and when rendered could produce errors. Other templates may not have referenced the same piece of framework at all and work fine with almost no changes. For example, a 1.5 template that accesses the variable value "frontpage" to determine if they are on the home page or not. This doesn't work in Joomla 3. (See table below for code ) If a template referenced a changed piece or not will be the determining factor of how many issues you will have when trying to implement your updated template.

Be prepared to make some changes based on “best practices”. Although your index.php may function, it needs to be secure and execute efficiently. Consider that every page served to your audience uses the index.php file so make sure you are familiar with the recommended methods for the Joomla framework and building blocks for a template. A thorough study of the index.php file in both the Protostar Template and the Beez Template that is included with the Joomla 3 installation package can provide examples and best practices for more complex templates.

Richtlinien

Hier sind einige Richtlinien für die Joomla! 3-Template index.php-Datei:

1. Again, some things haven't changed: all index.php templates need to start with this statement:

<?php defined( '_JEXEC' ) or die;?>

True for Joomla 1.5 and still true for Joomla 3.

2. For Joomla 3 the recommended DOCTYPE ( Document Type Declaration ) should be HTML5 as this is used throughout Joomla 3. Here is an example:

<!DOCTYPE html>
    <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en" dir="ltr">

3. To make use of Joomla 3's application framework:

In 1.5 access to the framework was done through the $mainframe variable. You might see something like this:

<?php require_once (‘includes/../framework.php' );
$mainframe =& JFactory::getApplication('site'); ?>

replace it with this:

<?php $app = Jfactory::getApplication();?>

4. To retrieve the Heading code use this statement directly beneath your heading tag and follow it with your stylesheets. This has not changed with the Joomla 3 but always bears repeating:

<jdoc:include type="head" />

5. To retrieve the sitename in 1.5 you might see this:

<?php echo $mainframe->getCfg('sitename');?>

For Joomla 3 use this code:

<?php  $app->getCfg('sitename');?>

6. Error Codes and Messages:

A better methodology for retrieving error codes is in place for Joomla 3. You might see this in your 1.5 template:

<?php $this->error->code; ?>

replace it with this Joomla 3 convention:

<?php $this->error->getCode(); ?>

For error messages, this is a typical 1.5 statement:

<?php $this->error->message; ?>

Replace it with this statement for Joomla 3

<?php $this->error->getMessage(); ?>

7. To access the template parameters in replace code that looks like this:

<?php $color = $this->params->get('colorVariation'); ?>

with this recommended methodology:

<?php $app = Jfactory::getApplication();
$template = $app->getTemplate(true);
$params = $template->params;
$color = $params->get('colorVariation'); ?>

This will work equally well as an example:

<?php $app = Jfactory::getApplication();
$params = $app->getParams();
$color = $params->get('colorVariation'); ?>

8. Access to the Global Document Object classes in the index.php template file is typically coded this way:

<?php $doc = Jfactory::getDocument(); ?>

This statement is the same in Joomla 3. However, it is valid to note that this statement is not necessary to access the page classes so it might be there or it might not depending on the original programmer. For example: given the code:

<?php $doc =& JFactory::getDocument();
echo 'Current title is: ' . $doc->getTitle(); ?>

is equivalent to this code:

<?php echo 'Current title is: ' . $this->getTitle(); ?>

Die Zusammenfassung

The table below is a quick reference of code differences between a Joomla 1.5 and Joomla 3.x template's index.php file.

Description	In a 1.5 Template (index.php) you might see	Recommended J3.x Template (index.php) code
First Line	<?php defined( '_JEXEC' ) or die( 'Restricted access' );?>	No change
DOCTYPE	<?php echo '<?xml version="1.0" encoding="utf-8"?'.'>'; ?><!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="<?php echo $this->language; ?>" lang="<?php echo $this->language; ?>" dir="<?php echo $this->direction; ?>" >	<!DOCTYPE html> <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="<?php echo $this->language; ?>" lang="<?php echo $this->language; ?>" dir="<?php echo $this->direction; ?>">
Access to Joomla Framework	$app = JFactory::getApplication(); OR require_once (‘includes/../framework.php' ); $mainframe =& JFactory::getApplication('site');	No change but needs to look like this: $app = JFactory::getApplication();
Retrieve HTML headers from Joomla	<jdoc:include type="head" />	No change
Retrieve the Sitename	$mainframe->getCfg('sitename');	$app->get('sitename');
Retrieve Error Codes	$this->error->code	$this->error->getCode();
Retrieve Error Messages	$this->error->message	$this->error->getMessage();
Retrieve System Messages	$this->getBuffer('message')	<jdoc:include type="message" />
Active Language	$this->language;	$doc->language;
View	JRequest::getVar( 'view' )	$app->input->getCmd('view');
Task	JRequest::getVar( 'task' )	$app->input->getCmd('task');
Layout	JRequest::getVar( 'layout' )	$app->input->getString('layout', 'default');
ID	JRequest::getVar( 'id' )	With alias: $app->input->getString('id'); Only ID: $app->input->getInt('id');
Homepage detection	<?php if(JRequest::getVar( 'view' ) == 'frontpage') ?>	<?php $menu = $app->getMenu(); if($menu->getActive() == $menu->getDefault()) ?>
Main Content	<jdoc:include type="component" />	No change
Modules & Positions	<jdoc:include type="modules" name="right" style="xhtml" />	No change
Retrieve Base URL	$url = clone(JURI::getInstance()); echo $this->baseurl; JURI::root()*;	JURI::base(); $this->baseurl;
Access to Document Page Classes	$doc = JFactory::getDocument();	No change However, use of "$this->" is equivalent.
Access to Template Parameters	echo $this->params->get('colorVariation');	No change

Bootstrap-Styling und Joomla! 3

To incorporate the new Bootstrap Styling ( 2.3.2 ) into your updated template, use these three lines at the very top of your index.php, replacing the one line php block.

<?php defined( '_JEXEC' ) or die;
JHtml::_('bootstrap.framework');
JHtml::_('bootstrap.loadCss', true, $this->direction); ?>

After these statements, you can add Bootstrap (2.3.2 ) classes wherever you need to and take advantage of the Bootstrap Framework offered in Joomla 3.

Man kann es nicht oft genug sagen ...

There are many variations of coding practices and your success with translating a 1.5 template into a template fit for Joomla 3 depends on the complexity of the old and new design, and the original coding. Your template might have been previously converted from Joomla 1.0! Your best strategy is to research the documentation available and become familiar with the Protostar and Beez templates in Joomla 3. Techniques for coding and structuring in these 2 templates have undergone the scrutiny of the Joomla community and volunteer developers – the true experts on how to best make your template secure and function reliably.

Referenzen

• Creating a basic Joomla! template
• Creating a basic index file
• Creating a basic templateDetails.xml file
• Understanding Joomla! templates
• Standard form field and parameter types
• Talk:Creating a basic Joomla! template