JavaScript toevoegen
From Joomla! Documentation
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 (ook bekend als ECMAScript) is een scripttaal hoofdzakelijk gebruikt bij client-side website ontwikkeling om de gebruikerservaring uit te breiden en verbeteren. Joomla voorziet ontwikkelaars van makkelijk te gebruiken mechanismen om JavaScript op te nemen in hun extensies met behulp van bestaande API methodes. Er zijn een aantal methodes om JavaScript op te nemen in uw Joomla extensies; enkele zijn hieronder beschreven.
Gebruik
Er zijn drie methodes om JavaScript op te nemen in uw code met behulp van de Joomla API; JDocument::addScriptDeclaration, JDocument::addScript en script. Deze methodes moeten of aangeroepen worden in uw View class van de component <yourcomponent>/views/<yourview>/view.html.php of het template script <yourcomponent>/views/<yourview>/tmpl/<yourtemplate>.php of, in geval van een module, in het template script <yourmodule>/tmpl/<yourtemplate>.php.
Inline JavaScript
Blokken JavaScript-code kunnen direct binnen een component of module's display template worden gedeclareerd met behulp van de addScriptDeclaration methode van de JDocument class:
<?php
$document = JFactory::getDocument();
$document->addScriptDeclaration('
window.event("domready", function() {
alert("An inline JavaScript Declaration");
});
');
?>Externe JavaScript
Als alternatief wilt u misschien uw JavaScript in een apart bestand onderbrengen. Uw JavaScript onderbrengen in een extern bestand kan uw template code makkelijker leesbaar maken, vooral als de JavaScript lang of ingewikkeld is.
Er zijn twee manieren om een JavaScript-bestand op te nemen met behulp van de Joomla! API. De eerste bestaat uit het gebruik van de addScript methode van de JDocument class:
<?php
$document = JFactory::getDocument();
$document->addScript('/media/system/js/sample.js');
?>De tweede gebruikt de script methode van de JHTML class :
<?php
// Add the path parameter if the path is different than 'media/system/js/'
JHTML::script('sample.js', 'templates/custom/js/');
?>De API is veranderd in 3.x, de tweede parameter kan daarom geen string zijn. Als u deze methode echt wilt gebruiken, dan moet u de absolute link opnemen naar uw JavaScript bestand:
<?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));
?>Beschrijven
De Joomla API JDocument::addScriptDeclaration, JDocument::addScript en script methodes sluiten JavaScript in Joomla's index.php in via de jdoc head tag:
<jdoc:include type="head"/>Het gebruik van de JDocument::addScript of script methodes om JavaScript op te nemen zou resulteren dat in de index.php de volgende HTML gegenereerd wordt:
<head>
...
<script type="text/javaScript" src="/media/system/js/sample.js"></script>
...
</head>Het aanroepen van de class methode JDocument::addScriptDeclaration zou de volgende HTML genereren:
<head>
...
<script type="text/javaScript">
window.addEvent("domready", function() {
alert("Embedded block of JS here");
});
</script>
...
</head>Het gebruik van deze methodes wordt zeer aangeraden aangezien het duidelijk een andere scripttaal (JavaScript) scheidt van de PHP code en zorgt dat alle JavaScript juist opgenomen wordt tussen de <head></head> tags en in in geval van JDocument::addScript en JHTML::script ervoor zorgt dat een JavaScript bestand slechts eenmaal opgenomen wordt (er zijn bijvoorbeeld geen dubbele .js bestanden).
Een JavaScript Framework gebruiken
Een Javascript framework voorziet ontwikkelaars van generieke functionaliteit voor het afhandelen van diverse codeer-taken op een vertrouwde, consequente en platform-onafhankelijke manier. Een framework laat de ontwikkelaar de complexiteit van het implementeren van een bepaalde functie in verschillende webbrowsers vergeten en laat hem zich focussen op de eisen aan de software.
Twee Javascript Frameworks worden verstrekt als onderdeel van Joomla 3.x; jQuery en Mootools. jQuery is een nieuw geïntroduceerd framework dat integreert met Joomla's nieuwe Bootstrap HTML framework; Mootools is Joomla's oude Javascript-bibliotheek wat nu vervangen wordt door jQuery en is opgenomen om backwards-compatibiliteit van extensies van derden.
In bijna alle gevallen zou u een framework moeten gebruiken bij het ontwikkelen van Javascript in uw extensies of templates en er een opnemen is erg eenvoudig met de Joomla's API.
Joomla 3.x jQuery
Raadpleeg alstublieft de handleiding Javascript Frameworks in Joomla 3.x voor informatie over het opnemen van een framework in Joomla 3.x
Joomla 1.5/2.5 Mootools
Tenzij u JavaScript-code onderhoud die gebruik maakt van Mootools of als u een extensie ontwikkelt voor Joomla 2.5 of eerder wordt aangeraden jQuery te gebruiken.
Eerst moet u de Mootools code in uw extensie opnemen. Om het Mootools framework in uw extensie op te nemen moet u de volgende code aan uw view.html.php of tmpl bestand toevoegen:
VOOR JOOMLA 1.5
JHTML::_('behavior.mootools');VOOR JOOMLA 2.5
JHtml::_('behavior.framework');Bovenstaande code resulteert in dezelfde uitkomst als het vergelijkbare jQuery framework statement; het zorgt dat Mootools juist opgenomen is en slechts één keer.
Daarna is Mootools gebruiken bijna hetzelfde als jQuery:
JFactory::getDocument()->addScriptDeclaration('
window.addEvent("domready", function() {
alert($("list").getElements("li").length);
});
');Meer informatie over Mootools is beschikbaar op http://mootools.net/. Bezoek, voor API documentatie, http://mootools.net/docs/core.
Belangrijke opmerkingen voor 3rd party ontwikkelaars
Zorg, indien u een eigen template override of extensie maakt die een apart .JS bestand toevoegt, dat u belangrijke afhankelijkheden zoals Jquery of Mootools toevoegt voor uw eigen .JS bestanden. JS framework bestanden moeten altijd geladen worden voor elke andere bestanden, om zeker te weten dat ze eerst uitgevoerd worden, anders eindigen andere bestanden, die geladen zijn voor het framework, waarschijnlijk in een JS exception.
Sommige templates zoals Protostar of Beez voegen alle afhankelijkheden die ze nodig hebben toe via functies zoals
JHtml::_('bootstrap.framework');
om Jquery + Bootstrap te laden, maar u moet niet op dit feit vertrouwen in uw extensies of eigen template-overrides. Zorg er altijd voor dat uw extensies of eigen overrides de afhankelijkheden die u nodig heeft laadt voor het template dat doet, ik leg later uit waarom:
Als u bijvoorbeeld een eigen template override heeft dat een .JS bestand invoegt met Jquery scripts dat mooie dingen doet op alle pagina's waar die template-override wordt gebruikt. In dat geval moet u dit declareren bovenaan het override bestand:
JHtml::_('jquery.framework');
$doc->addScript('templates/'.$this->template.'/js/fancy-script.js');
Als u een extensies van derden ontwikkelt, welke u in de Joomla! Extensie Directory wilt plaatsen, dan zou u iets als dit moeten doen:
if($params->get('add_extension_resources', false))
{
JHtml::_('jquery.framework');
$doc->addScript('media/com_fancy/js/fancy-script.js');
}
De voorwaardelijke clausule om te beslissen om wel of niet de extensiebronnen toe te voegen wordt ten sterkste aangeraden en wordt beschouwd als good practice want het geeft flexibiliteit aan derde partij ontwikkelaars die uw extensiebronnen niet willen gebruiken en eigen/aangepaste bestanden gebruiken zonder te hoeven stoeien met Joomla! door omweggetjes en hacks te vinden om uw oorspronkelijke extensiebronnen te verwijderen om duplicaten en conflicten te voorkomen.
Uitleg
Als u de broncode bekijkt van de index.php van het Protostar template, dan ziet u dat het statement
JHtml::_('bootstrap.framework');
toegevoegd is lang voor het statement
<jdoc:include type="head" />
dit doet u misschien denken dat framework bestanden en uw bestanden van derden die methodes als deze gebruiken
$doc->addScript('templates/'.$this->template.'/js/fancy-script.js');
$doc->addScript('media/com_fancy/js/fancy-script.js');
toegevoegd worden in de juiste volgorde en op de juiste plek, maar dat is niet het geval, omdat extensie-bestanden en template override-bestanden eerst uitgevoerd worden en dat het index.php bestand van uw huidige template als laatste uitgevoerd wordt. Dit zorgt dat uw eigen .JS bestanden eerst ingevoegd worden en de framework bestanden ingevoegd vanuit het template daarna ingevoegd worden.
Dit gebeurt omdat de Joomla! API (zoals $doc->addScript) een array gebruikt om de JS bestandspaden en ze worden in het document gegenereerd in dezelfde volgorde als ze in die array gezet zijn (FIFO stack). Het is ook zo, dat als een bestandpad ingevoegd is en een andere API-aanroep probeert dezelfde waarde toe te voegen, dan wordt deze actie genegeerd, om dubbelen te vermijden. Het betekent ook dat de volgorde niet verandert wordt als dezelfde bestanden meerdere keren ingevoegd worden.
Na dat gezegd te hebben, zal dit
JHtml::_('jquery.framework');
$doc->addScript('templates/'.$this->template.'/js/fancy-script.js');
in uw eigen templates overrides en extensies, verplicht zijn en geen schade of conflicten veroorzaken bij de aanroep
JHtml::_('bootstrap.framework');
in uw template index.php bestand.
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