Emmanuel Georjon

This post is the fourth of a serie on Synchronizing WordPress and Delicious. We previously studied the plugins, and the plugins, and the Delicious API. Today we will take a look to the WordPress API.

This post is an english translation of the post Synchroniser Delicious et WordPress: l’API de WordPress

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:

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

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 href="'.$link->link_url.'" title=".$link->link_description.'">'.$link->link_name.'</a><br />';
}

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:

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->term_id.' '.$result->name.'<br />';
   }
}

Add a link

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

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.

This post is an english translation of the post Synchroniser Delicious et WordPress: l’API de WordPress

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:

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

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 href="'.$link->link_url.'" title=".$link->link_description.'">'.$link->link_name.'</a><br />';
}

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:

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->term_id.' '.$result->name.'<br />';
   }
}

Add a link

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

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.