Sass et Compass éveillent de plus en plus la curiosité des intégrateurs Web et développeurs front-end français. Malheureusement je ne peux que constater une certaine réticence de leur part à sauter le pas.
La faute en incombe généralement à une frayeur démesurée de la ligne de commande et, il est vrai, à un manque de ressources francophones qui expliquent comment intégrer l’outil dans son processus métier.

Je vous propose ici la méthode de travail générique que j’utilise depuis maintenant 2 ans dans mon environnement professionnel. Je précise bien générique parce que certains projetss peuvent imposer une organisation différente.

Crédits : Post-it Marilyn par Peter Hellberg sous licence CC BY-SA 2.0

Initialiser un nouveau projet Compass

Mon projet est généralement contenu dans un projet plus conséquent, comme par exemple un thème Drupal pour lequel j’ai déjà créé son répertoire. Il me suffit ainsi d’initialiser un nouveau projet Compass, chose aisée grâce à sa commande init :

$ compass init --prepare --sass-dir sass --css-dir css --images-dir img --relative-assets
directory css/ 
directory sass/ 
   create config.rb

Puisque je ne souhaite pas que Compass me génère de feuilles de styles par défaut, j’utilise ici l’option --prepare qui limitera son action à créer :

• le fichier de configuration du projet config.rb ;
• le répertoires accueillant les sources SCSS nommé ici sass ;
• le dossier de destination des feuilles de styles générées css.

Cela fait, j’édite le fichier de configuration pour paramétrer les 2 environnements de déployement (development et production, sachant que development est celui par défaut) et pour empêcher Compass d’ajouter un éventuel cache buster :

if environment == :production
  output_style = :compressed
else
  output_style = :expanded
  sass_options = { :debug_info => true }
end

# Désactiver l'ajout du cache buster sur les images appelées via la fonction image-url().
asset_cache_buster :none

Note :
La ligne qui contient :debug_info me permet d’utiliser le plugin pour Firefox FireSass.

Ok, mon projet Compass est presque prêt. Il ne me manque plus qu’à créer quelques répertoires et fichiers que j’utilise habituellement :

$ mkdir -p sass/partials/{reset,ui}
$ touch sass/{style,reset,partials/_{base,reset,ui}}.scss

Mon arborescence finale :

$ tree -F
.
├── config.rb
├── css/
└── sass/
    ├── partials/
    │   ├── _base.scss
    │   ├── _reset.scss
    │   ├── _ui.scss
    │   ├── reset/
    │   └── ui/
    ├── reset.scss
    └── style.scss

Méthodologie de travail avec Compass

Après toute modification qui nécessite une vérification du résultat de ma part¹, je lance une compilation des sources Sass par une simple commande :

$ compass compile

Comme aucun fichier de configuration n’est précisé, la commande compile lit le fichier de configuration config.rb (ou compass.rb).

Lorsque mon fichier de configuration n’est pas standard, je précise son emplacement avec l’argument -c : $ compass compile -c sass/theme.rb

Il est aussi possible de ne compiler qu’une seule feuille de styles, en précisant simplement son équivalent Sass :

$ compass compile sass/styles.scss

Cette opération pouvant être répétitive, Compass offre une commande watch qui possède les même options que sa sœur compile mais qui se charge de surveiller mon projet et lancer la compilation dès que cela est nécessaire :

$ compass watch

Un petit Ctrl+C stoppera la surveillance.

Partager son projet Compass

Jusqu’ici je ne travaillai qu’en local. Il me faut maintenant pousser mon travail sur le dépôt centralisé pour permettre à mes collègues d’en bénéficier.
Oui, je pourrai pousser le travail en l’état, mais non je ne le fait pas. Puisque ces mêmes ressources sont destinée à être déployées sur le serveur de production je relance une compilation en précisant l’environnement production :

$ compass compile -e production --force

L’argument --force m’assure que toutes les ressources seront bien compilées.

J’obtiens ainsi des feuilles de styles compressées, idéales pour les webperf et décourageantes pour la personne qui souhaiterait directement les éditer en se cognant du projet Compass parce que ça l’emmerde de s’y mettre²

Webperf un jour, webperf toujours !

Dernière opération avant de pousser mon travail : j’optimise les sprites modifiés depuis la dernière fois. Évoluant sous MacOSX, j’utilise l’excellent ImageOptim. Sous Linux vous pouvez vous tourner vers son équivalent Trimage et PNGGauntlet sous Windows.

Au secours, j’ai un conflit !

Après un svn up ou git pull il peut arriver un conflit . Il y a 98% de chances pour qu’il porte sur un fichier généré par Compass, à savoir une feuille de styles ou une image de sprite.
Pas de problème, j’accepte la version entrante ou supprime ma version locale. Je peux ainsi visualiser dans un navigateur la dernière version récupérée et dans tous les cas il me suffit de lancer une compilation pour que mon travail soit à nouveau pris en compte (puisque les modifications entrantes des sources Sass ont été correctement fusionnées).

En résumé

Finalement, une fois le projet initialisé, travailler avec Compass revient à exécuter un ridicule jeux de commandes :

$ compass watch
CTRL+C
$ compass compile -e production --force
$ open -a "ImageOptim" img/*.png

Rien de sorcier, n’est-ce pas ?

Bonus de Compass

Il peut arriver que je souhaite supprimer tout fichier généré par Compass : fichiers de cache, sprites et feuilles de styles. Rien de plus simple à l’aide de la commande clean :

$ compass clean

Parce que les statistiques sont toujours révélatrices de points forts ou faiblesses d’un projet :

$ compass stats

Notes :
N’oubliez pas de préciser le fichier de configuration s’il n’est pas standard.

Continuez votre lecture sur des sujets similaires

• Compass : supprimer le cache buster des sprites
• Instances multiples de Compass avec Ruby Version Manager (rvm)
• Git : des alias pour aller plus vite
• Drupal 6 : utiliser une iframe comme contenu de page
• Optimiser le chargement des AdSense

Le système de theming de Drupal 7 est un gâchis. Jacine Luisi, co-auteure du livre The Definitive Guide to Drupal 7, résume dans son article Let’s Do Something About Drupal’s Theme System le fond de ma pensée. Au lieu de retranscrire son article ici même, je vais plutôt vous présenter de quoi il retourne.

Crédits : Kaos - Chaos paiting (ii) par Kristina Alexanderson sous licence CC BY-NC-SA 2.0

Pourquoi le theming Drupal est-il si compliqué ?

Depuis que je travaille sur Drupal 7, il ne se passe pas une semaine sans que j’ai à pester contre son système de thème. Comme le souligne Jacine, les nombreux points d’entrées et la multiplicité de niveaux d’interactions font qu’il est souvent difficile de trouver où intervenir.

Quel preprocess appeler ? Celui-ci ?
Perdu. Testons dans un autre ou dans un hook_alter.
Toujours rien. Peut-être dans un hook_process ?
Finalement, il me faut surcharger un hook_theme parce que je ne peux agir sur ce pre-render…

J’exagère un peu, quoique, pas tant que ça finalement.
Vous allez me dire qu’avec Drupal 6 nous étions habitué à cette gymnastique mentale, ce à quoi je réponds oui, mais. Mais, c’était moins anarchique. Exemple.

Un exemple tout bête

Pour un type de contenu spécifique, un client demande à pouvoir insérer librement du code JavaScript et des styles CSS depuis l’espace de contribution. Pas de problème, il me suffit de récupérer le contenu des champs et de les attacher à la page à l’aide des fonctions drupal_add_js et drupal_add_css en précisant un type inline et les scopes appropriés. Ni une ni deux, je m’exécute et fais le nécessaire dans une implémentation de hook_preprocess_node() et, sans surprise, cela fonctionne.

Note : les extraits de codes qui suivent sont simplifiés pour se focaliser sur le sujet.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20

<?php
/**
 * @file template.php
 */
/**
 * Implements hook_preprocess_node().
 */
function MYTHEME_preprocess_node(&$vars) {
  // Nous utilisons la propriété `value` au lieu de `safe_value` qui encode les quotes.
  if (!empty($vars['field_inline_css'][0]['value'])) {
    drupal_add_css($vars['field_inline_css'][0]['value'], array(
      'type'       => 'inline',
      'group'      => CSS_THEME,
      'every_page' => false,
      'media'      => 'all',
      'preprocess' => false, // ne pas aggréger avec les autres styles
    ));
  }
  // -- snip --
}

Malheureusement le markup HTML des champs est malgré tout généré dans le flux du contenu. Ok, il me suffit de les masquer (au sens Drupal 7 du terme). Je regarde pour appliquer un coup de hide() sur mes champs depuis mon implémentation du preprocess_node. Mince, ces derniers sont déjà marqués comme rendus, leurs contenu calculé, etc. Pas mieux depuis un hook_page_alter(), ni depuis le fichier de template dédié. Pourtant la documentation officielle ne cesse de montrer comme il est facile de gérer la visibilité des champs.

Que faire ? Dois-je perdre du temps pour rendre un à un tous les champs à afficher pour ce type de contenu, ou est-ce que je pousse un peu l’investigation ? J’opte pour la seconde option tellement cette situation me paraît ridicule.

Rapidement, je trouve que je peux masquer mes champs en implémentant le hook_node_view_alter(). Tout fonctionne.

1
2
3
4
5
6
7
8
9
10
11

<?php
/**
 * @file template.php
 */
/**
 * Implements hook_node_view_alter().
 */
function MYTHEME_node_view_alter(&$build) {
  hide($build['field_inline_css']);
  hide($build['field_inline_js']);
}

Cependant, gérer ces champs à deux endroits n’est pas des plus lisible. Je rapatrie donc le code ajouté dans l’implémentation du hook_preprocess_node() dans mon hook_node_view_alter.
Déconfiture : seule l’injection du JavaScript est prise en compte. Celle des styles CSS est tout bonnement ignorée ;!

WTF Drupal (╯°□°）╯︵ ┻━┻

Et c’est ainsi que je me suis résigné à scinder cette étape de theming en 2 emplacements distincts. Le tout agrémenté d’explications en commentaires pour ne pas m’y perdre dans quelques mois ou tout simplement pour aider mes collègues à s’y retrouver.

Comment en est-on arrivé là ?

La faute en incombe en partie à une structure de données non normalisée couplée à un système de render array alléchant mais qui ne tient pas ses promesses. Tout module gère ses données à transmettre à l’API render comme bon lui chante. De ce fait il existe presque autant de cas de figure qu’il y a de modules :-/ Au niveau des fichiers de template, nous avons le droit à une soupe de variables au type simple et de render array.

Également, les modules peuvent transformer la structure des render array et nous mettre des bâtons dans les roues pour le theming (les modules Field Group et Display Suite en sont de bons exemples).

Pour finir, bien des situations complexes pourraient être évités si le core de Drupal exploitait systématiquement les render array. Il arrive toujours un moment où, alors que nous cherchons à modifier le #prefix d’un élément, l’on tombe sur du pur HTML. Tout ça parce qu’une implémentation du hook_theme() ne retourne pas de render array, comme theme_links() par exemple…

L’avenir du theming avec Drupal 8

FIXME. C’est l’idée
Jacine propose une standardisation de composant qui aura le bénéfice de simplifier le templating en rationnalisant la construction d’une page et, surtout, chaque module pourra arrêter de nous noyer sous des kilomètres de classes CSS “au cas où…”.

Continuez votre lecture sur des sujets similaires

• Drupal 6 : utiliser une iframe comme contenu de page

Facebook a annoncé la suppression des profils d’applications au 1er février 2012. Vous ne pourrez plus associer une application onglet à une page fan comme vous le faisiez actuellement. En effet, la page de profil d’une application mettait à disposition un lien pour ajouter cette dernière à/aux page(s) fan de votre choix.

Facebook propose bien de créer manuellement une page associée à votre application, mais vu son utilité autant s’en passer. À la place, et pour éviter 50 clics supplémentaires, je vous propose, amis Community manager, un bookmarklet qui permet d’associer aisément vos applications à des pages fan Facebook.

Mise en place du bookmarklet

Glissez-déposez simplement le lien ci-dessous dans les favoris de votre navigateur ; dans votre barre personnelle par exemple.

Utilisation du bookmarklet Facebook Add Page Tab

Rendez-vous sur la page de configuration de votre application¹ puis cliquez sur le bookmarklet. Ce dernier vous redirige vers une page Facebook vous demandant les pages qui accueilleront votre application. L’association faite, vous serez redirigés sur l’accueil de Facebook, et pourrez accéder à votre/vos page(s) mise(s) à jour via le moteur de recherche ou le manager de pages.

Page de configuration d’une application Facebook

Continuez votre lecture sur des sujets similaires

• Dailymotion Download Bookmarklet
• JavaScript : optimiser le calcul de l’intersection de tableaux de grandes tailles
• Une console JSLint pour aider vos validations JavaScript
• Optimiser le chargement des AdSense
• Du RGBA dans vos animations avec le plugin jQuery Color

Le générateur de sprites de Compass 0.11.3¹ crée des images dont le nom a pour format <map>-<hash>.png où <map> correspond au nom du répertoire qui contient les images du sprite et -<hash> à un hash qui :

• assure l’unicité du fichier généré ;
• fait office de cache buster.

Seulement voilà, chaque modification de sprite (par un ajout ou décalage d’image par exemple) va générer une image avec un hash différent², ce qui rend la gestion du dépôt d’un projet versionné assez prise de tête.
Heureusement, il est possible de ruser.

Pour ce faire, il suffit d’implémenter les callbacks on_sprite_saved et on_stylesheet_saved dans le fichier de configuration du projet, comme suit :

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21

#
# config.rb
#
 
# Réaliser une copie des sprites avec un nom dépourvu du hash d'unicité.
on_sprite_saved do |filename|
  if File.exists?(filename)
    FileUtils.cp filename, filename.gsub(%r{-s[a-z0-9]{10}\.png$}, '.png')
  end
end
 
# Remplacer dans les feuilles de styles générés les références aux sprites par
# leurs équivalents dépourvus du hash d'unicité.
on_stylesheet_saved do |filename|
  if File.exists?(filename)
    css = File.read filename
    File.open(filename, 'w+') do |f|
      f << css.gsub(%r{-s[a-z0-9]{10}\.png}, '.png')
    end
  end
end

Ainsi, après chaque génération de sprite par Compass, une copie de l’image dépourvue du hash d’unicité est réalisée. Cela s’accompagne bien évidemment par un remplacement de leurs appels dans les feuilles de styles.
Il ne reste plus qu’à ignorer les images ayant un hash au niveau de votre repository pour ne pas polluer ce dernier.

Je suis conscient qu’il y aurait plus secure (je pense notamment aux substitutions dans les feuilles de style), mais disons que cela me convient dans l’immédiat, et qu’accessoirement je ne fais pas de ruby

Continuez votre lecture sur des sujets similaires

• Compass au quotidien
• Instances multiples de Compass avec Ruby Version Manager (rvm)
• Drupal 6 : utiliser une iframe comme contenu de page
• Optimiser le chargement des AdSense
• WordPress : autoriser l’upload de fichiers au format non-supporté

Vous devez intégrer sous Drupal 6 des pages en provenance d’un site externe. Le web scraping est à exclure et de ce fait le chargement en iframe des pages externes a été retenu.
Marche à suivre.

Déclarer un menu de type callback

En premier lieu, il vous faut créer la page virtuelle qui aura la charge de faire appel au service externe via une iframe. Cela se fait en implémentant le hook_menu pour y déclarer une entrée de type MENU_CALLBACK. La fonction callback associée, _mytheme_load_iframe() ici¹, prendra 3 arguments :

1. url : l’URL de la ressource externe à charger dans l’iframe ;
2. width : la largeur en pixels de l’iframe, de type String obligatoirement ;
3. height : la hauteur en pixels de l’iframe, obligatoirement de type String.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35

<?php
/**
 * template.php
 */
/**
 * @implements hook_menu()
 */
function mytheme_menu() {
    return array(
        'drupal/page/path' => array(
            'title'            => 'Mon contenu externe',
            'page callback'    => '_mytheme_load_iframe',
            'page arguments'   => array(
              'url'    => 'http://example.com/service',
              'width'  => '700',
              'height' => '1000',
            ),
            'access arguments' => array('access content'),
            'type'             => MENU_CALLBACK,
        )
    );
}
 
/**
 * Loads an external resource into an iframe.
 *
 * @param string $url   URL to load in the iframe.
 * @param string $width The width of the iframe.
 * @param string $height The height of the iframe.
 */
function _mytheme_load_iframe($url, $width, $height) {
    return theme('mytheme_simple_iframe', $iframe_url, $width, $height);
}
 
?>

Comme vous pouvez le lire, la méthode de callback fait appel à la fonction theme() sur un hook mytheme_simple_iframe qui n’existe pas.

Création d’un hook de thème

La création d’un hook permettant de faire appel à un fichier template est des plus simple, grâce au hook_theme. Définissez dans votre fichier template.php (ou dans un fichier de module) le hook mytheme_simple_iframe :

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20

<?php
/**
 * template.php
 */
/**
 * @implements hook_theme()
 */
function mytheme_theme() {
    return array(
      'mytheme_simple_iframe' => array(
        'template'  => 'simple_iframe',
        'arguments' => array(
            'url'    => null,
            'width'  => '700',
            'height' => '500',
        ),
      ),
    );
}
?>

Simple de compréhension, on déclare un fichier de template simple_iframe auquel 3 variables seront passées. Les arguments width et height ont une valeur par défaut de précisée, ce qui permet de les omettre dans la définition de la ressource externe dans le hook_menu.

Enfin, créez le fichier de template qui affichera une iframe.

1
2
3
4
5
6
7
8

<?php
/**
 * simple_iframe.tpl.php
 */
?>
<div class="iframe">
  <iframe src="<?php print $url ?>" width="<?php print $width ?>" height="<?php print $height ?>" frameborder="0" align="left"></iframe>
</div>

Désormais, tout accès à l’URL /drupal/page/path chargera le template simple_iframe.tpl.php lorsque Drupal effectuera le rendu de la variable $content du fichier page.tpl.php.

Continuez votre lecture sur des sujets similaires

• Compass au quotidien
• Les angoisses du theming sous Drupal 7
• Compass : supprimer le cache buster des sprites
• Optimiser le chargement des AdSense
• WordPress : autoriser l’upload de fichiers au format non-supporté

Dans le cadre de mon travail à Clever Age j’utilise dans plusieurs projets Compass, le framework Sass, dans sa version 0.10.6. Mais voilà, cette version a laissé place à la branche 0.11 qui, malheureusement, s’accompagne de son lot de mixins obsolètes voire de bugs avec certaines extensions.

Mes nouveaux projets feront appels à la dernière version en date de Compass mais il me faut conserver une branche 0.10 sur mon poste pour assurer le support des anciens projets. Il est actuellement inconcevable de proposer aux clients une mise à jour des fichiers SCSS vers la branche 0.11.

Comment faire cohabiter les deux versions de Compass et leurs dépendances ? C’est là qu’intervient Ruby Version Manager, un gestionnaire d’environnements pour Ruby.

Installer RVM

L’installation de RVM est des plus simples : il suffit de suivre la documentation.
Je préfère installer RVM pour l’utilisateur courant (moi) et non pour tous les utilisateurs du poste, qui n’auront pas les mêmes besoins. Accessoirement, cela me permet de manipuler les gem sans invoquer sudo.

$ cd
$ bash < <(curl -sk https://rvm.beginrescueend.com/install/rvm)
$ echo '[[ -s "$HOME/.rvm/scripts/rvm" ]] && . "$HOME/.rvm/scripts/rvm" # Load RVM function' >> ~/.bash_profile
$ source .bash_profile
$ type rvm | head -1
rvm is a function

J’en profite pour installer la dernière version stable de Ruby :

$ rvm install 1.9.2
Installing Ruby from source to: /Users/mehdi/.rvm/rubies/ruby-1.9.2-p180, this may take a while depending on your cpu(s)...

ruby-1.9.2-p180 - #fetching 
ruby-1.9.2-p180 - #downloading ruby-1.9.2-p180, this may take a while depending on your connection...
…
Installing rubygems dedicated to ruby-1.9.2-p180...
…
Installation of rubygems completed successfully.
ruby-1.9.2-p180 - adjusting #shebangs for (gem irb erb ri rdoc testrb rake).
ruby-1.9.2-p180 - #importing default gemsets (/Users/mehdi/.rvm/gemsets/)
Install of ruby-1.9.2-p180 - #complete 

À ce point, la version de Ruby active sur le système est pourtant celle fournie par Apple (je suis toujours sous OSX :p) :

$ ruby -v
ruby 1.8.7 (2009-06-12 patchlevel 174) [universal-darwin10.0]

En effet, RVM a bien réalisé l’installation de Ruby 1.9.2 mais il faut déclarer explicitement notre souhait de l’utiliser en remplacement de la version système¹ :

$ rvm use 1.9.2 --default
Using /Users/mehdi/.rvm/gems/ruby-1.9.2-p180
$ ruby -v
ruby 1.9.2p180 (2011-02-18 revision 30909) [x86_64-darwin10.7.0]

Installation de la dernière version en date de Compass

Classique, l’installation de Compass se fait via gem :

$ gem install compass
Fetching: sass-3.1.1.gem (100%)
Fetching: chunky_png-1.2.0.gem (100%)
Fetching: fssm-0.2.7.gem (100%)
Fetching: compass-0.11.1.gem (100%)
Successfully installed sass-3.1.1
Successfully installed chunky_png-1.2.0
Successfully installed fssm-0.2.7
Successfully installed compass-0.11.1
4 gems installed
Installing ri documentation for sass-3.1.1...
Installing ri documentation for chunky_png-1.2.0...
Installing ri documentation for fssm-0.2.7...
Installing ri documentation for compass-0.11.1...
Installing RDoc documentation for sass-3.1.1...
Installing RDoc documentation for chunky_png-1.2.0...
Installing RDoc documentation for fssm-0.2.7...
Installing RDoc documentation for compass-0.11.1...
$ gem list

*** LOCAL GEMS ***

chunky_png (1.2.0)
compass (0.11.1)
fssm (0.2.7)
rake (0.9.0)
sass (3.1.1)

Une petite vérification d’usage :

$ compass version 
Compass 0.11.1 (Antares)
Copyright (c) 2008-2011 Chris Eppstein
Released under the MIT License.
Compass is charityware.
Please make a tax deductable donation for a worthy cause: http://umdf.org/compass

Ok, mon environnement par défaut est prêt. Voyons comment faire cohabiter une ancienne version de Compass.

Création d’un Gemset dédié à l’ancienne version de Compass

En premier lieu, je me positionne sur l’environnement ruby voulu. Ici, il s’agit du Ruby que j’ai défini par défaut.

$ rvm default
$ rvm gemset name
/Users/mehdi/.rvm/gems/ruby-1.9.2-p180

Recherchons la dernière version de la branche qui m’intéresse² (0.10 pour rappel) :

$ gem query -ran ^compass$

*** REMOTE GEMS ***

compass (0.11.1, 0.11.0, 0.10.6, 0.10.5, 0.10.4, 0.10.3, 0.10.2, 0.10.1, 0.10.0, 0.8.17, 0.8.16)

Ok, il me faut la 0.10.6.
RVM donne accès à des gemsets qui sont des espaces cloisonnés de gems pour une version de Ruby donnée. Pratique, j’ai justement besoin d’isoler les gems de la version 0.10.6 de Compass à celles de la dernière version en date.

Je crée un gemset au nom assez explicite et l’utilise :

$ rvm gemset create compass0.10.6
$ rvm gemset use !$
$ rvm gemset name
compass0.10.6

La création d’un gemset fourni un nouvel environnement vierge de gems (ou presque, rake restant disponible) :

$ gem list

*** LOCAL GEMS ***

rake (0.9.0)

Je peux maintenant installer Compass 0.10.6³, ses dépendances et autres extensions en toute tranquillité.

$ gem install compass --version 0.10.6 --no-rdoc --no-ri
Fetching: haml-3.1.1.gem (100%)
Fetching: compass-0.10.6.gem (100%)
Successfully installed haml-3.1.1
Successfully installed compass-0.10.6
2 gems installed
$ gem list

*** LOCAL GEMS ***

compass (0.10.6)
haml (3.1.1)
rake (0.9.0)

La petite vérification d’usage :

$ compass version
Compass 0.10.6
Copyright (c) 2008-2009 Chris Eppstein
Released under the MIT License.

Installer l’extension Lemonade pour Compass 0.10.6

Il ne me reste plus qu’à installer l’extension lemonade que j’utilise dans mes projets :

$ gem install lemonade --version '< 0.3.5' --no-rdoc --no-ri
…
4 gems installed

J’installe ici la version strictement inférieur à 0.3.5 de lemonade car cette dernière lève directement une erreur pour indiquer que la gem lemonade est désormais dépréciée au profit de Compass Sprites. Le hic étant que ce dernier n’existe pas dans Compass 0.10.6.

Malheureusement, la gem de lemonade ne précise pas les bonnes versions de ses dépendances, et, de ce fait, on se retrouve avec un environnement incapable de générer les images des sprites. Pour corriger cela, on commence par downgrader la version de chunky_png :

$ gem uninstall chunky_png --version 1.2.0
$ gem install chunky_png --version '< 1.0.0' --no-rdoc --no-ri
…
1 gem installed  

La gem haml installée avec l’extension lemonade est incompatible avec Compass 0.10.6 et risque de générer une erreur du genre :

compile scss/screen.scss
  error scss/screen.scss (Line 2087: Not a valid color stop: #bcd712 74%)

Il suffit donc d’installer la dernière version de la branche 3.0 :

$ gem install haml --version '< 3.1' --no-rdoc --no-ri
$ gem uninstall haml --version 3.1.1
$ gem list

*** LOCAL GEMS ***

chunky_png (0.12.0)
compass (0.10.6)
fssm (0.2.7)
haml (3.0.25)
lemonade (0.3.4)
rake (0.9.0)
sass (3.1.1)

Utilisation

Par défaut, en ouvrant un shell, Compass sera disponible en version 0.11. Si j’ai à travailler sur un projet en 0.10 il me suffit d’ouvrir un nouveau shell et d’activer temporairement le gemset compass0.10.6 :

$ rvm gemset use compass0.10.6

À l’avenir, je maintiendrai à jour la version de Compass dans l’environnement par défaut et, si besoin est, je figerai dans un nouveau gemset la version de Compass devenu obsolète.

Continuez votre lecture sur des sujets similaires

• Compass : supprimer le cache buster des sprites
• Compass au quotidien
• PHP : installer APC sous Mac OS X Leopard
• Rotation des logs Apache
• TextMate : bundle CSS, commande "Convertir la sélection en Unicode"

Créé par Loïc d’Anterroches, Photon¹ est un micro framework PHP distribué sous licence LGPL qui fonctionne au-dessus du serveur web Mongrel2 et du service de messagerie asynchrone ØMQ².
Voici un petit guide d’installation pour ce framework PHP pas comme les autres.

Pré-requis

Je considère que vous disposez sur votre système d’une version de PHP 5.3 installée via macports, à l’aide du port php5.

Photon effectue des contrôles de processus. Pour ce faire, la présence de l’extension PHP PCNTL est obligatoire.
Vérifiez que vous la possédez :

$ php -i | grep pcntl
/opt/local/var/db/php5/pcntl.ini,
pcntl
pcntl support => enabled

Si ce n’est pas le cas, lancez une installation macports :

$ sudo port install php5-pcntl

Mongrel2 requiert SQLite et ZeroMQ. Aussi, s’il n’est pas encore présent dans votre environnement de développement, il sera bon d’installer XDebug.
Vérifiez la présence de ces pré-requis sur votre poste :

$ port installed sqlite3 zmq php5-xdebug
The following ports are currently installed:
  php5-xdebug @2.1.0_0 (active)
  sqlite3 @3.7.5_0 (active)
  zmq @2.0.10_0 (active)

S’il vient à manquer des ports dans la liste ainsi générée, installez-les avec la commande port install :

sudo port install zmq

Dans le cas où vous ne possédez aucune de ces libraires, vous pouvez les installer en une unique commande

sudo port install sqlite3 zmq php5-xdebug php5-pcnt

Installer Mongrel2 sous Mac OS X Snow Leopard

Contre toute attente, au moment où cet article est rédigé, Mongrel2 n’est pas disponible dans macports. Qu’à cela ne tienne, procédez à son installation depuis les sources :

sudo port install wget
wget http://mongrel2.org/static/downloads/mongrel2-1.5.tar.bz2
tar xjvf mongrel2-1.5.tar.bz2
cd mongrel2-1.5/
sudo make clean macports install

L’option macports du Makefile ne signifie par que Mongrel2 s’installera dans l’environnement de macports, mais qu’il va utiliser les libraires disponibles depuis cet environnement (soit généralement /opt/local/). Le binaire est généré dans le répertoire /usr/local/bin/ :

which m2sh
/usr/local/bin/m2sh

Installer Photon

L’installation de Photon est des plus simple. En effet, tout passe par PEAR.

Commencez par déclarer les canaux du projet Photon, de l’extension PHP pour ØMQ puis ceux de PHPUnit et ses dépendances :

sudo pear channel-discover dist.photon-project.com
sudo pear channel-discover pear.zero.mq
sudo pear channel-discover pear.phpunit.de
sudo pear channel-discover pear.symfony-project.com
sudo pear channel-discover components.ez.no

N’ayez aucune inquiétude quant à la présence des dépendances Symfony et eZ Publish. Ces dernières sont requises par PHPUnit qui n’y récupérera qu’un nombre limité de composants (comme le parser YAML de Symfony) et n’ira pas vous installer les 2 solutions dans leur intégralité.

Il ne vous reste plus qu’à lancer l’installation proprement dite de Photon :

sudo pear install --alldeps photon/photon-alpha
sudo sh -c 'echo "extension=http.so" > /opt/local/var/db/php5/http.ini'
sudo sh -c 'echo "extension=zmq.so" > /opt/local/var/db/php5/zmq.ini'    

Tester votre installation de Photon

L’installation terminée, Photon est accessible par la commande hnu³. Afin de vous en assurer, lancez simplement sa propre batterie de tests unitaires, comme suit :

hnu selftest

Could not open input file: /usr/share/php/photon.php

Si vous rencontrez l’erreur Could not open input file: /usr/share/php/photon.php c’est que vous utilisez une version de Photon inférieure ou égale à 0.0.5. Si à l’heure où je rédige ces lignes la version 0.0.6 de Photon n’est pas disponible, exécutez l’ensemble des commandes ci-dessous pour fixer le problème :

cd ~/Downloads/
wget -O hnu.diff http://projects.ceondo.com/p/photon/source/ddiff/9acba649ae355aaf4b365a1f639961336ae6a323/
sudo patch --no-backup-if-mismatch -i hnu.diff `pear config-get bin_dir`/hnu
rm hnu.diff
cd -

Mettre à jour Photon

Encore une fois, la procédure est des plus simple grâce à PEAR :

$ sudo pear update-channels
Update of Channel "dist.photon-project.com" succeeded
$ sudo pear upgrade photon/photon-alpha
downloading photon-0.0.5.tgz ...
Starting to download photon-0.0.5.tgz (3,937,334 bytes)
...........................................................................done: 3,937,334 bytes
upgrade ok: channel://dist.photon-project.com/photon-0.0.5

Accéder aux sources de Photon

Vous pouvez accéder en local aux sources de Photon dans le répertoire /opt/local/lib/php. Avec TextMate par exemple :

mate -a `pear config-get php_dir`/photon*

Autrement, vous pouvez directement accéder aux sources du projet par la forge Indefero du projet.

Continuez votre lecture sur des sujets similaires

• PHP : installer APC sous Mac OS X Leopard
• WordPress : une classe abstraite pour aider la création de shortcodes
• TextMate : commande « Export words »
• PHP : convertir un DATETIME en un timestamp UNIX
• PHP : fonction uncamel() pour inverser une notation en CamelCase

J’ai récemment eu besoin d’afficher de manière élégante les pièces jointes à des articles et des pages. Seulement, avec un WordPress qui autorise l’ajout de documents autres que des images/vidéos et rien pour les insérer proprement dans un contenu, la tâche est loin d’être aisée.

Un coup de XHTML et roule ma poule !

Oui ! Si j’étais le rédacteur du site (comme ici). Mais il n’en est rien. Il fallait une solution utilisable depuis l’éditeur WYSIWYG, sans avoir à intervenir sur la source XHTML (genre pour ajouter un div, une image, des classes CSS, etc).

Voici donc un shortcode WordPress qui affiche la liste des pièces jointes.

Le shortcode en action

Table des matières

1. Code source
2. Différents styles d’affichage
3. Exemples d’utilisation
4. Liste des paramètres
5. Personnaliser le shortcode
6. Historique des versions et changelog

Code source

Le shortcode présenté dans ce billet nécessite la présence de la classe abstraite d’aide à la création de shortcode PPM_Shortcode. Si ce n’est pas déjà fait, récupérez-là et rendez-la disponible pour la classe AttachmentsListShortCode.

Copiez le code qui suit dans le fichier functions.php de votre thème¹.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358

<?php
/**
 * Add the new shortcode `attachments`.
 */
$attachments_list = new AttachmentsListShortCode('attachments');
$attachments_list->register();
 
/**
 * Shortcode to display a list of attachments of the current post.
 *
 * Attributes to use as follows:
 *     'exclude' - Default is none. List of IDs of the attachments to exclude of search.
 *     'orderby' - Default is 'title ASC'. How to order the attachments.
 *     'style'   - Default is 'large'. Presentation style to use.
 *
 * @author Mehdi Kabab <http://pioupioum.fr/>
 * @copyright Copyright (C) 2010 Mehdi Kabab
 * @license http://www.gnu.org/licenses/gpl.html  GNU GPL version 3 or later
 * @version 1.0.0
 * @link http://pioupioum.fr/outils-astuces/wordpress-shortcode-afficher-fichiers-joints.html
 */
class AttachmentsListShortCode extends PPM_Shortcode
{
    /**
     * Default options.
     *
     * @var array
     **/
    protected $_default_options = array(
        'exclude' => array(),
        'orderby' => 'title ASC',
        'style'   => null,
    );
 
    /**
     * Keys allowed in the query ORDER BY clause.
     *
     * @param array
     */
    protected $_allowed_orderby = array(
        'mime_type'
    );
 
    /**
     * Directory of MIME icons.
     * The path is relative to the current theme.
     *
     * @var string
     */
    private $_icons_dir;
 
    /**
     * Clause ORDER BY to be applied to sorting.
     *
     * @var string
     */
    private $_orderby = null;
 
    /**
     * Stack of the presentation styles for the attachments.
     *
     * @var ArrayObject
     **/
    private $_styles;
 
    /**
     * Constructor.
     *
     * @param string $tag Shortcode tag to be searched in post content.
     * @param string $icons_dir Directory of MIME icons.
     */
    public function __construct($tag, $icons_dir = 'images/mime')
    {
        parent::__construct($tag);
        $this->setIconsDirectory($icons_dir);
 
        $this->_styles = new ArrayObject(array(),
                                         ArrayObject::ARRAY_AS_PROPS);
        foreach ($this->_getDefaultStyles() as $tpl => $data) {
            if (isset($data['default'])) {
                $default = (boolean) $data['default'];
                unset($data['default']);
            } else {
                $default = false;
            }
            $this->setStyle($tpl, $data, $default);
        }
    }
 
    /**
     * Retrieve directory of MIME icons.
     *
     * @return string
     */
    public function getIconsDirectory()
    {
        return $this->_icons_dir;
    }
 
    /**
     * Set the directory of MIME icons.
     *
     * @return PPM_Shortcode
     */
    public function setIconsDirectory($dir)
    {
        $this->_icons_dir = trim($dir, '/') . '/';
 
        return $this;
    }
 
    /**
     * Retrieve the stack of the presentation styles.
     *
     * @return ArrayObject
     */
    public function getStyles()
    {
        return $this->_styles;
    }
 
    /**
     * Set a presentation style of the attachments.
     *
     * @param string $name Presentation style name.
     * @param array $data Style data.
     * @param boolean $default True for set this style as default style.
     * @return PPM_Shortcode
     * @throws Exception If the data are not valid.
     */
    public function setStyle($name, $data, $default = false)
    {
        if (!$this->_isValidStyle($data)) {
            throw new Exception(sprintf('Data for the style `%s` are not valid!',
                                        $name));
        }
        $this->_styles[$name] = new ArrayObject($data,
                                                   ArrayObject::ARRAY_AS_PROPS);
        if (true === $default) {
            $this->setStyleByDefault($name);
        }
 
        return $this;
    }
 
    /**
     * Retrieve name of the presentation style used by default.
     *
     * @return string
     */
    public function getStyleByDefault()
    {
        return $this->_default_options['style'];
    }
 
    /**
     * Set name of the presentation style to use by default.
     *
     * @param string $name
     * @return PPM_Shortcode
     */
    public function setStyleByDefault($name)
    {
        $this->_default_options['style'] = $name;
 
        return $this;
    }
 
    /**
     * [filter] Edit the clause ORDER BY to allow sorting by mime_type.
     *
     * @param string $orderby The ORDER BY clause.
     * @return string The new ORDER BY clause.
     */
    public function filterOrderby($orderby)
    {
        if (null !== $this->_orderby && in_array($this->_orderby, $this->_allowed_orderby)) {
            $orderby = preg_replace('#^([^\.]+\.)(\w+)(\s+ASC|DESC)$#i',
                                    '$1post_' . $this->_orderby . '$3',
                                    $orderby);
        }
 
        return $orderby;
    }
 
    /**
     * @see PPM_Shortcode::_process()
     */
    protected function _process($attributes, $content = null)
    {
        if ($this->getStyles()->offsetExists($this->getOption('style'))) {
            $style = $this->getOption('style');
        } else {
            $style = $this->getStyleByDefault();
        }
 
        // Order and Order by clauses
        list($orderby, $order) = explode(' ', $this->_default_options['orderby']);
        if (false !== strpos($this->getOption('orderby'), ' ')) {
            list($orderby, $order) = explode(' ', $this->getOption('orderby'));
        } else {
            $orderby = $this->getOption('orderby');
        }
        $this->_orderby = $orderby;
 
        // Retrieve the attachments
        $attachments = get_children(array(
            'post_parent' => get_the_ID(),
            'post_type'   => 'attachment',
            'numberposts' => -1,
            'exclude'     => $this->getOption('exclude'),
            'orderby'     => $this->_orderby,
            'order'       => ('ASC' === strtoupper($order)) ? 'ASC' : 'DESC',
            'exclude'     => $this->getOption('exclude'),
            'suppress_filters' => false // Allows to edit the query
        ));
        if (false === $attachments) {
            return '';
        }
 
        // Edit the query
        add_filter('posts_orderby', array($this, 'filterOrderby'));
 
        $result = '';
        $tpl = $this->getStyles()->$style;
        foreach ($attachments as $attachment) {
            // Do not display image attachments
            if (0 === strpos($attachment->post_mime_type, 'image/')) {
                continue;
            }
 
            // Determine the filename
            $file_type = strtr($attachment->post_mime_type, '/-', '__');
            $file_name = $this->getIconsDirectory() . $file_type . '.png';
            if (file_exists(get_stylesheet_directory() . '/' . $file_name))
            {
                $icon_file = get_bloginfo('stylesheet_directory', false) .
                             '/' . $file_name;
            }
            else
            {
                $icon_file = wp_mime_type_icon($attachment->ID);
            }
 
            if (function_exists('getimagesize')) {
                $size_attr =  getimagesize($icon_file);
                $size_attr = $size_attr[3];
            } else {
                $size_attr = '';
            }
 
            $file_path = get_attached_file($attachment->ID);
            $context = array(
                'ID'        => $attachment->ID,
                'filename'  => basename($attachment->guid),
                'file_date' => mysql2date(get_option('date_format'),
                                          $attachment->post_date),
                'file_size' => esc_attr(size_format(filesize($file_path))),
                'file_type' => $attachment->post_mime_type,
                'file_url'  => esc_attr($attachment->guid),
                'icon_atts' => $size_attr,
                'icon_path' => esc_attr($icon_file),
                'title'     => esc_attr(get_the_title($attachment->ID)),
                'label_filename'  => __('File name:'),
                'label_file_date' => __('Upload date:'),
                'label_file_size' => __('Size:')
            );
 
            // Hook for customize the context
            $context = apply_filters('attachments_list_context',
                                     $context,
                                     $attachment,
                                     $this->getStyles()->$style);
 
            $result .= $this->_compileMarkup($tpl, $context);
        }
 
        return $tpl->before . do_shortcode($content) . $result . $tpl->after;
    }
 
    /**
     * Performs substitutions in the markup of the selected presentation style.
     *
     * @param ArrayObject $tpl
     * @param array $context
     * @return string The markup after substitutions.
     */
    protected function _compileMarkup($tpl, $context)
    {
        $markup = $tpl->markup;
        foreach ($context as $key => $value) {
            $markup = str_replace('%' . $key . '%', $value, $markup);
        }
 
        return $markup;
    }
 
    /**
     * Retrieve the default stack of the presentation styles.
     *
     * Declare the `medium`, `small` and `large` presentation styles.
     *
     * @return array
     */
    protected function _getDefaultStyles()
    {
        return array(
            'medium' => array(
                'before' => '<div class="attachments-list-medium">',
                'after'  => '</div>',
                'markup' => '<div class="attachment-item attachment-%ID%">' .
                            '<a href="%file_url%" title="%title% (%file_size%)" rel="attachment">' .
                            '<img src="%icon_path%"%icon_atts% alt=""/><small>%title%</small></a>' . 
                            '</div>'
            ),
            'small'  => array(
                'before' => '<div class="attachments-list-small">',
                'after'  => '</div>',
                'markup' => '<div class="attachment-small-icon attachment-%ID%">' .
                            '<img src="%icon_path%"%icon_atts% alt=""/>' .
                            '<a href="%file_url%" title="%title%" rel="attachment">' .
                            '%title%</a>&nbsp;(%file_size%)' . 
                            '</div>'
            ),
            'large'  => array(
                'before' => '<div class="attachments-list-large">',
                'after'  => '</div>',
                'markup' => '<dl class="attachment-item attachment-%ID%">' .
                            '<dt><a href="%file_url%" title="%title%" rel="attachment">' .
                            '<img class="alignleft" src="%icon_path%"%icon_atts% alt=""/>' .
                            '%title%</a></dt>' .
                            '<dd><span>%label_filename%</span> %filename%</dd>' .
                            '<dd><span>%label_file_date%</span> %file_date%</dd>' .
                            '<dd><span>%label_file_size%</span> %file_size%</dd>' .
                            '</dl>',
                'default' => true
            )
        );
    }
 
    /**
     * Test if the data of a presentation style are well formed.
     *
     * @param array $data
     * @return boolean
     */
    protected function _isValidStyle($data)
    {
        $ok = 3 === count($data) &&
              isset($data['before']) &&
              isset($data['after']) &&
              isset($data['markup']);
 
        return $ok;
    }
 
}
?>

Il vous faut également intégrer à votre thème les styles CSS qui suivent. Ceux-ci demeurant être une suggestion.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44

.attachments-list-large, .attachments-list-medium, .attachments-list-small {
  margin-bottom: 1em;
}
.attachments-list-large .attachment-item img, .attachments-list-medium .attachment-item img, .attachments-list-small .attachment-item img {
    border: none;
}
.attachments-list-large .attachment-item dl {
    margin: 0 0 1.5em 1em;
}
.attachments-list-large .attachment-item dt {
    font-weight: bold;
}
.attachments-list-large .attachment-item dd {
    font-size: 0.85em;
    margin-left: 1.5em;
}
.attachments-list-large .attachment-item img {
    display: inline;
    float: left;
}
.attachments-list-large .attachment-item img {
    margin-right: 1em;
}
.attachments-list-medium .attachment-item {
    display: inline-table;
    margin-bottom: 1.5em;
    padding: 0 0.15em;
    text-align: center;
    vertical-align: top;
    width: 10em;
}
.attachments-list-medium .attachment-item a {
    text-decoration: none;
}
.attachments-list-medium .attachment-item small {
    display: block;
    font-size: 0.85em;
}
.attachments-list-small img {
    margin-right: 5px;
    vertical-align: text-bottom;
    height: 16px;
    width: 16px;
}

Ou si vous utilisez SCSS :

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54

.attachments-list-large, .attachments-list-medium, .attachments-list-small {
    margin-bottom: 1em;
    .attachment-item {
        img {
            border: none;
        }
    }
}
.attachments-list-large {
    .attachment-item {
        $space: 1em;
        dl {
            margin: 0 0 ($space + 0.5em) $space;
        }
        dt {
            font-weight: bold;
        }
        dd {
            font-size: 0.85em;
            margin-left: ($space + 0.5em);
        }
        img {
            display: inline;
            float: left;
            margin: {
                right: $space;
            }
        }
    }
}
.attachments-list-medium {
    .attachment-item {
        display: inline-table;
        margin-bottom: 1.5em;
        padding: 0 0.15em;
        text-align: center;
        width: 10em;
        a {
            text-decoration: none;
        }
        small {
            display: block;
            font-size: 0.85em;
        }
    }
}
.attachments-list-small {
    img {
        margin-right: 5px;
        vertical-align: text-bottom;
        height: 16px;
        width: 16px;
    }
}

Différents styles d’affichage

Le shortcode attachments propose trois formats d’affichage des pièces jointes : medium, large (par défaut) et small.

[attachments style="small"]

[attachments style="medium"]

[attachments style="large"]

Exemples d’utilisation

Usage basique

[attachments]

Exclure des documents de la liste

Ici, nous excluons de la liste les documents ayant les identifiants 53 et 56.

[attachments exclude="53,56"]

Liste des documents triés par date de mise en ligne

[attachments orderby="date"]

Liste des documents triés par date, les plus récents en premier

[attachments orderby="date DESC"]

Liste des documents triés par type de document

[attachments orderby="mime_type"]

Cumul des paramètres

Les paramètres peuvent être cumulés, sans ordre précis.

[attachments style="large" exclude="53" orderby="date"]

Ajouter un titre à la liste

Le shortcode attachments existe aussi en forme englobante. Tout contenu englobé préfixera la liste des pièces jointes générées.

[attachments]
<h2>Avec un contenu</h2>
<p>Ce shortcode englobe le titre qui précède et ce paragraphe.</p>
[/attachments]

Liste des paramètres

Voici la liste des paramètres acceptés par le shortcode attachments :

exclude
(optionnel) La liste des ID séparés par des virgules des documents à exclure de la liste. Vide par défaut. Toutes les pièces jointes au contenu sont affichées.

orderby
(optionnel) Le type de tri appliqué à la liste. Par défaut title ASC, les document sont triés par titre et par ordre alphabétique.

style (optionnel) Le type de présentation de la liste. Trois formats sont disponibles : small, medium et large (par défaut). Se reporter aux exemples pour avoir des aperçus.

Personnaliser le shortcode

Afin de correspondre aux besoins du plus grand nombre, le shortcode attachments offre diverses possibilités de personnalisation.

Ajouter un type de présentation

Si vous souhaitez afficher une simple liste ordonnée des pièces jointes, déclarez un nouveau style au shortcode comme suit :

1
2
3
4
5
6
7
8
9
10

<?php
$attachments_list = new AttachmentsListShortCode('attachments');
$ol_style = array(
    'before' => '<ol class="attachments-list-ol">',
    'after'  => '</ol>',
    'markup' => '<li><a href="%file_url%" rel="attachment">%title%</a></li>'
);
$attachments_list->setStyle('ol', $ol_style)
                 ->register();
?>

Puis, appelez-le dans un billet :

[attachments style="ol"]

Notez que la déclaration d’un style peut se faire après l’enregistrement du shortcode. La seule contrainte étant de la faire avant l’appel au shortcode par WordPress.

Si vous souhaitez définir un style de présentation à utiliser par défaut, deux possibilités :

• Lors de la déclaration d’un style, préciser la clé 'default' => true.
• À l’aide de la méthode setStyleByDefault($name) : $attachments_list->setStyleByDefault('ol);.

Ci-après, la liste des différentes tags disponibles pour vos styles :

• ID. L’identifiant de la pièce jointe.
• title. Le titre de la pièce jointe.
• filename. Le nom de fichier de la pièce jointe.
• file_date. La date de transfert de la pièce jointe.
• file_size. La taille de la pièce jointe, en [K|M]Bytes.
• file_type. Le type MIME du fichier.
• file_url. L’URL de téléchargement de la pièce jointe.
• icon_atts. D’éventuels attributs ajoutés à la balise <img/>.
• icon_path. L’URL de l’icône illustrative.
• label_filename. Label annonçant le titre du fichier.
• label_file_date. Label annonçant la date de transfert du document.
• label_file_size. Label annonçant la taille de la pièce jointe.

Personnaliser les icônes

Par défaut le shortcode affiche les icônes disponibles dans WordPress. Le shortcode permet d’utiliser un set d’icône personnalisé.

Il suffit pour cela de déclarer un chemin d’accès aux icônes des différents types MIME. Par défaut images/mime. Ce chemin doit être relatif au dossier du thème.

1
2
3
4
5

<?php
$attachments_list = new AttachmentsListShortCode('pièces jointes');
$attachments_list->setIconsDirectory('img/icons')
                 ->register();
?>

Afin que les icônes soient récupérées, les fichiers images des types MIME doivent être de la forme type_mime.png.
C’est à dire qu’un document PDF de type MIME application/pdf aura pour icône le fichier application_pdf.png. Un document ODT de type MIME application/vnd.oasis.opendocument.text se référera quand à lui à l’image application_vnd.oasis.opendocument.text.png.

J’utilise le pack d’icônes Oxygen dans les exemples présentés de cette page.

Filtre attachments_list_context

Le filtre attachments_list_context permet de modifier le contexte qui sera utilisé pour réaliser les substitions dans le style de présentation.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

<?php
function filter_attachments_list_context($context, $attachment, $size)
{
    // WordPress ne comportant pas de chaîne 'Size:', cette
    // dernière ne peut être localisée automatiquement.
    // Travaillant sur un site exclusivement localisé en français
    // on peut se permettre les deux traitements qui suivent.
    $context['label_file_size'] = 'Taille&nbsp;:';
    $context['file_size'] = strtr($context['file_size'], 'B', 'o');
 
    return $context;
}
 
add_filter('attachments_list_context', 'filter_attachments_list_context', 10, 3);
?>

Historique des versions et changelog

1.0.0

• Version initiale.

Continuez votre lecture sur des sujets similaires

• WordPress : une classe abstraite pour aider la création de shortcodes
• WordPress : autoriser l’upload de fichiers au format non-supporté
• WordPress : récupération avancée des images d’un article
• WordPress : lister les images d’un article sur une page media
• WordPress et SmartyPants : des légendes qui disparaissent

Une petite classe PHP abstraite pour aider la création de shortcodes dans WordPress.

Pour un exemple d’utilisation, se reporter au shortcode attachments.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199

<?php
/**
 * Abstract class to create shortcodes in WordPress.
 *
 * @author Mehdi Kabab <http://pioupioum.fr/>
 * @copyright Copyright (C) 2010 Mehdi Kabab
 * @license http://www.gnu.org/licenses/gpl.html  GNU GPL version 3 or later
 * @version 1.0.0
 * @link http://pioupioum.fr/snippets/wordpress-create-shortcode-class.html
 */
abstract class PPM_Shortcode
{
    /**
     * Default options.
     *
     * @var array
     **/
    protected $_default_options = array();
 
    /**
     * Options after initialization of shortcode.
     *
     * @var ArrayObject
     */
    private $_options;
 
    /**
     * Tag name of shortcode.
     *
     * @var string
     **/
    private $_name = null;
 
    /**
     * Constructor.
     *
     * @param string $tag Shortcode tag to be searched in post content.
     */
    public function __construct($tag)
    {
        $this->setTagName($tag);
        $this->_options = new ArrayObject(array(),
                                          ArrayObject::ARRAY_AS_PROPS);
    }
 
    /**
     * Excecute the shortcode.
     *
     * Called by the shortcode API.
     *
     * @param array $attributes Attributes used in the call of the shortcode.
     * @param string $content The content of the shortcode. Default to null.
     * @return string
     */
    public function run($attributes, $content = null)
    {
        $this->setOptions(shortcode_atts($this->_default_options, $attributes));
 
        return $this->_process($attributes, $content);
    }
 
    /**
     * Check if the current shortcode tag already registered.
     *
     * @global array $shortcode_tags
     * @return boolean
     */
    public function isRegistered()
    {
        global $shortcode_tags;
 
        return array_key_exists($this->getTagName(), $shortcode_tags);
    }
 
    /**
     * Register the shortcode.
     *
     * @return PPM_Shortcode
     * @throws Exception If the shortcode already exists.
     */
    public function register()
    {
        if ($this->isRegistered()) {
            throw new Exception(sprintf('The shortcode `%s` already exists!',
                                        $this->getTagName()));
        }
 
        add_shortcode($this->getTagName(), array($this, 'run'));
 
        return $this;
    }
 
    /**
     * Unregister the shortcode.
     *
     * @return PPM_Shortcode
     */
    public function unregister()
    {
        remove_shortcode($this->getTagName());
 
        return $this;
    }
 
    /**
     * Retrieve the name of shortcode.
     *
     * @return string
     */
    public function getTagName()
    {
        return $this->_name;
    }
 
    /**
     * Set the name of shortcode.
     *
     * @param string $name Shortcode tag to be searched in post content.
     * @return PPM_Shortcode
     */
    public function setTagName($name)
    {
        $this->_name = $name;
 
        return $this;
    }
 
    /**
     * Retrieve the requested option.
     *
     * @param string $name The option to search.
     * @return mixed
     */
    public function getOption($name)
    {
        return $this->_options->offsetGet($name);
    }
 
    /**
     * Test if an option exists for the shortcode.
     *
     * @param string $name
     * @return boolean
     */
    public function hasOption($name)
    {
        return $this->_options->offsetExists($name);
    }
 
    /**
     * Set an option.
     *
     * @param string $name
     * @param mixed $value
     * @return PPM_Shortcode
     */
    public function setOption($name, $value)
    {
        $this->_options->offsetSet($name, $value);
 
        return $this;
    }
 
    /**
     * Retrieve the options.
     *
     * @return ArrayObject
     */
    public function getOptions()
    {
        return $this->_options;
    }
 
    /**
     * Set the options.
     *
     * @param array $options
     * @return PPM_Shortcode
     */
    public function setOptions($options)
    {
        foreach ((array) $options as $name => $value) {
            $this->setOption($name, $value);
        }
 
        return $this;
    }
 
    /**
     * Concrete excecution of the shortcode.
     *
     * @param array $attributes Attributes used in the call of the shortcode.
     * @param string $content The content of the shortcode. Default to null.
     * @return string
     */
    abstract protected function _process($attributes, $content = null);
 
}
?>

Continuez votre lecture sur des sujets similaires

• Shortcode WordPress : afficher les documents liés aux billets
• WordPress et SmartyPants : des légendes qui disparaissent
• Shortcode WordPress : intégrer un flux RSS
• Photon : guide d’installation sur Mac OS X Snow Leopard
• WordPress : forcer le chargement de jQuery en bas de page

Le snippet qui suit ne se limite pas à forcer le chargement de jQuery en pied de page. Il permet également de remplacer la version locale à l’installion WordPress par une version équivalente, mais servie par le service Google Libraries API.

Si un script tierce remplace la version jQuery, son chargement sera forcé en bas de page.

Bien évidemment, il est aisé d’adapter ce snippet pour n’importe quel autre fichier JavaScript.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48

<?php
/**
 * Force load jQuery in the footer.
 *
 * @param boolean $google Set to true for load jQuery from the
 *                        Google Libraries Api servers. Default to false.
 * @global WP_Scripts $wp_scripts
 */
function forcejQueryInFooter($google = false)
{
    // Do not apply in the WordPress admin Panel.
    if (is_admin())
    {
        return;
    }
 
    global $wp_scripts;
 
    if (!is_a($wp_scripts, 'WP_Scripts'))
    {
        $wp_scripts = new WP_Scripts();
    }
    $jquery = $wp_scripts->query('jquery', 'registered');
    if (false !== $jquery)
    {
        $jquery_google = 'http://ajax.googleapis.com/ajax/libs/jquery/%s/jquery.min.js';
        wp_deregister_script($jquery->handle);
        wp_register_script(
            $jquery->handle,
            ($google) ? sprintf($jquery_google, $jquery->ver) : $jquery->src,
            $jquery->deps,
            ($google) ? null : $jquery->ver,
            true
        );
    }
}
 
/**
 * Force load jQuery in the footer from the Google Libraries Api servers.
 *
 * @see forcejQueryInFooter()
 */
function forcejQueryGoogleLibrariesApiInFooter()
{
    forcejQueryInFooter(true);
}
 
add_action('wp_enqueue_scripts', 'forcejQueryGoogleLibrariesApiInFooter', 101);

Remplacez forcejQueryGoogleLibrariesApiInFooter par forcejQueryInFooter dans l’ajout d’action à wp_enqueue_scripts pour utiliser la version de jQuery livrée avec WordPress.

Continuez votre lecture sur des sujets similaires

• WordPress jQuery UI Effects
• Shortcode WordPress : afficher les documents liés aux billets
• WordPress : une classe abstraite pour aider la création de shortcodes
• JavaScript : optimiser le calcul de l’intersection de tableaux de grandes tailles
• Optimiser le chargement des AdSense