CHAPTER 15 ■ WORKING WITH TAXONOMY

<?php

/**

* Display the taxonomy terms associated with a given node */

$nid = 2;

$node = node_load($nid);

$result = field_view_field('node', $node, 'field_tags', array('default')); print render($result);

In the foregoing code, I’m calling the field_view_field() function, passing the type of entity that contains the field (a node), the object containing the field (the node object that I’ve loaded), the name of the field (field_geographic_location), and the display mode (default).

Building Your Own Taxonomy Queries

If you need to generate a node listing of some sort, you might end up wishing that things were simpler; you might wish that Drupal kept taxonomy terms in the node table, so you could say the following:

SELECT * FROM node WHERE vocabulary = 1 and term = 'cheeseburger'

The cost of flexibility is a bit more work for the Drupal developer. Instead of making simple queries such as this, you must learn to query the taxonomy tables using JOINs.

Using taxonomy_select_nodes()

Before you start writing a query, consider whether you can get what you want using an existing function. For example, if you want titles of nodes tagged by term IDs 5 and 6, you can use taxonomy_ select_nodes():

$tids = array(5, 6);

$result = taxonomy_select_nodes($tids); $titles = array();

foreach($result as $nid) { $node = node_load($nid); $titles[] = $node->title;

}

Taxonomy Functions

The following sections explain functions that might be useful for your module.

Retrieving Information About Vocabularies

The built-in functions in the following sections retrieve information about vocabularies, as vocabulary data objects or as an array of such objects.

355

CHAPTER 15 ■ WORKING WITH TAXONOMY

taxonomy_vocabulary_load($vid)

This function retrieves a single vocabulary (the $vid parameter is the vocabulary ID) and returns a vocabulary object. It also caches vocabulary objects internally, so multiple calls for the same vocabulary aren’t expensive. This function is also a special load function from the point of view of Drupal’s menu system (see Chapter 4 for details). Since taxonomy vocabularies are entities, the taxonomy_ vocabulary_load function is just a wrapper for the entity_load function.

taxonomy_get_vocabularies()

The taxonomy_get_vocabularies($type) function retrieves an array of all vocabulary objects.

Adding, Modifying, and Deleting Vocabularies

The following functions create, modify, and delete vocabularies. They return a status code that’s one of the Drupal constants SAVED_UPDATED or SAVED_NEW.

taxonomy_vocabulary_save($vocabulary)

This function creates a new vocabulary or updates an existing one. The $vocabulary parameter is a vocabulary object containing the following keys:

•vid: The vocabulary ID

•name: The name of the vocabulary

•machine name: The internal Drupal name for this vocabulary

•description: The description of the vocabulary

•hierarchy: Set to 0 for no hierarchy, 1 for single hierarchy, and 2 for multiple hierarchy.

•module: The name of the module that’s responsible for this vocabulary; if this key is not passed, the value will default to taxonomy.

•weight: The weight of the vocabulary; it affects the placement of the node submission form in the Vocabularies fieldset.

•rdf_mapping: An array that defines how terms are mapped

The taxonomy _vocabulary_save($vocabulary) function returns SAVED_NEW or SAVED_UPDATED.

taxonomy_vocabulary_delete($vid)

The $vid parameter of this function is the ID of the vocabulary. Deleting a vocabulary deletes all its terms by calling taxonomy_del_term() for each term. The taxonomy_vocabulary_delete($vid) function returns SAVED_DELETED.

356

CHAPTER 15 ■ WORKING WITH TAXONOMY

Retrieving Information About Terms

The built-in functions in the following sections retrieve information about terms, typically as objects or as an array of objects.

taxonomy_load_term($tid)

This function retrieves a term (the $tid parameter is the term ID) and returns a term object. It caches term objects internally, so multiple calls for the same term aren’t expensive. The structure of the term object looks like this:

$term = taxonomy _term_load(3); var_dump($term);

object(stdClass)#65 (9) { ["tid"]=> string(1) "3" ["vid"]=> string(1) "3"

357

CHAPTER 15 ■ WORKING WITH TAXONOMY

}

}

taxonomy_get_term_by_name($name)

The taxonomy_get_term_by_name($name) function searches for terms matching a string (the $name parameter is a string). Whitespace is stripped from $name, and matches are case insensitive. This function returns an array of term objects.

Adding, Modifying, and Deleting Terms

The following functions create, modify, and delete terms. They return a status code that is one of the Drupal constants SAVED_UPDATED, SAVED_NEW, or SAVED_DELETED.

taxonomy_term_save($term)

This function creates a new term or updates an existing term. The $term is a term object:

•name: The name of the term

•description: The description of the term; this value is unused by Drupal’s default user interface, but might be used by your module or other third-party modules.

•vid: The ID of the vocabulary to which this term belongs

•weight: The weight of this term; it affects the order in which terms are shown in term selection fields.

•relations: An optional array of term IDs to which this term is related

•parent: Can be a string representing the term ID of the parent term, an array containing either strings representing the term IDs of the parent terms, or a subarray containing strings representing the term IDs of the parent terms.

Optional.

•vocabulary_machine_name: The machine name of the vocabulary associated with this term

•tid: The term ID; if this key isn’t passed, a new term will be created.

This function returns SAVED_NEW or SAVED_UPDATED.

358