Synchronize Delicious and WordPress: the WordPress API

This post is the fourth of a serie on Synchronizing WordPress and Delicious. We previously studied the plugins, and the delicious API.

Unfortunately, the WordPress documentation doesn’t say a lot of things on this subject.
Even on the page Function Reference, supposed to give us the list of all available functions, we can’t find anything on the links management.

Files

Without documentation, the easiest way to get information is to look at the source code of WordPress (G**oogle is not often our friend in this kind of subject). More generally, I recommend to read this source code of WordPress (and some plugins), to everyone who want to develop a plugin. These readings allow to progress quicker than just read the documentation.

The files containing functions to manage links are stored into two directory trees: wp-admin and wp-includes.

For the « administration » side, files are the following:

Path File Comments
wp-admin link-manager Displays the page « Management of links » (the list of bookmarks)
wp-admin link.php Gets request from users, and launches actions (adding, deleting …)
wp-admin link-add.php
edit-link-form.php
Manages the add and edit action
wp-admin link-category.php
edit-link-form.php
Manages categories of links (forms and associated actions)
wp-admin link-parse-opml.php Parses OPLM files, and prepare the data to be imported into the links database of WordPress
wp-admin/includes bookmark.php The API itself. Contains the functions to add, edit and delete links

For the « public » part, files are the following:

Path File Comments
wp-includes bookmark.php The file contains some very interesting functions for plugin development. These functions are used by those that are stored in the following file
wp-includes bookmark_template.php Contains THE function to list bookmarks wp_list_bookmarks

Database structure

All bookmarks are stored into a single table wp_links which contains all fields visible in the bookmarks edition page. Links can be divided by categories (of links). These categories are managed as « terms » of a taxonomy named link_category. This taxonomy and terms are managed as usual by WordPress using tables wp_terms, wp_term_taxonomy and wp_term_relationships.

Getting bookmarks information

The most known function is probably wp_list_bookmarks, that has many options. 80% of the source code of this function is dedicated to the analyzis of the parameters. But wp_list_bookmarks is mainly made for templates: it allows to display bookmarks, but doesn’t give us a simple array of bookmarks and their attributs.

In fact, wp_list_bookmarks calls an another function that should be more interesting for us: get_bookmarks. This one takes some parameters, and returns a list of bookmarks as an array. The parameters are the following:

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'         => ''
);

The function returns an array of objects. These objects contains rather the same fields than the table wp-links:

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( list of categories' ids)
);

Most of the functions managing the bookmarks are using these objects.

The file wp-includes/bookmark.php contains also the function get_bookmark to get attributs of a specific bookmark.

With these functions, we are mainly able to get information from a bookmark or a set of bookmarks.
Example of use:

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

The categories of links can be collected with the functions wp_get_object_terms and/or get_terms. I already spoke about these functions in a the previous post WordPress: how to get data from taxonomy?

Bookmarks management

We know how to list our bookmarks, now we will look how to manage them.

We have mainly five functions available:

Function Comments
wp_delete_link( $link_id ) Delete the link specified by its id. Manage also the relevant categories.
$link_id=wp_insert_link(
$linkdata,
$wp_error=false)
Add or edit the link specified. $linkdata is an object as previously described.
wp_update_link( $linkdata ) Modify a bookmark with the information specified. These information must contain the field link_id to identify the bookmark to modify. The function calls wp_insert_link, that we can use directly.
wp_set_link_cats(
link_id = 0,
$link_categories = array() )
Manage categories of links
wp sanitize_bookmark($bookmark) Allows to « sanitize » a bookmark object before inserting it into the database.

Some examples

Get all categories of links

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

Add a link

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

Conclusion

The WordPress API provides us a limited number of functions, but these are featured and very useful. They perform a lot of checks, and allow to use to manage bookmarks with a minimum number of lines of PHP. For example, wp_insert_link adds or edits a bookmark, but manages also the categories.-delicious-1495″>the Delicious API. Today we will take a look to the WordPress API.

Unfortunately, the WordPress documentation doesn’t say a lot of things on this subject.
Even on the page Function Reference, supposed to give us the list of all available functions, we can’t find anything on the links management.

Files

Without documentation, the easiest way to get information is to look at the source code of WordPress (G**oogle is not often our friend in this kind of subject). More generally, I recommend to read this source code of WordPress (and some plugins), to everyone who want to develop a plugin. These readings allow to progress quicker than just read the documentation.

The files containing functions to manage links are stored into two directory trees: wp-admin and wp-includes.

For the « administration » side, files are the following:

Path File Comments
wp-admin link-manager Displays the page « Management of links » (the list of bookmarks)
wp-admin link.php Gets request from users, and launches actions (adding, deleting …)
wp-admin link-add.php
edit-link-form.php
Manages the add and edit action
wp-admin link-category.php
edit-link-form.php
Manages categories of links (forms and associated actions)
wp-admin link-parse-opml.php Parses OPLM files, and prepare the data to be imported into the links database of WordPress
wp-admin/includes bookmark.php The API itself. Contains the functions to add, edit and delete links

For the « public » part, files are the following:

Path File Comments
wp-includes bookmark.php The file contains some very interesting functions for plugin development. These functions are used by those that are stored in the following file
wp-includes bookmark_template.php Contains THE function to list bookmarks wp_list_bookmarks

Database structure

All bookmarks are stored into a single table wp_links which contains all fields visible in the bookmarks edition page. Links can be divided by categories (of links). These categories are managed as « terms » of a taxonomy named link_category. This taxonomy and terms are managed as usual by WordPress using tables wp_terms, wp_term_taxonomy and wp_term_relationships.

Getting bookmarks information

The most known function is probably wp_list_bookmarks, that has many options. 80% of the source code of this function is dedicated to the analyzis of the parameters. But wp_list_bookmarks is mainly made for templates: it allows to display bookmarks, but doesn’t give us a simple array of bookmarks and their attributs.

In fact, wp_list_bookmarks calls an another function that should be more interesting for us: get_bookmarks. This one takes some parameters, and returns a list of bookmarks as an array. The parameters are the following:

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

The function returns an array of objects. These objects contains rather the same fields than the table wp-links:

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

Most of the functions managing the bookmarks are using these objects.

The file wp-includes/bookmark.php contains also the function get_bookmark to get attributs of a specific bookmark.

With these functions, we are mainly able to get information from a bookmark or a set of bookmarks.
Example of use:

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

The categories of links can be collected with the functions wp_get_object_terms and/or get_terms. I already spoke about these functions in a the previous post WordPress: how to get data from taxonomy?

Bookmarks management

We know how to list our bookmarks, now we will look how to manage them.

We have mainly five functions available:

Function Comments
wp_delete_link( $link_id ) Delete the link specified by its id. Manage also the relevant categories.
$link_id=wp_insert_link(
$linkdata,
$wp_error=false)
Add or edit the link specified. $linkdata is an object as previously described.
wp_update_link( $linkdata ) Modify a bookmark with the information specified. These information must contain the field link_id to identify the bookmark to modify. The function calls wp_insert_link, that we can use directly.
wp_set_link_cats(
link_id = 0,
$link_categories = array() )
Manage categories of links
wp sanitize_bookmark($bookmark) Allows to « sanitize » a bookmark object before inserting it into the database.

Some examples

Get all categories of links

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

Add a link

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

Conclusion

The WordPress API provides us a limited number of functions, but these are featured and very useful. They perform a lot of checks, and allow to use to manage bookmarks with a minimum number of lines of PHP. For example, wp_insert_link adds or edits a bookmark, but manages also the categories.