wiki:Copixresource
Last modified 4 years ago

Présentation

Copix possède un système vous permettant de gérer plus facilement vos ressources (feuilles de styles, images, javascripts ...).

Ce système est simple, quand vous voulez afficher une image, lier un fichier css, etc... Ne mettez pas son chemin en dur mais utilisez CopixResource?.

Exemple en PHP

<?php
CopixUrl::getResource ("styles/styles_copix.css");
// ou la syntaxe racourcie
_resource ("styles/styles_copix.css");
// retourne une chaine du type http://www.monsite.com/./themes/mon_theme/styles/styles_copix.css
?>

Exemple avec Smarty

Avec le tag copixresource :

Error: Failed to load processor smarty
No macro or processor named 'smarty' found

Récupérer le chemin physique

CopixURL::getResource() renvoie une URL pour le chemin passé en paramètre. Mais vous pouvez avoir besoin du chemin physique uniquement depuis www, sans  http://www.monsite.com/ devant. Dans ce cas, il faut utiliser CopixURL::getResourcePath() : 

<?php
CopixUrl::getResourcePath ('styles/styles_copix.css');
// ou la syntaxe raccourcie
_resourcePath ('styles/styles_copix.css');
// retourne une chaine du type ./themes/mon_theme/styles/styles_copix.css

// récupérer le chemin complet depuis la racine du disque dur
getcwd () . '/' . _resourcePath ('styles/styles_copix.css');
// retourne une chaine du type /var/www/html/mon_site/www/./themes/mon_theme/styles/styles_copix.css
?>

Types de ressources

Il existe deux types de ressources.

Ressources globales

Ce sont les ressources "classiques", identifiées par un chemin simple : chemin/vers/maRessource.css

Ces ressources sont stockées dans le répertoire www/ est sont accessibles directement depuis le web (i.e. sans passer par du PHP).

Ressources de module

Elles sont identifiées par un chemin de la forme : monModule|chemin/vers/maRessource.css

Ces ressources sont stockées dans les sous-répertoires www/ des modules. Elles sont accessibles via une URL spéciale qui utilise le script resource.php.

A Noter : un traitement spécial est réservé aux ressources de module de type Javascript, CSS ou HTML. Afin de pouvoir faire facilement des références à d'autres ressources dans ces fichiers, vous pouvez y utiliser un tag {copixresource path="chemin/vers/uneAutreRessource.css"}, qui sera évalué comme le tag copixresource de Smarty.

Par exemple, imaginez l'arborescence suivante :

  • monModule/
    • www/
      • styles/
        • monStyle.css
      • img/
        • monBackground.png
        • autreImage.png

La feuille de style peut être référencées par _resource('monModule|styles/monStyle.css'). Imaginez que dans cette feuille de style, vous voulez utiliser monBackground.png comme image de fond sur les balises ayant la classe CSS "maClasse". Vous pouvez le faire facilement avec le {copixresource} : 

.maClasse {
  background-image: url({copixresource path='monModule|img/monBackground.png'});
}

Point important, Smarty n'est absolument pas utilisé pour faire cette substitution. Ce serait bien trop lourd. Une simple expression régulière fait le travail. Donc aucune des fonctionnalités de Smarty ne sont disponbiles.

Ordre de résolution des ressources

Lorsque vous demandez une ressource avec _resource() ou _resourcePath(), une recherche du fichier est effectuée dans différents répertoires. Plusieurs paramètres et configurations différents vont se combiner pour déterminer l'ordre de recherche et le nom des fichiers recherchés.

La règle appliquée est celle du "first-match" : la recherche s'arrête au premier fichier trouvé.

Paramètres de résolution

Thème

La résolution tient compte du thème en cours. Par exemple pour une ressource chemin/vers/maRessource.css, l'ordre de résolution est :

  1. si le thème n'est pas "default": www/themes/nomDuTheme/chemin/vers/maRessource.css
  2. www/themes/default/chemin/vers/maRessource.css
  3. www/chemin/vers/maRessource.css

I18N

En définissant la propriété CopixConfig::instance()->i18n_path_enabled à vrai, la recherche de ressources internationalisées est activée.

Dans ce cas, l'ordre de résolution tient compte des valeurs de CopixI18N::getLang() et CopixI18N::getCountry(). Pour chaque répertoire testé, deux sous-répertoires sont testés en premier lieu s'ils existent. L'ordre de résolution est :

  1. chemin/vers/lang_country/maResource.css
  2. chemin/vers/lang/maResource.css
  3. chemin/vers/maResource.css

Répertoires de ressources supplémentaires

En utilisant CopixConfig::instance()->copixresource_addDirectory(), il est possible d'indiquer des sous-répertoires de www/ dans lesquels se trouvent des ressources. Ces répertoires sont vérifiés dans l'ordre d'ajout dans liste. En outre, la racine est toujours vérifiée en premier.

L'intérêt de ce système est, par exemple, de placer une copie du répertoire www/ distribué avec Copix3 dans un sous-répertoire et de placer les ressources propres à votre projet à la racine du www/.

Exemple de résolutions

Pour cette exemple, prenons le contexte suivant :

  • thème : automne,
  • internationalisation des ressources : activée,
  • langue : fr (français)
  • pays : FR (France).
  • répertoires supplémentaires : commons/.

Pour une ressource globale chemin/vers/maRessource.css, l'ordre de résolution est:

  1. themes/automne/chemin/vers/fr_FR/maRessource.css
  2. themes/automne/chemin/vers/fr/maRessource.css
  3. themes/automne/chemin/vers/maRessource.css
  4. commons/themes/automne/chemin/vers/fr_FR/maRessource.css
  5. commons/themes/automne/chemin/vers/fr/maRessource.css
  6. commons/themes/automne/chemin/vers/maRessource.css
  7. themes/default/chemin/vers/fr_FR/maRessource.css
  8. themes/default/chemin/vers/fr/maRessource.css
  9. themes/default/chemin/vers/maRessource.css
  10. commons/themes/default/automne/chemin/vers/fr_FR/maRessource.css
  11. commons/themes/default/automne/chemin/vers/fr/maRessource.css
  12. commons/themes/default/automne/chemin/vers/maRessource.css
  13. chemin/vers/fr_FR/maRessource.css
  14. chemin/vers/fr/maRessource.css
  15. chemin/vers/maRessource.css
  16. commons/chemin/vers/fr_FR/maRessource.css
  17. commons/chemin/vers/fr/maRessource.css
  18. commons/chemin/vers/maRessource.css

Pour une ressource de module monModule|chemin/vers/maRessource.css, l'ordre de résolution est:

  1. themes/automne/modules/monModule/chemin/vers/fr_FR/maRessource.css
  2. themes/automne/modules/monModule/chemin/vers/fr/maRessource.css
  3. themes/automne/modules/monModule/chemin/vers/maRessource.css
  4. commons/themes/automne/modules/monModule/chemin/vers/fr_FR/maRessource.css
  5. commons/themes/automne/modules/monModule/chemin/vers/fr/maRessource.css
  6. commons/themes/automne/modules/monModule/chemin/vers/maRessource.css
  7. cheminDeMonModule/www/chemin/vers/fr_FR/maRessource.css
  8. cheminDeMonModule/www/chemin/vers/fr/maRessource.css
  9. cheminDeMonModule/www/chemin/vers/maRessource.css

Dans les trois derniers cas, comme le répertoire cheminDeMonModule/www/ n'est pas accessible direcement depuis le web, le script resource.php est utilisée pour récupérer le contenu de la ressource.