Synchroniser Delicious et WordPress: l’API de WordPress

Cet article est le quatrième volet de notre série sur La synchronisation entre WordPress et Delicious. Nous avons déjà étudié les plugins, ainsi que l’API de Delicious. Aujourd’hui, nous allons regarder ce que propose WordPress.

Le moins que l’on puisse dire, c’est que la doc n’est pas très bavarde sur le sujet.
Même sur la page Function Reference, censée nous donner la liste de toutes les fonctions disponibles, nous ne trouvons absolument rien sur la gestion des liens.

Organisation des fichiers

Sans documentation, la façon la plus simple de récupérer des infos est de regarder les fichiers de WordPress (non, pas G**gle pour cette fois). D’une manière générale, je conseille à ceux qui veulent se lancer dans le développement de plugin, de lire les sources de WordPress, ou d’autres plugins. Cela permet de progresser plus vite que de simplement lire la documentation.

Les fichiers contenant les fonctions pour gérer les liens sont rangés dans les deux arborescences wp-admin et wp-includes.

Pour la partie « administration », les fichiers sont les suivants:

Répertoire Fichier Commentaires
wp-admin link-manager Affiche la page des gestions des liens (la liste)
wp-admin link.php Récupère les requêtes de l’administrateur, et lance les actions (ajout, effacement, …)
wp-admin link-add.php
edit-link-form.php
Gère l’ajout et l’édition d’un lien
wp-admin link-category.php
edit-link-form.php
Gère les categories de liens (formulaire et actions associées)
wp-admin link-parse-opml.php Parse un fichier OPML et prepare l’import des liens dans WordPress
wp-admin/includes bookmark.php L’API proprement dite. Contient les fonctions pour ajouter, modifier, effacer des liens

Pour la partie « public », les fichiers sont les suivants:

Répertoire Fichier Commentaires
wp-includes bookmark.php Le fichier contient des fonctions très intéressantes pour le développement des plugins, et qui sont utilisées par la fonction présente dans le fichier suivant
wp-includes bookmark_template.php Contient LA fonction pour lister les bookmarks wp_list_bookmarks

Organisation de la base de données

Tous les bookmarks sont stockés dans une seule table wp_links qui contient ni plus ni moins que les champs qui apparaissent dans la page d’édition des bookmarks.

Les liens peuvent être classés par catégories (de liens). Ces catégories sont gérées comme des termes d’une taxonomie appelée ‘link_category’ par WordPress, qui utilise donc les tables habituelles pour cela: wp_terms, wp_term_taxonomy et wp_term_relationships.

Récupération des informations

La fonction la plus connue est certainement wp_list_bookmarks qui accepte une multitude d’options. 80% du code de cette fonction consiste d’ailleurs à analyser les paramètres. Mais cette fonction est très orientée « template »: elle permet l’affichage des bookmarks, mais pas la récupération simple de ces liens et de leurs attributs sous la forme d’un tableau par exemple.

Mais wp_list_bookmarks appelle une fonction très intéressante pour nous: get_bookmarks, qui prend quelques paramètres en entrée et nous renvoie une liste des bookmarks sous forme de tableau. Les paramètres sont les suivants:

1
2
3
4
5
6
7
8
9
10
11
12
$defaults = array(
   'orderby'        => 'name', 
   'order'          => 'ASC',
   'limit'          => -1, 
   'category'       => '',
   'category_name'  => '', 
   'hide_invisible' => 1,
   'show_updated'   => 0, 
   'include'        => '',
   'exclude'        => '', 
   'search'         => ''
);

Le tableau que renvoie cette fonction est un tableau d’objets. Ces objets contiennent à peu près les mêmes champs que la table wp-links de la base de données:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
$linkdata = array(
   'link_id'            =>
   'link_name'       =>
   'link_url'           =>
   'link_rating'       =>
   'link_image'       =>
   'link_target'      =>
   'link_visible'       =>
   'link_owner'       =>
   'link_notes'       =>
   'link_description' =>
   'link_rss'         =>
   'link_rel'         =>
   'link_category'    => array( id des categories )
);

La plupart des fonctions gérant les bookmarks utilisent cet objet, ce qui est assez pratique.

Le fichier wp-includes/bookmark.php contient également la fonction get_bookmark pour obtenir les attributs d’un bookmark en particulier.

Avec ces fonctions, nous sommes principalement capable de récupérés les informations un bookmark, ou l’ensemble des bookmarks de la base.
Exemple d’utilisation:

1
2
3
4
$links_list = get_bookmarks();
foreach ($links_list as $link) {
    echo '<a href="'.$link->link_url.'" title=".$link->link_description.'">'.$link->link_name.'</a><br />';
}

Les catégories de liens peuvent être collectées avec les fonctions wp_get_object_terms et/ou get_terms. J’ai déjà parlé de ces fonctions dans l’article WordPress: Récupérer les informations sur la taxonomie.

Manipulation des bookmarks

Nous savons donc lister nos bookmarks, regardons maintenant comment les manipuler.
Cinq fonctions principales sont disponibles:

Fonction Commentaires
wp_delete_link( $link_id ) Efface le lien spécifié par son identifiant. Gère également les catégories associées
$link_id=wp_insert_link(
$linkdata,
$wp_error=false)
Ajoute ou modifie le lien spécifié en paramètre. $linkdata est un objet dont j’ai déjà décrit la structure précédemment.
wp_update_link( $linkdata ) Modifie un lien avec les informations passées en paramètre. Ces informations doivent obligatoirement contenir le champ link_id. A noter que cette fonction appelle wp_insert_link.
wp_set_link_cats(
link_id = 0,
$link_categories = array() )
Gère les catégories des liens
wp sanitize_bookmark($bookmark) Permet de « nettoyer » la fiche d’un bookmark avant de l’insérer.

Quelques exemples

Récupérer toutes les catégories des liens

1
2
3
4
5
6
$results = get_terms('link_category');
if ($results) {
   foreach ($results as $result) {
      echo $result->term_id.' '.$result->name.'<br />';
   }
}

Ajouter un lien

1
2
3
4
5
6
7
8
9
10
11
$linkdata = array(
   'link_id'          => 0,
   'link_name'        => 'WordPress Plugin Repository',
   'link_url'	         => 'http://wordpress.org/extend/plugins',
   'link_target'      => '',
   'link_visible'     => 'Y',
   'link_notes'       => 'Most of plugins developed for WordPress',
   'link_description' => '',
   'link_category'    => array( 5 )
);
$link_id = wp_insert_link( $linkdata );

Conclusion

L’API de WordPress pour manipuler les bookmarks nous propose un nombre assez restreints de fonctions. Celles-ci sont cependant complètes, et très pratiques. Elles effectuent en effet un grand nombre de vérifications, et permettent donc de manipuler les bookmarks avec un minimum de code. Par exemple, wp_insert_link gère à la fois les ajouts, les modifications d’un bookmark, mais effectue également tous les changements de catégories associés.