JavaScript hinzufügen

From Joomla! Documentation

This page is a translated version of the page Adding JavaScript and the translation is 100% complete.

Other languages:
български • ‎বাংলা • ‎Deutsch • ‎English • ‎español • ‎eesti • ‎فارسی • ‎français • ‎हिन्दी • ‎Nederlands • ‎português do Brasil • ‎中文(台灣)‎
Joomla! 
2.5 & 3.x
Serie

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

Joomla 2.5 https://api.joomla.org/cms-2.5/classes/JHtmlBehavior.html#method_framework

Joomla 3.x https://api.joomla.org/cms-3/classes/JHtmlBehavior.html#method_framework

http://en.wikipedia.org/wiki/JavaScript

http://www.w3schools.com/js/default.asp

http://mootools.net/

http://jquery.com/