Themen für Fortgeschrittene
From Joomla! Documentation
Wie werden Templates ausgeführt?
Templates werden in einem 2-Phasen-Processs ausgeführt, der vollen Gebrauch vom PHP-Parser macht um dem Template-Designer beachtliche Felxibilität und Leistung zu bieten. Templates werden in der Umgebung des Dokumenten-Objekts ausgeführt so dass das $this-Objekt immer die Instantiierung der JDocument-Klasse ist.
Bevor die Ausführung des Templates beginnt, wird die Komponente ausgeführt und seine Ausgabe für später zwischengespeichert.
Dann geht die Ausführung der Vorlage folgendermaßen weiter:
- template-Parameter (falls vorhanden) werden geladen.
- die template-Sprache (falls vorhanden) wird geladen.
- wenn der legacy-Modus an ist, dann werden die Konfigurations-Variablen als globals kopiert.
- die Vorlage-Datei (index.php) wird geladen und ausgeführt (durch PHP). Der Ausgang ist gepuffert. Dies ist Phase 1 des 2-Phasen-Prozess. Alles zwischen <?php and ?> tags wird als PHP-code ausgeführt. Alles, was außerhalb dieser tags wird ausgegeben, aber ansonsten ignoriert. Da die Ausgabe gepuffert ist, wird in diesem Stadium nichts an den Client-Webbrowser gesendet.
- eine favicon.ico Datei wird zuerst im Wurzelverzeichnis der Joomla!-Installation, dann im Wurzelverzeichnis des Templates gesucht. Das letztere wird das erste überschreiben.
- die Ausgabe, die in Phase 1 gepuffert wurde, wird jetzt nach <jdoc:include>-Elementen durchsucht. Für jedes gefundene jdoc-Element wird die geeignete renderer-Klasse geladen und seine render-mathode wird aufgerufen. Die Ausgabe der render-Methode erstetzt die <jdoc:include>-Elemente selbst im Ausgabepuffer. Im Falle der Modul-renderer-Klassen, löst dies die Ausführung der Module und die Pufferung der Ausgabe aus.
- Bestimmte template-spezifische HTTP-Header werden der Liste der Header die ausgegeben werden hinzugefügt.
- Die Steuerung wird dann an das JApplication Objekt zurückgegeben, das den Rest des Prozesses, die jetzt gerenderte Seite zurück zu dem Client-Webbrowser zu bekommen, durchführt.
Fehlerseiten vom System
Vorlagen für Fehlerseiten
Standardmäßig verwendet Joomla! spezielle Templates, wenn es eine Fehlermeldung auslösen muss. Diese befinden sich im Verzeichnis templates/system. Bei Statuscodes auf Serverebene werden diese nach dem Statuscode benannt, der ausgelöst wird. Die Standard-Systemfehlerseiten sind:
- templates/system/403.php (Status code: 403 Forbidden)
- templates/system/404.php (Status code: 404 Not Found)
- templates/system/500.php (Status code: 500 Internal Server Error)
Darüber hinaus sind auch diese Systemfehlerseiten verfügbar:
- templates/system/component.php (nicht sicher, wann dies verwendet wird)
- templates/system/offline.php wird verwendet, um die Nachricht "Site ist offline" darzustellen.
Hinweis: Elemente des Typs jdoc:include werden in diesen Fehlerseiten nicht geparst.
Die Statuscodes sind als Teil des HTTP-Protokolls in RFC2616 definiert. Für weitere Informationen zu HTTP-Statuscodes siehe: http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html
Styling für Fehlerseiten
Diese Seiten können mit Hilfe der folgenden CSS-Klassen gestylt werden:
- errorboxheader
- errorboxbody
- techinfo
Benutzerdefinierte Fehlerseiten
Joomla! uses the templates/system/error.php file to handle several HTTP Status errors, including "403 Forbidden", "404 Not Found", and "500 Internal Server" errors. You can style the error results, if desired.
It is important to understand that error.php is an independent file from the Joomla! CMS but dependent on the Joomla! Platform. Plugins do not run on the file. You cannot include modules or use <jdoc:include> statements.
Overriding the System Error Results
To override the system error results, copy the templates/system/error.php file into your templates/<template-name> directory.
If it finds one, Joomla! will use the error.php file from the current template, in place of the system file.
You can format the page, as desired, to match your template.
Overriding the System Styling
If you want to change the styling, copy the templates/system/css/error.css file into your templates/<template-name>/css directory. Next, update your templates/<template-name>/error.php file to reference the new location of the stylesheet by changing this line, accordingly:
<link rel="stylesheet" href="<?php echo $this->baseurl; ?>/templates/system/css/error.css" type="text/css" />
Then, simply change the error.css, as desired, for your styling requirements.
Customizing Error Messages
You can add conditional logic to vary the message returned, dependent upon the specific error code.
Here is an example of how to trap a 404 error and provide a custom message.
<?php if ($this->error->getCode() == '404') { ?>
<div id="errorboxheader">Page not found</div>
<div id="errorboxbody"><p>Sorry! That page cannot be found.</p>
</div>
</div>
<?php } ?>
HTTP Status Code
When a request is made for a page on your site, the server returns an HTTP status code in response to the request. Joomla! returns a '200 - the server successfully returned the page' for error pages. This is problematic for those working with Google Webmaster Services and trying to get a sitemap resolved.
If you want Joomla! to return a status code for the error, you can do so by adding logic before the DOCTYPE line, as follows:
<?php
if ($this->error->getCode() == '404') {
header("HTTP/1.0 404 Not Found");
} ?>
More HTTP Status Code Information
If you want to see the error page in theme design and don't like redirecting to error page URL or duplicating HTML in the error page template, here is a way to apply your theme template to the error page.
First, put the following code in templates/<template-name>/error.php:
<?php
// no direct access
defined( '_JEXEC' ) or die( 'Restricted access' );
include dirname(__FILE__) . "/index.php";
?>
Then make the following edits to templates/<template-name>/index.php:
1. Find the following code in index.php
<jdoc:include type="head" />
and replace it with the following
<?php if (!$this->error->getCode()) : ?>
<jdoc:include type="head" />
<?php else : ?>
<title><?php echo $this->error->getCode() ?> - <?php echo $this->title; ?></title>
<?php endif; ?>
2. Find the following code in index.php
<jdoc:include type="component" />
and replace it with the following
<?php if ($this->error->getCode()) : /* check if we are on error page, if yes - display error message */ ?>
<p><strong><?php echo $this->error->getCode() ?> - <?php echo $this->error->message ?></strong></p>
<p><strong><?php echo JText::_('JERROR_LAYOUT_NOT_ABLE_TO_VISIT'); ?></strong></p>
<ol>
<li><?php echo JText::_('JERROR_LAYOUT_AN_OUT_OF_DATE_BOOKMARK_FAVOURITE'); ?></li>
<li><?php echo JText::_('JERROR_LAYOUT_SEARCH_ENGINE_OUT_OF_DATE_LISTING'); ?></li>
<li><?php echo JText::_('JERROR_LAYOUT_MIS_TYPED_ADDRESS'); ?></li>
<li><?php echo JText::_('JERROR_LAYOUT_YOU_HAVE_NO_ACCESS_TO_THIS_PAGE'); ?></li>
<li><?php echo JText::_('JERROR_LAYOUT_REQUESTED_RESOURCE_WAS_NOT_FOUND'); ?></li>
<li><?php echo JText::_('JERROR_LAYOUT_ERROR_HAS_OCCURRED_WHILE_PROCESSING_YOUR_REQUEST'); ?></li>
</ol>
<p><strong><?php echo JText::_('JERROR_LAYOUT_PLEASE_TRY_ONE_OF_THE_FOLLOWING_PAGES'); ?></strong></p>
<ul>
<li><a href="<?php echo $this->baseurl; ?>/index.php" title="<?php echo JText::_('JERROR_LAYOUT_GO_TO_THE_HOME_PAGE'); ?>"><?php echo JText::_('JERROR_LAYOUT_HOME_PAGE'); ?></a></li>
</ul>
<p><?php echo JText::_('JERROR_LAYOUT_PLEASE_CONTACT_THE_SYSTEM_ADMINISTRATOR'); ?>.</p>
<?php else : ?>
<jdoc:include type="component" />
<?php endif; ?>
Now your theme template is applied to error pages too.
Note: Module includes in template will not work on error page created by this method (but will work on other pages).
Using modules in error pages
Modules cannot be included in error pages in the same way as the template's index.php because you cannot use <jdoc:include> statements. There is an alternative way using JModuleHelper.
To include a single module by title, you can use:
if (JModuleHelper::getModule('menu')) {
echo $doc->getBuffer('module', 'menu');
}
To include multiple modules by position, you can use:
$modules = JModuleHelper::getModules( 'footer_3' );
$attribs['style'] = 'xhtml';
foreach ($modules AS $module ) {
echo JModuleHelper::renderModule( $module, $attribs );
}
JavaScript hinzufügen
Note that a more up-to-date Joomla document covering this topic can be found at Adding JavaScript and CSS to the page, although it currently doesn't cover the more advanced topics at the bottom of this page.
JavaScript (auch bekannt als ECMAScript) ist eine Skriptsprache, die hauptsächlich bei der Entwicklung von client-seitigen Websites verwendet wird, um die Benutzerfreundlichkeit zu erweitern und zu verbessern. Joomla bietet Entwicklern einfach zu verwendende Mechanismen, um JavaScript in ihre Erweiterungen unter Verwendung bestehender API-Methoden einzubinden. Es gibt eine Reihe von Methoden, um JavaScript in Joomla-Erweiterungen einzubinden. Einige davon werden im Folgenden beschrieben.
Verwendung
Es gibt drei Methoden, um JavaScript über die Joomla-API in Ihren Code einzubetten: JDocument::addScriptDeclaration, JDocument::addScript und script. Diese Methoden sollten entweder in der View-Klasse Ihrer Komponente <yourcomponent>/views/<yourview>/view.html.php oder im Template-Skript <yourcomponent>/views/<yourview>/tmpl/<yourtemplate>.php oder im Falle eines Moduls in dessen Template-Skript <yourmodule>/tmpl/<yourtemplate>.php aufgerufen werden.
Inline JavaScript
JavaScript-Code-Blöcke können direkt innerhalb des Anzeige-Templates einer Komponente oder eines Moduls mit der Methode addScriptDeclaration der Klasse JDocument deklariert werden:
<?php
$document = JFactory::getDocument();
$document->addScriptDeclaration('
window.event("domready", function() {
alert("An inline JavaScript Declaration");
});
');
?>
Externes JavaScript
Alternativ können Sie Ihr JavaScript auch in eine separate Datei auslagern. Die Auslagerung Ihres JavaScripts in eine externe Datei kann die Lesbarkeit Ihres Templatecodes verbessern, insbesondere wenn das JavaScript sehr umfangreich oder komplex ist.
Es gibt zwei Möglichkeiten, eine JavaScript-Datei über die Joomla! API einzubinden. Die erste beinhaltet die Verwendung der Methode addScript der Klasse JDocument:
<?php
$document = JFactory::getDocument();
$document->addScript('/media/system/js/sample.js');
?>
Die zweite verwendet die Methode script der Klasse JHTML:
<?php
// Add the path parameter if the path is different than 'media/system/js/'
JHTML::script('sample.js', 'templates/custom/js/');
?>
Die API hat sich in 3.x geändert, so dass der zweite Parameter kein String sein darf. Wenn Sie diese Methode wirklich benötigen, müssen Sie den absoluten Link zu Ihrer JavaScript-Datei angeben:
<?php
JHtml::script(Juri::base() . 'templates/custom/js/sample.js');
?>
You can use options in a third parameter. This example shows the options version and relative . The file example should be saved in the folder media/com_example/js/example.min.js. So you do NOT need to insert the js in the path you insert as second parameter.
<?php
JHtml::_('script', 'com_example/example.min.js', array('version' => 'auto', 'relative' => true));
?>
Beschreibung==
Die Methoden JDocument::addScriptDeclaration, JDocument::addScript und script der Joomla-API betten JavaScript über das jdoc head-Tag in Joomlas index.php ein:
<jdoc:include type="head"/>
Die Verwendung der Methoden JDocument::addScript oder script zum Einbetten von JavaScript-Includes führt dazu, dass die index.php das folgende HTML ausgibt:
<head>
...
<script type="text/javaScript" src="/media/system/js/sample.js"></script>
...
</head>
Der Aufruf der Klassenmethode JDocument::addScriptDeclaration ergibt folgendes HTML:
<head>
...
<script type="text/javaScript">
window.addEvent("domready", function() {
alert("Embedded block of JS here");
});
</script>
...
</head>
Die Verwendung dieser Methoden wird dringend empfohlen, um eine andere Skriptsprache (JavaScript) vom Haupt-PHP-Code zu unterscheiden und sicherzustellen, dass alle JavaScript-Tags korrekt zwischen den <head></head>-Tags eingebettet sind. Und im Falle von JDocument::addScript und JHTML::script wird sichergestellt, dass eine JavaScript-Datei nur einmal enthalten ist (d. h. es gibt keine.js-Dateiduplikation).
Verwendung eines JavaScript-Frameworks
Ein Javascript-Framework stellt Entwicklern generische Funktionen zur Verfügung, um verschiedene Codierungsaufgaben konsistent und plattformunabhängig zu handhaben. Ein Framework ermöglicht es dem Entwickler, die Feinheiten der Implementierung einer bestimmten Funktion in verschiedenen Webbrowsern zu ignorieren und sich auf die Anforderungen der Software zu konzentrieren.
Zwei Javascript-Frameworks werden als Teil von Joomla 3.x; jQuery und Mootools zur Verfügung gestellt. jQuery ist ein neu eingeführtes Framework, das sich in Joomlas neues Bootstrap HTML-Framework integriert; Mootools ist Joomlas veraltete Javascript-Bibliothek, die nun durch jQuery ersetzt wird und für die Rückwärtskompatibilität mit Erweiterungen von Drittanbietern enthalten ist.
In den meisten Fällen sollten Sie bei der Entwicklung von Javascript in Ihren Erweiterungen oder Templates ein Framework verwenden, das mit der Joomla-API einfach zu integrieren ist.
Joomla 3.x jQuery ==
Bitte beachten Sie das Handbuch unter Javascript-Frameworks in Joomla 3.x für Informationen über die Einbindung eines Frameworks in Joomla 3.x.
Joomla 1.5/2.5 Mootools
Wenn Sie keinen Javascript-Code pflegen, der Mootools nutzt, und keine Erweiterung für Joomla 2.5 oder früher entwickeln, wird empfohlen, stattdessen jQuery zu verwenden.
Zuerst müssen Sie den Mootools-Code in Ihre Erweiterung aufnehmen. Um das Mootools-Framework in Ihre Erweiterung aufzunehmen, fügen Sie den folgenden Code zu Ihrer Datei view.html.php oder der Template-Datei hinzu:
FÜR JOOMLA 1.5
JHTML::_('behavior.mootools');
FÜR JOOMLA 2.5
JHtml::_('behavior.framework');
Der obige Code führt zu dem gleichen Ergebnis wie die ähnliche jQuery-Framework-Anweisung, d. h. er stellt sicher, dass Mootools korrekt und nur einmal eingebunden wird.
Dann ist die Verwendung von Mootools fast identisch mit jQuery:
JFactory::getDocument()->addScriptDeclaration('
window.addEvent("domready", function() {
alert($("list").getElements("li").length);
});
');
Weitere Informationen über Mootools finden Sie unter http://mootools.net/. Die API-Dokumentation finden Sie unter http://mootools.net/docs/core.
== Wichtige Hinweise für externe Entwickler ==
Wenn Sie ein benutzerdefiniertes Template oder eine Erweiterung erstellen und eine benutzerdefinierte JS-Datei hinzufügen müssen, stellen Sie sicher, dass Sie wichtige Abhängigkeiten wie Jquery oder Mootools vor Ihren eigenen JS-Dateien hinzufügen. JS-Framework-Dateien müssen immer vor allen anderen Dateien geladen werden, um sicherzustellen, dass sie zuerst ausgeführt werden. Ansonsten enden andere Dateien, die vor den benötigten Frameworks geladen werden, vermutlich mit JS-Ausnahmen.
Einige Templates wie Protostar oder Beez fügen alle Abhängigkeiten ein, die Sie benötigen, indem sie Funktionen wie z. B.
JHtml::_('bootstrap.framework');
verwenden, um Jquery + Bootstrap zu laden. Aber Sie sollten sich in Ihren Erweiterungen oder eigenen Template-Overrides nicht darauf verlassen. Stellen Sie immer sicher, dass Ihre Erweiterung oder Ihr Override die Abhängigkeiten lädt, die Sie benötigen, bevor das Template es tut. ich werde später erklären, warum:
Zum Beispiel ein Template-Override, welches eine JS-Datei mit einigen Jquery-Skripten einfügt und die auf allen Seiten, auf denen dieses Template-Override verwendet wird, ansprechende Dinge tut. In diesem Fall sollte dies im oberen Abschnitt der Override-Datei deklariert werden:
JHtml::_('jquery.framework'); $doc->addScript('templates/'.$this->template.'/js/fancy-script.js');
Wenn Sie eine Erweiterung entwickeln und planen, diese im Joomla!-Extension-Directory zu veröffentlichen, sollten Sie folgendes tun:
if($params->get('add_extension_resources', false)) { JHtml::_('jquery.framework'); $doc->addScript('media/com_fancy/js/fancy-script.js'); }
Die Verwendung der Bedingungsklausel, um zu entscheiden, ob die Ressourcen einer Erweiterung hinzugefügt werden sollen oder nicht, wird stark empfohlen und als gute Praxis betrachtet. Sie gibt Drittentwicklern, die die einzubindenden Erweiterungsressourcen nicht verwenden wollen und benutzerdefinierte/geänderte Dateien verwenden, mehr Flexibilität. Sie müssen keine Umgehungslösungen und Hacks für Joomla! verwenden, um die ursprünglichen Erweiterungsressourcen zu entfernen und Duplikate und Konflikte zu vermeiden.
Erklärung
Wenn Sie den Quellcode der index.php aus der Protostar-Template überprüfen, können Sie sehen, dass die Anweisung
JHtml::_('bootstrap.framework');
weit vor folgender Anweisung hinzugefügt wird.
<jdoc:include type="head" />
dies führt zu der Annahme, dass die Framework-Dateien und Ihre 3rd-Party-Dateien mit Methoden wie z. B.
$doc->addScript('templates/'.$this->template.'/js/fancy-script.js'); $doc->addScript('media/com_fancy/js/fancy-script.js');
in der richtigen Reihenfolge an der richtigen Stelle hinzugefügt werden, aber das ist nicht der Fall, weil Erweiterungsdateien und Template-Überschreibungsdateien zuerst und die index.php-Datei des aktuellen Templates als letzte verarbeitet wird. Dies führt dazu, dass Ihre benutzerdefinierten JS-Dateien zuerst eingefügt werden und die aus dem Template eingefügten Frameworkdateien danach eingefügt werden.
Dies geschieht, weil die Joomla! API (z. B. $doc->addScript) ein Array verwendet, um die JS-Dateipfade zu speichern. Sie werden im Dokument in der gleichen Reihenfolge gerendert, wie sie in dieses Array eingefügt wurden (FIFO-Stapel).
Sobald ein Dateipfad in das Array eingefügt wird und ein anderer API-Aufruf versucht, die gleiche Datei einzufügen, wird diese Aktion ignoriert, um Duplikate zu vermeiden. Das bedeutet auch, dass die Reihenfolge der Dateien nicht verändert wird, wenn versucht wird, dieselben Dateien mehrmals einzufügen.
Die Verwendung von
JHtml::_('jquery.framework'); $doc->addScript('templates/'.$this->template.'/js/fancy-script.js');
in Ihren benutzerdefinierten Template-Overrides und Erweiterungen ist erforderlich und verursacht keinen Schaden oder Konflikt mit dem Aufruf
JHtml::_('bootstrap.framework');
in der index.php Datei Ihres Templates.
Externe Links
https://api.joomla.org/cms-2.5/classes/JHtmlBehavior.html#method_framework
https://api.joomla.org/cms-3/classes/JHtmlBehavior.html#method_framework
http://en.wikipedia.org/wiki/JavaScript
http://www.w3schools.com/js/default.asp
Wie kann ich die Browserfähigkeiten ermitteln?
Verschiedene Webbrowser zeigen manchmal Unterschiede in der Darstellung einer Seite. Aus diesem Grund muss manchmal ermittelt werden, welchen Browser ein Besucher benutzt, um browserspezifisches CSS zu verwenden.
Das folgende JavaScript definiert eine einfache Funktion zur Browser-Erkennung, die den Namen und die Version des Browsers bestimmt, indem sie den String navigator.userAgent
dekodiert.
function browserDetect()
{
var browserNames=new Array("Opera", "MSIE","Netscape","Firefox");
this.name="NK";
this.mainVersion="NK";
this.minorVersion="NK";
for (var i=0; i< browserNames.length; i++)
{
var pattern='('+browserNames[i]+')'+'.([0-9]+)\.([0-9]+)';
var myRegExp=new RegExp(pattern);
if (myRegExp.test(navigator.userAgent))
{
var results=myRegExp.exec(navigator.userAgent);
this.name=results[1];
this.mainVersion=results[2];
this.minorVersion=results[3];
break;
}
}
}
Um dies in einem Skript zu verwenden, wird eine Instanz dieses Objekts erstellt:
var browser = new browserDetect();
Die Eigenschaft browser.name
gibt dann den Namen des Browsers (MSIE, Opera, Netscape oder Firefox), browser.mainVersion
die Hauptversionsnummer und browser.minorVersion
die Minor-Versionsnummer an.
Es ist jedoch zu beachten, dass dies nicht narrensicher ist, und es ist im Allgemeinen besser (nach Meinung dieses Autors), das Schreiben von browserspezifischem Code so weit wie möglich zu vermeiden.
Stylesheets für andere Ausgabegeräte hinzufügen
Mit CSS-Stylesheets ist es möglich, eine Reihe von Anweisungen (Stile) zu verwenden, die von dem Gerät abhängen, mit dem die Webseiten aufgerufen werden.
Media-Typen
Zulässige Media-Typen sind:
- all - Wird auf alle Geräte angewandt.
- aural - Für Sprachsynthesizer.
- braille - Vorgesehen für Braille-Tastsensoren.
- embossed - Vorgesehen für seitengestützte Blindenschriftdrucker.
- handheld - Vorgesehen für Handheld-Geräte.
- print - Wird zum Formatieren gedruckter Seiten verwendet.
- projection - Vorgesehen für projizierte Präsentationen, z. B. Projektoren, oder zum Drucken auf Transparentfolien.
- screen - Hauptsächlich vorgesehen für farbige Computerbildschirme.
- tty - Vorgesehen für Geräte, die ein Zeichengitter mit festem Zeichenabstand verwenden, z. B. Fernschreiber, Terminals oder tragbare Geräte mit eingeschränkter Anzeigefunktion. Autoren sollten mit dem Medientyp "tty" keine Pixeleinheiten verwenden.
- tv - Vorgesehen für Fernsehgeräte (niedrige Auflösung, Farbe, Bildschirme mit eingeschränkter Bildlauffunktion, Ton verfügbar).
Beispiele
Ein Media-Typ kann durch folgende Syntax einer CSS-Deklaration zugewiesen werden
@media print {
body {
font-size: 12pt;
font-color: #000000;
}
}
Um mehr als einen Deklarationsstil mehr als einem Media-Typ zuzuordnen:
@media print, handheld{
body {
font-size: 12pt;
font-color: #000000;
}
img {
max-width: 100%;
height: auto;
}
}
Die Anweisungen lassen sich in der CSS-Hauptdatei oder in einem separaten Stylesheet für einen bestimmten Media-Typ verwenden. Es muss eine Anweisung zum Einbinden der CSS-Datei im<head>-Abschnitt des Templates geben (folgender stammt aus dem Joomla! Beez-Template):
<link rel="stylesheet" href="<?php echo $this->baseurl ?>/templates/beez/css/print.css" type="text/css" media="Print" />
Um ein Stylesheet einzubinden, wird folgender Weg empfohlen:
<?php
$document = JFactory::getDocument();
$tpath = $this->baseurl . '/templates/' . $this->template;
$document->addStyleSheet( $tpath . '/css/print.css', 'text/css', 'print'); // arguments: $path, $type, $media
?>
Auf diese Weise kann sichergestellt werden, dass das Stylesheet zum Dokument hinzugefügt wird und auch Plugins darauf zugreifen können (z. B. zum Kombinieren und Komprimieren von Stylesheets).