Dev:Taxonomy

From Habari Project

Jump to: navigation, search

Habari's taxonomy system provides a powerful way for developers to define relationships between things. For example, tagging posts is implemented using the taxonomy system.

Contents

Vocabularies and Terms

The building blocks of the taxonomy system are Vocabularies and Terms. You can think of a Vocabulary as a container of related Terms, and these Terms can be associated with objects, such as posts, users, or comments. As an example, Habari creates the Tags Vocabulary when you install or upgrade to Release 0.7 or newer. If you create a post and tag it with the tag awesome, Habari checks to see if there is a Term labelled awesome in the Tags Vocabulary, creates one if there isn't, and then associates that Term with your new post.

Terms can be stored in a hierarchy. This means it's possible to say that, for example, a Term is the sibling, parent, or child of another Term in the Vocabulary.

Possible Uses

We've thought of some possible uses for the taxonomy system, but we hope that plugin developers will come up with the most interesting ones.

Categories 
and hierarchical categories for one. This is implemented by the Simple Categories plugin.
Sub pages 
This is implemented by the SubPages plugin.
Menus 
Allow users to define menus, for example for navigation, and insert the menus into an Area defined by a theme.
Threaded comments 
Allow comment authors to reply to other comments, and display them in a threaded layout.

Code Examples

The following sections demonstrate how to use the taxonomy system, using examples modified from the Simple Categories plugin.

Working with Vocabularies

A plugin that works with the taxonomy system will commonly create a vocabulary when it is activated. Note that commonly-used vocabularies such as "categories" should be named generically since other plugins could use or build upon them.

public function action_plugin_activation( $file )
{
  if ( Plugins::id_from_file($file) == Plugins::id_from_file(__FILE__) ) {
    $simple_categories = Vocabulary::create( array(
      'name' => 'categories',
      'description' => 'A vocabulary for describing Categories',
      'features' => array( 'multiple', 'hierarchical' )
    ));
  }
}

Retrieving the vocabulary for later use is very simple.

$categories = Vocabulary::get('categories');

We can also rename or delete an existing vocabulary.

// Rename the vocabulary
Vocabulary::rename('categories', 'simple_categories');
 
// Delete the Vocabulary
$categories = Vocabulary::get('simple_categories');
$categories->delete();

Of course, this code is pretty silly, because you would just delete the vocabulary before you renamed it.

Features

You can limit the behaviour of the vocabulary by using features as in the example above. Possible features as of Habari 0.9 are:

  • hierarchical: The vocabulary's terms exist in a parent child hierarchy
  • multiple: More than one term in the vocabulary can be associated with an object
  • free: Terms within the vocabulary can have any value
  • unique: A term may be associated with exactly 0 or 1 object

Vocabularies have multiple and free by default. Developers can implement code that denies those features or add own features.

Working with Terms

Vocabularies only become interesting and useful when Terms are added to them, which is done with the add_term method.

// Retrieve the vocabulary
$categories = Vocabulary::get('categories');
 
// Add a term
$category_term = $categories->add_term('food');

Terms can be associated with objects using the set_object_terms method, which takes three parameters; the type of object with which you want to associate terms, the id of the particular object, and an array of Terms to associate with it. You have to pass the old terms if you only want to add a new one, otherwise the old ones will be overridden.

$categories = Vocabulary::get('categories');
 
// Get the latest post. In practice, you'd probably use a sensible post.
$post = Post::get();
 
// Associate some terms with the post
$terms = array('vegetables', 'animals');
$categories->set_object_terms('post', $post->id, $terms);

TODO: add relative (specify parent, before), retrieve, retrieve relative (ancestors etc), move, delete.

Personal tools