Creating vocabularies and terms when installing a Drupal module

By default, in Drupal 6, if you try to use the taxonomy API functions at install time, nothing will happen. Simply by including the taxonomy module in your code, you can get access to the taxonomy API functions, enabling you to create vocabularies, terms or do any of the kind of taxonomy processing you might need when a module is initially installed.

Imagine you're writing a module that provides a 'juice' content type. Wouldn't it be nice to create a vocabulary to categorise the types of juice, and populate it with taxonomy terms in order to get the user going?

Here's an example of how to achieve this in your module's install function:

function juice_install() {
  module_load_include('module', 'taxonomy', 'taxonomy');
  $t = get_t();
 
  // Create the vocabulary programatically.
  $vocab = array(
    'name' => 'Juice type',
    'description' => $t('The type of juice, such as apple or orange.'),
    'help' => 0,
    'relations' => 0,
    'hierarchy' => 0,
    'multiple' => 0,
    'required' => 1,
    'tags' => 0,
    'module' => 'taxonomy',
    'weight' => 0,
    'nodes' => array('juice'),
  );
 
  taxonomy_save_vocabulary($vocab);
 
  // Get the vid of the vocabulary we just created.
  $vid = db_result(
    db_query(
      "SELECT vid FROM {vocabulary} WHERE name = '%s'",
      'Juice type'
    )
  );
 
  // Create the term programatically.
  $term = array(
    'name' => 'Orange',
    'vid' => $vid,
    'description' => $t('Orange juice is made from oranges. It is sweet and usually orange in colour.'),
  );
 
  taxonomy_save_term($term);
}

The key here is line 2. We're including not just an include file (which would be identified by the .inc extension), but an actual module file. Usually, you don't need to do this in Drupal, because every enabled module has its .module file included automatically, but we're more restricted here because during install, only a limited set of functionality is normally available. By manually including this module file, we can actually allow Drupal to use the taxonomy API functions.

Don't forget that's it's bad practice to use t() in an install file. If your module ends up in an installation profile, it will fail to install, so on line 3 above we've set up a variable to use as a function call, using the get_t() function, then we're calling $t(), which calls the appropriate function, instead of just t().

We then use a data structure to create a vocabulary. Since we need to know the vocabulary's vid, we need to query the database after we've saved the vocabulary, since the call to taxonomy_save_vocabulary doesn't seem to return any information such as its vid.

After creating the vocabulary, we create a taxonomy term to add to it. This is why we need the vid of the vocabulary; we don't need to create the term and then map it to a vocabulary; instead, we just tell Drupal which vocabulary to attach it to at the time when it's created.

The example is far from complete, of course. You need to write a corresponding uninstall function that will remove the vocabulary. There's no need to concern yourself with removing taxonomy terms, because if you remove the vocabulary, the terms will all go too. You could also do with some kind of checking to make sure that the vocabulary and its terms don't already exist, because you would otherwise be duplicating yourself if a user somehow reinstalled the module without uninstalling it first.

Comments

by kiam on 25 May, 2010 - 16:32

The shown code contains two errors. The arguments for module_load_include() are wrong (the first argument is the type of the file to include, such as inc); t() is available from the installation function.

by Chris on 25 May, 2010 - 17:34

Thanks for the comment. In the module_load_include() call, we're loading taxonomy.module, so the arguments as shown are correct. You're right in that you'd usually load a .inc here, but we're loading the .module. Secondly, although t() is indeed available in an installation function, it is considered bad practice to use it, because if your module is used in an installation profile, t() will not be available and the install will fail.

by kiam on 4 June, 2010 - 16:47

To load a module there is the function drupal_load(); module_load_include() is thought for include files (as the name suggests, and how the documentation reports).

by Chris on 4 June, 2010 - 17:25

Thanks for this. Your suggestion makes sense here, and drupal_load() looks like the way to go!

by Anonymous on 21 July, 2010 - 19:12

I have the following in the nodes part of the $vocab array:

'nodes' => array('page', 'story'),

However the page and story content types are not selected and in the main taxonomy page, under Type is just 0, 1

by Mike on 22 July, 2010 - 11:53

I've looked at the taxonomy_save_vocabulary() function and it seems the function uses the keys and not the values of the nodes array. So the following solves the problem:

'nodes' => array('page' => 'page', 'story' => 'story'),

by Achton on 7 October, 2010 - 19:21

taxonomy_save_vocabulary() alters the $vocab argument, so it will contain the vid after calling.

So you could just do this:
$vid = $vocab['vid'];

.. and save a SELECT :)

by Alejandro Garza on 4 November, 2010 - 22:35

A hierarchical taxonomy install example is the HILCC module over at http://drupal.org/project/hilcc

by Anonymous on 9 September, 2011 - 18:19

Nice article. thanks. be careful about putting this in a hook_install function without adding a test to see whether the vocab you are installing is already present, or creating a delete function when the module is uninstalled. Otherwise you'll end up with lots of different vocabs...all the same!

Cheltenham Web Design and Drupal Development | Tigerfish Interactive