Questions avancées
From Joomla! Documentation
Comment les templates sont-ils exécutés ?
Les templates sont exécutés au cours d'un processus en deux étapes permettant la pleine utilisation de l'analyseur PHP pour fournir flexibilité et des performances aux concepteurs de templates. Les templates sont exécutés dans le contexte d'un document objet de sorte que l'objet $this est toujours l'instanciation de la classe JDocument.
Avant le début de l'exécution du template, le composant aura été exécutés et le résultat mis en mémoire tampon pour une utilisation ultérieure.
L'exécution du template s'opère alors comme suit :
- les paramètres du template (s'ils en existent) sont chargés.
- la langue du template (si elle existe) est chargée.
- si le mode legacy est enclenché, alors les variables de configuration sont copiés en tant que variables globales.
- le fichier de template (index.php) est chargé et exécuté (en PHP). La sortie est mise en mémoire tampon. Ceci est la première phase du processus en deux étapes. Tout ce qui se trouve entre les balises <?php et ?> est exécuté en tant que code PHP. Tout ce qui se trouve à l'extérieur de ces balises est ignoré. A ce stade et puisque la sortie est mise en mémoire tampon, rien n'est encore envoyé au navigateur web du client.
- un fichier favicon.ico est recherché, en premier lieu à la racine du répertoire Joomla! puis à la racine du répertoire de template. Le cas échéant, le dernier trouvé va se substituer au précédent.
- la sortie qui a été mise en mémoire tampon lors de la phase 1 va maintenant être analysée pour les éléments <jdoc:include>. Ceci est la phase 2 du processus. Pour chaque élément jdoc trouvé, la classe de rendu appropriée sera chargée et sa méthode de rendu appelée. La sortie de la méthode du rendu remplace l'élément <jdoc:include> lui-même dans la mise en mémoire tampon de la sortie. Dans le cas de classes de rendu de modules, cela permet d'enclencher l'exécution des modules ainsi que leur mise en mémoire tampon de leur sortie.
- certaines entêtes HTTP spécifiques aux templates sont ajoutées à la liste des entêtes en sortie.
- Le contrôle est ensuite transmis à l'objet JApplication qui va gérer le reste du processus d'obtention du rendu de la page web pour la renvoyer au navigateur web.
Les pages d'erreurs système
Templates de pages d'erreur
Par défaut Joomla! utilise des templates spéciaux quand il a besoin d'afficher un message d'erreur. Ces templates se trouvent dans le répertoire templates/system. Pour les codes de statut de niveau serveur ceux-ci sont nommés en fonction du niveau de statut. Les pages par défaut d'erreurs système sont :
- 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)
En outre, ces pages d'erreur sont également disponibles :
- templates/system/component.php
- templates/system/offline.php est utilisée pour afficher le message lors de la mise hors-ligne du site.
Notez que les éléments jdoc:include ne sont pas traités dans ces pages d'erreur.
Les codes de statut sont définis dans le cadre du protocole HTTP dans RFC2616. Pour de plus amples informations sur les codes de statut HTTP, veuillez consulter : http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html
Les style des pages d'erreur
Le style de ces pages peut être modifié à l'aide des classes CSS :
- errorboxheader
- errorboxbody
- techinfo
Pages d'erreurs personnalisées
Joomla! utilise le fichier templates/system/error.php afin de gérer plusieurs statuts d'erreurs HTTP y compris les erreurs "403 Forbidden", "404 not Found" et "500 Internal Server". Si vous le souhaitez, il est possible de définir le style du message d'erreur.
Il est important de comprendre que le fichier error.php est un fichier indépendant du CMS Joomla! mais dépendant du framework Joomla. Les plugins ne fonctionnent avec le fichier. Vous ne pouvez pas inclure des modules ou encore utiliser la déclaration <jdoc:include>.
Substitution des résultats d'erreurs système
Pour remplacer les résultats d'erreurs système, il convient de copier le fichier templates/system/error.php dans votre dossier templates/<nom du template>.
Si une erreur est trouvée, Joomla va utiliser le fichier error.php du template utilisé en lieu et place du fichier système.
Vous pouvez formater la page comme vous le souhaitez afin de correspondre à votre template.
Substitution des styles du système
Si vous souhaitez changer les styles, copiez le fichier templates/system/css/erreur.css dans votre dossier templates/<nom du template>/css. Ensuite, mettez à jour votre fichier templates/<nom du template>/error.php afin de référencer la feuille de style en changeant cette ligne en conséquence ː
<link rel="stylesheet" href="<?php echo $this->baseurl; ?>/templates/system/css/error.css" type="text/css" />
Ensuite, il suffit de modifier le fichier error.css comme vous le souhaité et en fonction de vos exigences de style.
Personnalisation des messages d'erreur
En fonction du code d'erreur spécifique, vous pouvez ajouter des logiques conditionnelles afin de varier les messages retournés.
Voici un exemple sur la façon d'intercepter une erreur 404 et de proposer un message personnalisé.
<?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 } ?>
Code de statut HTTP
Lorsqu'une requête est faite pour une page de votre site, le serveur renvoie un code d'état HTTP en réponse à la demande. Joomla! retourne un '200 - le serveur va renvoyer une page spécifique pour les erreurs. Cette situation est problématique pour ceux qui travaillent avec les services Google Webmaster et tentent de résoudre les questions de sitemap.
Si vous voulez que Joomla! retourne un code de statut d'erreur, vous pouvez le faire en ajoutant la logique suivante avant la ligne du DOCTYPE :
<?php
if ($this->error->getCode() == '404') {
header("HTTP/1.0 404 Not Found");
} ?>
Plus d'informations sur les statuts HTTP
- Création d'une page d'erreur 404 personnalisée
- HTTP/1.1 Définition des codes de statuts
- Liste des codes HTTP
Utiliser les thèmes d'en-tête et de pied de page sur la page d'erreur standard
Si vous souhaitez voir votre page d'erreur suivant le même style de votre template et ne voulez pas d'une redirection vers l'URL d'une page d'erreur ou dupliquer le HTML dans la page d'erreur de votre template, voici un processus permettant d'appliquer le style de votre template à la page d'erreur.
Tout d'abord, placez le code suivant dans templates/<nom du template>/error.php:
<?php
// no direct access
defined( '_JEXEC' ) or die( 'Restricted access' );
include dirname(__FILE__) . "/index.php";
?>
Ensuite, opérez les modifications suivantes dans templates/<nom du template>/index.php :
1. Trouver le code suivant dans index.php
<jdoc:include type="head" />
et remplacez le par le suivant ː
<?php if (!$this->error->getCode()) : ?>
<jdoc:include type="head" />
<?php else : ?>
<title><?php echo $this->error->getCode() ?> - <?php echo $this->title; ?></title>
<?php endif; ?>
1. Trouver le code suivant dans le fichier index.php
<jdoc:include type="component" />
et remplacez le par le suivant ː
<?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; ?>
Maintenant, votre template est également appliqué aux pages d'erreur.
Note : les modules intégrés dans le template ne fonctionneront pas sur une page d'erreur créée en suivant cette méthode, mais ils fonctionneront sur les autres pages.
L'utilisation de modules dans les pages d'erreur
Les modules ne peuvent pas être inclus dans les pages d'erreur de la même manière que dans l'index.php d'un template car vous ne pouvez pas utiliser les déclarations <jdoc:include>. Il existe une alternative grâce à l'utilisation de JModuleHelper.
Pour inclure un module unique par titre, vous pouvez utiliser :
if (JModuleHelper::getModule('menu')) {
echo $doc->getBuffer('module', 'menu');
}
Pour inclure plusieurs modules par position, vous pouvez utiliser :
$modules = JModuleHelper::getModules( 'footer_3' );
$attribs['style'] = 'xhtml';
foreach ($modules AS $module ) {
echo JModuleHelper::renderModule( $module, $attribs );
}
Ajouter du JavaScript
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.
Le JavaScript (également connu comme ECMAScript) est un langage de scripts principalement utilisé côté client et développé afin d'étendre et d'améliorer l'expérience utilisateur. Joomla! propose aux développeurs des mécanismes faciles à utiliser pour inclure du JavaScript dans leurs extensions en utilisant les méthodes API. Il existe différentes méthodes pour intégrer du JavaScript dans vos extensions Joomla! et certaines vont être présentées ci-dessous.
Utilisation
Il existe trois méthodes pour l'intégration de JavaScript dans votre code à l'aide de l'API Joomla : JDocument::addScriptDeclaration, JDocument::addScript et script. Ces méthodes doivent être appelées soit dans votre classe View de composant <yourcomponent>/views/<yourview>/view.html.php ou par un script de template <yourcomponent>/views/<yourview>/tmpl/<yourtemplate>.php ou dans le cas d'un module, dans son script de template <yourmodule>/tmpl/<yourtemplate>.php.
JavaScript en ligne
Les blocs de code JavaScript peuvent être déclarés directement dans la vue de template pour un composant ou un module par l'utilisation des classes : JDocument de la méthode addScriptDeclaration :
<?php
$document = JFactory::getDocument();
$document->addScriptDeclaration('
window.event("domready", function() {
alert("An inline JavaScript Declaration");
});
');
?>
JavaScript externe
Comme alternative, vous pouvez séparer votre code JavaScript en le plaçant dans un fichier séparé. Séparer votre code JavaScript dans un fichier externe peut rendre le code de votre template plus facile à lire surtout si le JavaScript est longue et complexe.
Il existe deux façons d'inclure un fichier JavaScript à l'aide de l'API Joomla. La première consiste à utiliser la classe JDocument de la méthode addScript :
<?php
$document = JFactory::getDocument();
$document->addScript('/media/system/js/sample.js');
?>
La seconde utilise la classe JHTML de la méthode script :
<?php
// Add the path parameter if the path is different than 'media/system/js/'
JHTML::script('sample.js', 'templates/custom/js/');
?>
L'API a changé dans 3.x, de sorte que le deuxième paramètre ne peut pas être une chaîne de caractères. Si vous avez vraiment besoin d'utiliser cette méthode, vous devez inclure le lien absolut vers votre fichier JavaScript :
<?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));
?>
Description
Les méthodes des API Joomla! JDocument::addScriptDeclaration, JDocument::addScript et script permettent d'intégrer du JavaScript dans le fichier Joomla! index.php via la balise d'en-tête :
<jdoc:include type="head"/>
Utiliser les méthodes JDocument::addScript ou script pour implémenter JavaScript dans le fichier index.php donnera le code HTML suivant :
<head>
...
<script type="text/javaScript" src="/media/system/js/sample.js"></script>
...
</head>
L'appel de la méthode de la classe JDocument::addScriptDeclaration générera le code HTML suivant :
<head>
...
<script type="text/javaScript">
window.addEvent("domready", function() {
alert("Embedded block of JS here");
});
</script>
...
</head>
L'utilisation de ces méthodes est fortement recommandée car elle différencie clairement un autre langage de script (JavaScript) d'avec le langage principal PHP, ce qui garantit que tous les JavaScript seront correctement intégrés entre les balises <head></head>. Dans le de JDocument::addScript et JHTML::script, cela permettra de s'assurer qu'un fichier JavaScript ne sera intégré qu'une seule fois (il n'y aura pas de fichiers .js doublons).
À l'aide d'un Framework JavaScript
Un framework Javascript fournit aux développeurs une fonctionnalité générique pour le traitement des différentes tâches de codage dans un cadre familier, cohérent et indépendant de la plateforme. Un framework permet au développeur d'oublier les subtilités de la mise en œuvre d'une fonction spécifique pour différents navigateurs web et ainsi de rester concentrés sur les exigences du logiciel.
Deux Frameworks JavaScript sont disponibles dans Joomla! 3.x à savoir jQuery et Mootools. jQuery est un framework nouvellement introduit dans le cadre de l'intégration du nouveau framework HTML Bootstrap. Mootools est une bibliothèque JavaScript héritée qui est désormais remplacée par jQuery et uniquement intégrée pour des questions de rétro-compatibilité avec les extensions tierces.
Dans presque tous les cas vous devriez utiliser un framework lorsque vous travailler avec JavaScript dans le cadre du développement de vos extensions ou templates et leur intégration est très simple à mettre en oeuvre avec les API Joomla.
Joomla! 3.x et jQuery
Pour plus d'informations sur la façon d'intégrer un framework dans Joomla! 3.x, veuillez consulter le guide sur les Frameworks JavaScript dans Joomla 3.x.
Joomla! 1.5/2.5 et Mootools
Sauf si vous devez assurer la maintenance d'un code JavaScript utilisant Mootools ou si vous développez une extension pour des versions 2.5 ou antérieures de Joomla, il est recommandé d'utiliser jQuery à la place.
Tout d'abord, il vous faudra inclure le code Mootools dans votre extension. Pour inclure le framework Mootools dans votre extension, vous devez ajouter le code suivant à votre fichier view.html.php ou tmpl :
POUR JOOMLA! 1.5
JHTML::_('behavior.mootools');
POUR JOOMLA! 2.5
JHtml::_('behavior.framework');
Le code ci-dessus donnera le même résultat que lors d'une déclaration jQuery. Cela permet de s'assurer que Mootools est inclus correctement et une fois uniquement.
Ensuite, l'utilisation de Mootools est presque identique à celle de jQuery :
JFactory::getDocument()->addScriptDeclaration('
window.addEvent("domready", function() {
alert($("list").getElements("li").length);
});
');
Vous pouvez consulter plus d'informations à propos de Mootools sur http://mootools.net/. Pour la documentation de l'API, veuillez consulter : http://mootools.net/docs/core.
Notes importantes pour les développeurs d’extensions tierces
Dans le cadre de la création d'un override de template ou d'une extension qui impose d'ajouter un fichier JS personnalisé, assurez-vous d'ajouter d'importantes dépendances, telles que Jquery ou Mootools avant votre fichier JS personnalisé. Les fichiers de framework JS doivent toujours être chargés avant tout autres fichiers afin de s'assurer qu'ils soient exécutés en premier, sinon d'autres fichiers qui seront chargés avant pourraient apparaître comme des exceptions JS.
Certains templates comme Protostar ou Beez intègrent toutes les dépendances dont vous avez besoin en utilisant des fonctions comme :
JHtml::_('bootstrap.framework');
pour charger Jquery + Bootstrap, mais vous ne devriez pas procéder ainsi pour vos extensions ou vos surcharges de templates. Assurez-vous que votre extension ou votre surcharge charge les dépendances dont vous avez besoin, avant que le template ne le fasse, je vous expliquerai pourquoi plus tard :
Par exemple, vous avez une surcharge personnalisée de template qui a besoin de l'intégration de fichier JS avec des scripts Jquery sur toutes les pages de remplacement de votre template. Dans ce cas, vous devez le déclarer au début de la section de votre fichier de surcharge :
JHtml::_('jquery.framework'); $doc->addScript('templates/'.$this->template.'/js/fancy-script.js');
Si vous développez une extension tierce que vous souhaiter proposer sur le Joomla! Extensions Directory, vous devrez faire quelque chose comme ceci :
if($params->get('add_extension_resources', false)) { JHtml::_('jquery.framework'); $doc->addScript('media/com_fancy/js/fancy-script.js'); }
La clause conditionnelle pour décider d'ajouter ou non les ressources de l'extension est très fortement encouragée et cela est considéré comme étant une bonne pratique car elle permet une flexibilité aux développeurs d'extensions tierces qui ne veulent pas utiliser vos ressources d'extension mais plutôt d'utiliser des fichiers modifiés/personnalisés sans avoir à se battre contre Joomla! en créant des solutions de rechange et des hacks pour être en mesure de retirer les ressources de vos extensions qui seront des doublons ou généreront des conflits.
Explication
Si vous regardez le code source de l'index.php du template Protostar, vous pouvez voir que les déclarations
JHtml::_('bootstrap.framework');
est ajoutée avant la déclaration
<jdoc:include type="head" />
cela peut vous faire penser que les fichiers framework et vos fichiers tierces utilisent les méthodes comme
$doc->addScript('templates/'.$this->template.'/js/fancy-script.js'); $doc->addScript('media/com_fancy/js/fancy-script.js');
sera ajouté dans le bon ordre, au bon endroit, mais ce n'est pas le cas car les fichiers d'extension ou les surcharges de template sont exécuté en premier et le fichier index.php de votre template actuel est exécuté en dernier. Cela fera que vos fichiers JS personnalisés seront insérés en premier et que les fichiers du framework seront insérés après.
Ceci se produit parce que l'API Joomla! (tel que $doc->addScript) utilise un tableau array pour stocker les chemins des fichiers JS et ils seront rendus dans le document dans le même ordre qu'ils auront été insérés dans cet array (pile FIFO). Egalement, une fois qu'un chemin d'accès au fichier est inséré dans le tableau et qu'un autre appel d'API tente d'insérer le même fichier, de cette action est ignorée pour éviter les doublons. Cela signifie également que l'ordre des fichiers n'est pas modifié lorsque les mêmes fichiers tenteront d'être insérés plusieurs fois.
Après avoir exposé cela, il convient d'ajouter
JHtml::_('jquery.framework'); $doc->addScript('templates/'.$this->template.'/js/fancy-script.js');
à votre surcharge personnalisée de template ou extension est requis et ne causera pas de dommages ou conflits avec l'appel :
JHtml::_('bootstrap.framework');
de votre fichier template index.php.
Liens externes
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
Les navigateurs web diffèrent parfois dans la manière dont ils rendent une page. Pour cette raison, vous pouvez souhaiter savoir quel navigateur particulier un visiteur utilise afin d'utiliser des feuilles de style CSS spécifiques à ce navigateur.
Le JavaScript suivant définit un objet de détection de navigateur simple qui détermine le nom et la version du navigateur en décryptant la chaîne navigator.userAgent.
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;
}
}
}
Pour utiliser cela dans un script, vous créez une instance de cet objet :
var browser = new browserDetect();
La propriété browser.name vous donnera ensuite le nom du navigateur (MSIE, Opera, Netscape ou Firefox), browser.mainVersion affichera le numéro de version principal et browser.minorVersion contiendra le numéro de version mineure.
Ceci n'est pas infaillible. Il est bien mieux d'éviter d'écrire du code spécifique à un navigateur.
Ajouter des feuilles de style pour la visualisation sur d'autres périphériques
En se servant de feuilles de style CSS, il est possible d'utiliser un ensemble de directives (styles) en fonction du type d'appareil utilisé pour consulter des pages web.
Types de médias
Les types de médias reconnus sont les suivants :
- all - Convient pour tous types d'appareils.
- aural - Pour les synthétiseurs vocaux.
- braille - Conçu pour les dispositifs de retour tactile en braille.
- embossed - Prévu pour les imprimantes en braille.
- handheld - Conçu pour les appareils "de poche".
- print - Utilisé pour la mise en forme de pages imprimées.
- projection - Prévu de projeter des présentations, par exemple les projecteurs - ou les impressions sur transparents.
- screen - Conçu principalement pour les écrans en couleur d'ordinateurs.
- tty - Pour les médias utilisant une grille de caractères à hauteur fixe, tels que les télétypes, des bornes ou des appareils portables avec peu de capacités d'affichage. Il est conseiller de ne pas utiliser les unités de pixels avec le type de média "tty".
- tv - Destiné aux dispositifs télévisuels (basse résolution, couleur, capacité de défilement des écrans limitée, le son est disponible).
Exemples
Vous pouvez attribuer un type de média à une déclaration CSS avec la syntaxe suivante :
@media print {
body {
font-size: 12pt;
font-color: #000000;
}
}
Pour attribuer plus d'une déclaration de style à plus d'un type de support vous pouvez utiliser :
@media print, handheld{
body {
font-size: 12pt;
font-color: #000000;
}
img {
max-width: 100%;
height: auto;
}
}
Les directives peuvent être utilisées dans le fichier CSS principal ou dans une feuille de style différente pour un même type de média. Il doit y exister une inclusion du fichier CSS dans le <head> du template (voici par exemple l'inclusion dans le template Beez de Joomla) :
<link rel="stylesheet" href="<?php echo $this->baseurl ?>/templates/beez/css/print.css" type="text/css" media="Print" />
La méthode recommandée pour inclure une feuille de style est la suivante :
<?php
$document = JFactory::getDocument();
$tpath = $this->baseurl . '/templates/' . $this->template;
$document->addStyleSheet( $tpath . '/css/print.css', 'text/css', 'print'); // arguments: $path, $type, $media
?>
Ainsi, vous vous assurez que la feuille de style sera bien ajoutée au document et est accessible aux plugins (par exemple pour combiner et compresser les feuilles de style).