Introduction

La classe CopixHTMLHeader a pour objectif de permettre la manipulation de la partie entête du fichier HTML (head) généré par Copix à la fin du processus de rendu.

Tout ce qui aura été ajouté via cette classe sera assigné au template principal dans une variable spéciale nommée "$HTML_HEAD".

On se sert souvent de cette classe lorsqu'il faut inclure des codes javascripts ou styles spécifiques à certains écrans. Copix utilise cette fonctionnalité pour plusieurs balises.

API

CopixHtmlHeader?

addJSLink ($fichier, $attributs)

Cette fonction ajoute un lien vers un fichier javascript. Si le même fichier est inclus deux fois, il ne sera déclaré qu'une seule fois dans l'entête.

Le tableau d'attributs peut servir à rajouter des options lors de l'inclusion du fichier javascript, ces options seront rajoutées dans la balise "script". En particulier, si aucun identifiant (attribut id) n'est précisé, un identifiant est généré à partir du chemin du fichier.

Exemple 

//en utilisant le système de ressources
CopixHTMLHeader::addJsLink (_resource ('js/mon_fichier_js.js'));
//avec une url absolue
CopixHTMLHeader::addJsLink ('http://www.copix.org/js/mon_fichier_js.js');

N.B. : lors du traitement d'une requête AJAX, l'ajout d'un script fait appel au framework JavaScript?.

addCSSLink ($fichier, $attributs)

Cette fonction ajoute un lien vers un fichier CSS.

Si le même fichier est inclus deux fois, il ne sera déclaré qu'une seule fois dans l'entête.

Le tableau d'attributs peut servir à rajouter des options lors de l'inclusion du fichier. En particulier, si aucun identifiant (attribut id) n'est précisé, un identifiant est généré à partir du chemin du fichier.

Exemple 

//en utilisant le système de ressources
CopixHTMLHeader::addCSSLink (_resource ('css/mon_fichier_js.css'));
//avec une url absolue
CopixHTMLHeader::addCSSLink ('http://www.copix.org/css/mon_fichier_css.css');

N.B. : lors du traitement d'une requête AJAX, l'ajout d'une feuille de style fait appel au framework JavaScript?.

addStyle ($selector, $def = null)

Ajoute la déclaration d'un style CSS qui sera ajouté dans un ensemble "style" dans l'entête.

$def doit contenir l'ensemble des propriétés de style sous la forme d'une chaîne de caractères (sans les accolades).

Si plusieurs appels sont effectués à cette fonction avec le même sélecteur, seul le premier appel est pris en compte.

Exemple 

CopixHTMLHeader::addStytle ('h2', 'border-bottom: 1px solid #000; font-size: 1em;');

Si seul $selector est spécifié, alors il devra contenir un ensemble de déclarations CSS valides, par exemple 

CopixHTMLHeader::addStytle ('h2 {border-bottom: 1px solid #000; font-size: 1em}');

addOthers ($content, $key=null)

Ajoute un contenu dans l'en tête HTML, ce contenu sera ajouté tel quel, sans aucune modification.

Si une clef est donnée ($key), CopixHTMLHeader s'en servira comme identifiant unique et n'ajoutera le code en question qu'une seule fois par clef (le dernier appel écrasant les précédents). 

CopixHTMLHeader::addOthers ('<link rel="icon" href="icone.jpg" />');

addJSFramework ($pluginList)

Ajoute le framework Javascript, à savoir MooTools? et les extensions Copix à la page.

Le framework Javascript est nécessaire à un certain nombre de fonctionnalités Javascript avancées, notamment les tags copixzone?, js_modalbox?, tabgroup et les sessions AJAX.

La liste de plugins $pluginList permet d'ajouter le chargement de scripts supplémentaires placés dans www/js/mootools/plugins.

N.B. : les inclusions sont effectués via addJSLink avec un identifiant, pour éviter de les inclure plusieurs fois.

addJSCode ($code, $key = null, $domReady = CopixHTMLHeader::DOMREADY_AUTO)

Ajoute une portion de code Javascript dans l'en-tête HTML. Le code javascript ajouté ne doit pas contenir les balises de déclaration Javascript.

Si une clef est donnée ($key), CopixHTMLHeader s'en servira comme identifiant unique et n'ajoutera le code en question qu'une seule fois par clef (le dernier appel écrasant les précédents).

Le paramètre $domReady indique à quel moment du chargement de la page le code doit être executé. 3 valeurs sont possibles :

  • CopixHTMLHeader::DOMREADY_NEVER : le code doit toujours être exécuté immédiatement.
  • CopixHTMLHeader::DOMREADY_ALWAYS : le code doit toujours être exécuté lorsque l'arbre DOM du document est prêt. Cela est nécessaire si le code accède à l'arbre DOM, par exemple avec getElementById() (ou le $() de MooTools?). Utiliser cette option force l'inclusion du framework Javascript.
  • CopixHTMLHeader::DOMREADY_AUTO : le moment est déterminé selon les conditions suivantes :
    • Pour une requête non-AJAX : équivaut CopixHTMLHeader::DOMREADY_NEVER,
    • Pour une requête AJAX :
      • si au moins un lien Javascript est ajouté avec addJSLink, équivaut à CopixHTMLHeader::DOMREADY_ALWAYS,
      • si non, équivaut à CopixHTMLHeader::DOMREADY_NEVER

addJSDOMReadyCode ($code, $key = null)

Raccourci pour CopixHTMLHeader::addJSCode($code, $key, CopixHTMLHeader::DOMREADY_ALWAYS).

addFavIcon ($pPicturePath)

Ajoute une icone à votre page. $pPicturePath est le chemin de l'image. 

CopixHTMLHeader::addFavIcon (_resource ('img/tools/favicon.jpg'));

get ()

Retourne une chaîne de caractères qui correspond à l'en tête du fichier HTML. Cette méthode est appelée par Copix lors du rendu du fichier final.

clear ($what)

Permet de supprimer de l'entête HTML certains éléments. $what est un tableau de valeurs qui peut contenir 'CSSLink', 'Styles', 'JSLink', 'JSCode', 'Others'.