Last updated April 11, 2012. Created by Matthew Davidson on February 1, 2010.
Edited by shamio. Log in to edit this page.

Overview

There are a great many modules for migration, deployment, backup, import, and aggregation, and every one of them implements their own mechanisms for discovering what fields a Drupal entity has, what type of fields they are, and what you can do with them. Field Tool is designed to solve this unnecessary duplication by… uh, creating another set of these mechanisms.

The API Field Tool provides is designed to be as simple and generic as possible, so virtually any module can drop it into place. It does no field value validation, so it is recommended that you do something like loading the updated entity into it's edit form and run drupal_execute() on the form, using form_get_errors() to see if the update was successful. The included Fieldtool Execute module provides an example implementation of such functionality.

Quick Start Guide

Discovering what fields are available for a particular node type:

<?php
$filters
= array('types' => array('story'));
$fields = fieldtool_fields('node', $filters);
?>

Getting and setting a node field value:

<?php
$node
= node_load(123);
$filters = array('types' => array($node->type));
$fields = fieldtool_fields('node', $filters);
$value = fieldtool_get($fields['title'], $node); // In this case returns a string
fieldtool_set($fields['title'], $node, 'New Title for This Node'); // Values given to fieldtool_set() should be of the same type as returned by fieldtool_get().
?>

Using the fieldtool_flat() convenience function, which sorts fields by hierarchy and weight, and the fieldtool_execute_submit() function from the included Fieldtool Execute module:

<?php
$node
= node_load(123);
$fields = fieldtool_flat('node', 'story');
$value = fieldtool_export($fields['title'], $node);
fieldtool_import($fields['title'], $node, 'A story called: '. $value);
fieldtool_execute_submit('node', 'update', $node);
?>

As the names suggest, fieldtool_export() and fieldtool_import() do a similar job to fieldtool_get() and fieltool_set(), but they are designed to be more forgiving, with a view to being used primarily for importing from and exporting to external systems that know nothing about Drupal. So fieldtool_export() will wherever possible try to produce a scalar value, and fieldtool_import() will try to fit an imported value (usually assumed to be something that can be treated as a scalar) as best it can into it's destination field. For instance, with taxonomy terms it will, when given a numeric value, try to find a term with that id in the vocabularies that apply to the current content type. When given a non-numeric string, it will try to find the corresponding term by first trying taxonomy_get_term_by_name(), then if nothing's found taxonomy_get_synonym_root(), again limiting to appropriate vocabularies for that node type.

fieldtool_execute_submit() saves the node, but does so by programmatically submitting the node form, thus guaranteeing that all form/field validation functions are called, and no values are saved that would not be accepted if created manually. At the time of writing fieldtool_execute_submit() only works with node entities, not users, etc.

Looking for support? Visit the Drupal.org forums, or join #drupal-support in IRC.