La gestion des pièces jointes (attachments), n’est pas ce que l’on peut appeler un point fort de WordPress. Avec le Media Manager, la version 2.5.x améliore sensiblement l’ergonomie d’un point de vue utilisateur. L’API s’étoffe également, mais la documentation reste assez pauvre. Voici donc un résumé des fonctions que WordPress met à notre disposition pour la gestion des attachements.
La base de données
Les pièces jointes sont stockées dans la base de données dans la table wp_posts sous forme d’articles (posts). Ils sont considérés comme des « sous-articles », et sont rattachés à des articles principaux. Les champs de la table wp_posts concernés sont:
| Champ | Type | Valeur | Description |
|---|---|---|---|
| ID | bigint(20) | Identifiant unique de l’article | |
| post_content | longtext | Description | |
| post_title | text | Nom du fichier | |
| post_excerpt | text | Intitulé | |
| post_status | varchar(20) | inherit | |
| post_parent | bigint(20) | ID de l’article auquel est attachée la pièce jointe | |
| guid | varchar(255) | url du fichier (de la pièce jointe) | |
| post_type | varchar(20) | attachment | |
| post_mime_type | varchar(100) | Type mime du document (image/jpeg par exemple) |
Les autres champs ne sont pas utilisés.
L’API
Les fonctions
Les fonctions sont toutes regroupées dans trois fichiers
wp-include/posts.php,wp-include/post_template.php,wp-include/media.php.
Il faut distinguer deux catégories de fonctions: la première permet de manipuler les pièces jointes, et la seconde permet d’en récupérer la liste et les paramètres pour les afficher.
Dans la première catégorie, nous trouvons wp_delete_attachment, wp_insert_attachment ou wp_update_attachment_metadata, qui permettent respectivement d’ajouter, d’effacer ou de modifier
une pièce jointe.
Les fonctions de la seconde catégorie sont plus nombreuses, mais souvent redondantes. Les plus importantes sont:
| Fonction | Arguments / Valeur par défaut |
Description |
|---|---|---|
| wp_attachment_is_image | $id | True ou False selon que la pièce jointe est une image ou pas |
| wp_get_attachment_image_src | $id, $size=’thumbnail’, $icon = false |
Renvoi un tableau contenant l’URL de l’image, ainsi que ses dimensions (hauteur, largeur). L’image peut être la pièce jointe elle-même ou une vignette |
| wp_get_attachment_image | $attachment_id, $size=’thumbnail’, $icon = false |
Renvoi la balise html pointant sur l’image ou la vignette (thumbnail). La réponse prend donc la forme: <img src= »" …> |
| wp_count_attachments | $mime_type | Renvoi un tableau avec la liste des types mime, et le nombre de documents par type (Array ($mime, $count)) |
| wp_get_attachment_link | $id = 0, $size = ‘thumbnail’, $permalink = false, $icon = false |
Renvoi le [perma]lien complet permettant l’affichage de la pièce jointe spécifiée. |
| get_children | $args, $output | Renvoi la liste des pièces jointes, en fonction des critères spécifiés dans args. La syntaxe est identique à la fonction get_posts $ouput peut prendre les valeurs OBJECT, ARRAY_N, ou ARRAY_A. La fonction appelle get_posts en ajoutant les arguments numberposts=-1, post_type=attachment et post_status => inherit |
| wp_get_attachment_metadata | $post_id, $unfiltered = false |
|
| wp_mime_type_icon | $id | Renvoi une url vers l’icône correspondant au type mime de la pièce jointe. |
size peut prendre les valeurs thumb, thumbnail, medium ou full.
Exemple d’application des fonctions précédentes: Affichage d’une liste de documents attachés (sans les images) à un article spécifié par $id.
$attachments = get_children( array( 'post_parent' => $post_id, 'post_status' => 'inherit', 'post_type' => 'attachment') ); if ( empty($attachments) ) return ''; $output = "\n"; foreach ( $attachments as $id =>; $attachment ) { if (substr($attachment->post_mime_type, 0, 5) != 'image') { $output .= wp_get_attachment_link($id, 'thumbnail', true, true) .' '; $output .= wp_get_attachment_link($id, 'thumbnail', true, false) . "\n"; } } echo $output;
Ce code va générer le HTML suivant:
<a title="album_martinique_2007" href="url 1">
<img class="attachment-thumbnail" src="url thumbnail" alt="" width="46" height="60" />
</a>
<a title="album_martinique_2007" href="url 1">album_martinique_2007</a>
<a title="Calendrier" href="url 2">
<img class="attachment-thumbnail" src="url thumbnail" alt="" width="46" height="60" />
</a>
<a title="Calendrier" href="url 2">Calendrier</a>
<a title="IPTC XMP Core" href="url 3">
<img class="attachment-thumbnail" src="url thumbnail" alt="" width="46" height="60" />
</a>
<a title="IPTC XMP Core" href="url thumbnail">IPTC XMP Core</a>ce qui donne:
Les fonctions get_posts et get_children ont quelques limitations. Par exemple, nous ne pouvons pas récupérer les pièces jointes d’un ensemble de catégories, ou exclure une ou plusieurs catégories. Dans ce cas, il reste à « taper » directement dans la base de données, ce qui n’est pas conseillé, et rend le développement plus vulnérable aux changements de version.
Les filtres et les hooks
Les filtres et les hooks ne sont pas très nombreux:
| Fonctions | Filtres | Actions (Hooks) |
|---|---|---|
| wp_insert_attachment | edit_attachment, add_attachment |
|
| wp_delete_attachment | wp_delete_file | delete_attachment |
| wp_get_attachment_url | wp_get_attachment_url | |
| wp_get_attachment_metadata | wp_get_attachment_metadata | |
| wp_get_attachment_image_src | icon_dir | |
| wp_mime_type_icon | icon_dir icon_dirs wp_mime_type_icon |
|
| wp_ext2type | ext2type |
Autres ressources
WordPress inclut également une série de vignettes pour décrire les types mime des documents. Ces images se trouvent dans le répertoire /wp-includes/images/crystal.
Les filtres icon_dir, icon_dirs et wp_mime_type_icon permettent d’influer sur l’affichage des vignettes (thumbnail). ext2type permet d’ajouter des types de documents.
Ces filtres ne sont pas complètement efficaces, car mal gérés dans certaines fonctions (wp_get_attachment_link par exemple). Je n’ai réellement réussi à m’en servir qu’avec la fonction wp_mime_type_icon.
Les templates
Les pièces jointes sont stockées comme de simples articles dans la base de WordPress. Au niveau des templates, il faut pourtant différencier un article principal et une pièce jointe, pour adapter l’affichage. WordPress propose quelques fonctions complémentaires pour gérer les attachments dans les thèmes.
Il existe d’abord un tag conditionnel (conditional tag), is_attachment() qui permet de savoir si nous sommes dans le cas d’un article ou d’une pièce jointe. WordPress propose également des templates dédiées. Lorsque l’on clique sur un lien correspondant à une pièce jointe, WordPress cherchera à utiliser les templates suivantes (dans cet ordre):
image.phpattachment.phpindex.php
Les templates image.php et attachment.php peuvent être créees pour afficher proprement une pièce jointe. Vous pouvez regarder, à titre d’exemple, la template image.php du thème classic, disponible par défaut dans WordPress.
Le permalien d’une pièce jointe prend la forme suivante:
http://<url du blog>/<url de l'article>/<url de la pièce jointe>
Conclusion
Depuis les versions 2.5.x, WordPress améliore sensiblement la gestion des pièces jointes, à la fois côté utilisateur, avec le Media Manager, et du côté développeur, avec une série de fonctions et de filtres permettant de proposer de nouvelles fonctionnalités, sans avoir besoin de requêter directement la base de données. Il subsiste encore quelques points à améliorer, notamment dans la gestion des vignettes.
