Geavanceerde onderwerpen

From Joomla! Documentation

Revision as of 08:26, 24 June 2015 by MartijnM (talk | contribs) (Created page with "Templates Handleidingen")
(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)
Other languages:
Deutsch • ‎English • ‎Nederlands • ‎español • ‎français • ‎български • ‎فارسی • ‎हिन्दी • ‎বাংলা • ‎中文(台灣)‎
Joomla! 
2.5 & 3.x
serie

Hoe worden templates uitgevoerd?

Templates worden uitgevoerd in een proces van 2 fases die volledig gebruik maken van de PHP parser om aanzienlijke flexibiliteit en performance te bieden aan de template ontwerper. Templates worden uitgevoerd binnen de context van het document object zodat het $this object altijd een instantie van de JDocument class is.

Voordat de template-uitvoering begint, is de component uitgevoerd en de uitvoer daarvan is gebufferd voor later gebruik.

De template uitvoering gaat dan als volgt:

  • template parameters (indien aanwezig) worden geladen.
  • template taal (indien aanwezig) wordt geladen.
  • indien de legacy-modus aan staat dan worden de instellingen-variabelen gekopieerd als globalen.
  • Het template bestand (index.php) wordt geladen en uitgevoerd (door PHP). De uitvoer wordt gebufferd. Dit is fase 1 van het proces van 2 fases. Alles tussen <?php en ?> tags wordt uitgevoerd als PHP-code. Alles buiten deze tags is uitvoer maar wordt anders genegeerd. Aangezien de uitvoer gebufferd wordt, wordt er op dit moment niets naar de webbrowser gestuurd.
  • er wordt naar een favicon.ico bestand gezocht, eerst in de Joomla! root-map, daarna in de template root-map. De laatste vervangt de eerste indien gevonden.
  • De gebufferde uitvoer uit fase 1 wordt nu geanalyseerd op <jdoc:include> elementen. Dit is fase 2 van het proces. Voor ieder gevonden jdoc-element, wordt de juiste renderer class geladen en zijn render-methode wordt aangeroepen. De uitvoer van de render-methode vervangt het <jdoc:include> element zelf in de uitvoer-buffer. In geval van module render-classes triggert dit het verwerken van de modules en het bufferen van hun uitvoer.
  • Bepaalde template-specifieke HTTP headers worden toegevoegd aan de lijst met headers om in de uitvoer te komen.
  • Controle wordt dan teruggegeven aan het JApplication object, dat de rest van het proces, om de nu gegenereerd pagina terug naar de browser van de gebruiker te krijgen, afhandelt.


Systeem foutpagina's

Foutpagina templates

Joomla! gebruikt standaard speciale templates als het een foutbericht moet geven. Deze staan in de templates/system map. Voor server-niveau status-codes zijn ze genoemd naar de statuscode die is ontstaan. De standaard systeem foutpagina's zijn:

  • 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)

Bovendien zijn deze systeem foutpagina's ook beschikbaar:

  • templates/system/component.php (niet zeker wanneer dit wordt gebruikt)
  • templates/system/offline.php wordt gebruikt om het "site staat offline" bericht te genereren.

Let op dat jdoc:include elementen niet in deze foutpagina's worden opgenomen.

De statuscodes zijn gedefinieerd als onderdeel van het HTTP protocol in RFC2616. Zie, voor meer informatie over HTTP statuscodes: http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html

Stijlen van de foutpagina's

Deze pagina's kunnen worden gestijld met behulp van de volgende CSS classes:

  • errorboxheader
  • errorboxbody
  • techinfo


Eigen foutpagina's

Joomla! gebruikt het templates/system/error.php bestand om verschillende HTTP Status fouten af te handelen, inclusief "403 Forbidden", "404 Not Found", en "500 Internal Server" fouten. U kunt, indien gewenst, het foutresultaat stijlen.

Het is belangrijk te begrijpen dat error.php een onafhankelijk bestand is van het Joomla! CMS maar afhankelijk is van het Joomla! Platform. Plugins kunnen het bestand niet gebruiken. U kunt geen modules opnemen of <jdoc:include> statements gebruiken.

Overriden van de Systeem foutresultaten

Kopieer, om de systeem foutresultaten te overriden, het templates/system/error.php bestand naar uw templates/<template-name> map.

Als Joomla! hem vindt, zal het het error.php bestand vanuit het huidige template gebruiken, in plaats van het systeem bestand.

U kunt de pagina naar wens opmaken om het op uw template aan te laten sluiten.

Overriden van de systeem stijling

Kopieer, als u de stijl wilt veranderen het templates/system/css/error.css bestand naar uw templates/<template-name>/css map. Bewerk vervolgens uw templates/<template-name>/error.php bestand om te verwijzen naar de nieuwe locatievan de stijlsheet door deze regel als volgt aan te passen:

<link rel="stylesheet" href="<?php echo $this->baseurl; ?>/templates/system/css/error.css" type="text/css" />

Wijzig daarna error.css, naar wens volgens uw stijl eisen.

Het aanpassen van foutboodschappen

U kunt conditionele logica toevoegen om de teruggegeven boodschap aan te passen, afhankelijk van de specifieke foutcode.

Hier is een voorbeeld hoe een 404 fout af te vangen en een eigen boodschap te geven.

<?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 statuscode

Als een pagina wordt opgevraagd op uw site, dan geeft de server een HTTP statuscode terug naar aanleiding van het verzoek. Joomla! geeft een '200 - de server gaf de pagina terug' foutboodschap pagina. Dit is een probleem voor degenen die werken met Google Webmaster Services en een sitemap hebben.

Als u wilt dat Joomla! een statuscode terug geeft voor de fout, dan kan dat door als volgt de volgende logica voor de DOCTYPE regel toe te voegen:

<?php 
if ($this->error->getCode() == '404') {
	header("HTTP/1.0 404 Not Found");
} ?>

Meer HTTP statuscode informatie

Het gebruiken van de Theme Header en Footer op de standaard foutpagina

Joomla 1.5 Indien u de foutboodschap in thema ontwerp wilt zien en niet naar een foutpagina URL wilt worden geleid of de HTML overnemen in het foutpagina template, dan is hier een manier om uw thema template op de foutpagina te laten werken.

Zet allereerst de volgende code in templates/<template-name>/error.php:

<?php
// no direct access
defined( '_JEXEC' ) or die( 'Restricted access' );

include dirname(__FILE__) . "/index.php";
?>

Bewerk daarna het volgende in templates/<template-name>/index.php:

1. Vind de volgende code in index.php

<jdoc:include type="head" />

en vervang het door het volgende

<?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. Vind de volgende code in index.php

<jdoc:include type="component" />

en vervang het door het volgende

<?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; ?>

Nu werkt uw thema template ook op de foutpagina's.

Let op: Module includes in het template zullen niet werken op foutpagina's, op deze manier aangemaakt (maar werken op andere pagina's).

Het gebruik van modules in foutpagina's

Modules kunnen niet op dezelfde manier opgenomen worden op foutpagina's als de template's index.php omdat u <jdoc:include> statements niet kunt gebruiken. Er is een alternatief door JModuleHelper te gebruiken.

Om een enkele module via de titel op te nemen, kunt u gebruiken:

if (JModuleHelper::getModule('menu')) { 
    echo $doc->getBuffer('module', 'menu');
}

Om meerdere modules op een positie op te nemen, kunt u gebruiken:

$modules = JModuleHelper::getModules( 'footer_3' );
$attribs['style'] = 'xhtml';
foreach ($modules AS $module ) {
    echo JModuleHelper::renderModule( $module, $attribs );
}


JavaScript toevoegen

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

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/


Hoe browser mogelijkheden bepalen?

Verschillende web browsers tonen soms iets anders, doordat ze een pagina anders genereren. Om deze reden wilt u weten welke browser een bezoeker gebruikt, om browser specifieke CSS te gebruiken.

Het volgende JavaScript definieert een eenvoudig browser detectie-object welke de naam en de versie van de browser bepaalt door de navigator.userAgent string te decoderen.

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;
    }
  }
}

U creëert een instantie van dit object, om dit in een script te gebruiken:

var browser = new browserDetect();

Het property browser.name geeft daarna de naam van de browser (MSIE, Opera, Netscape of Firefox), browser.mainVersion geeft de hoofdversie en browser.minorVersion geeft het punt versienummer.

U moet echter weten dat dit niet waterdicht is en het is in het algemeen beter (is de mening van de schrijver) om het schrijven van browser-specifieke code zo veel mogelijk te voorkomen.


Stylesheets toevoegen voor andere uitvoer apparaten

Met CSS stylesheets, is het mogelijk een set richtlijnen (stijlen) te gebruiken afhankelijk van het apparaat dat gebruikt wordt om webpagina's te bekijken.

Mediatypen

De herkende mediatypen zijn:

  • all - Geschikt voor alle apparatuur.
  • aural - Voor spraak synthesizers.
  • braille - Bedoeld voor braille apparatuur.
  • embossed - Bedoeld voor pagina braille printers.
  • handheld - Bedoeld voor draagbare apparatuur.
  • print - Gebruikt voor het opmaken van af te drukken pagina's.
  • projection - Bedoeld voor geprojecteerde presentaties, bijvoorbeeld projectors of het afdrukken op transparanten.
  • screen - Voornamelijk bedoeld voor kleur computerschermen.
  • tty - Bedeold voor media die een fixed-pitch teken-raster gebruiken, zoals telex, terminals, of draagbare apparatuur met beperkte weergave mogelijkheden. Auteurs moeten geen pixel eenheden gebruiken met het "tty" mediatype.
  • tv - Bedoeld voor televisie apparatuur (lage resolutie, kleur, beperkt scroll=bare schermen, geluid beschikbaar).

Voorbeelden

U kunt een mediatype aan een CSS declaratie koppelen met de volgende syntaxis

@media print {
  body { 
    font-size: 12pt;
    font-color: #000000; 
  }
}

Om meer dan één declaratie style te koppelen aan meer dan één mediatype:

@media print, handheld{
  body { 
    font-size: 12pt;
    font-color: #000000;
  }
  img {
    max-width: 100%;
    height: auto;
  }
}

De richtlijnen kunnen worden gebruikt in het hoofd CSS bestand of in een apart stylesheet voor een bepaald mediatype. Het CSS bestand moet opgenomen worden in de <head> sectie van het template (het volgende komt uit het Joomla! Beez template):

<link rel="stylesheet" href="<?php echo $this->baseurl ?>/templates/beez/css/print.css" type="text/css" media="Print" />

De aanbevolen manier om een stylesheet in te voegen is:

<?php
$document = JFactory::getDocument();
 $tpath = $this->baseurl . '/templates/' . $this->template;
$document->addStyleSheet( $tpath . '/css/print.css', 'text/css', 'print'); // arguments: $path, $type, $media
?>

Op deze manier zorgt u ervoor dat de stylesheet aan het document wordt toegevoegd en dat deze toegankelijk is voor plugins (bijv. voor het combineren en comprimeren van stylesheets).