This module is for module writers and has no UI of its own. Unless some other
module uses it, it won't add anything to your site. Only install this module if
another module requires it.
The field_extract module provides a couple of easy-to-use functions that make
extracting data from entity fields much easier - as a developer you don't have
to worry about languages and deltas, you just make the call.
It's worth noting that the functionality in this module overlaps with the Entity
Plus wrapper. The object-based wrapper is more elegant than this procedural
solution but it's heavier and slower, so you have a choice.
For clarity: this module does not load individual Field API fields for entities,
it accesses the contents of Field API fields that are already loaded into
entities. That's important because the $user object and taxonomy terms are often
loaded by Backdrop without their Field API fields. You may need to use the
field_attach_load() call to get the fields before using
field_extract_value().
Features
- Easy to use - just two functions to choose from
- Support for core fields and popular third party fields built-in
- Support for the Date module included (so important it gets its own bullet point)
- Easy to extend for other third party fields
- Easy to include support in new field modules
Important developer's note
This module makes it easier to extract values from fields, but to do this it
requires extraction settings in the field's field_info. This implementation
contains extraction support for most common fields (including the core fields)
but may not support some 3rd party modules.
Creating new extraction field_info is quite easy (see the includes directory)
or ask the 3rd party field module developer to include support in their next release.
Examples of use
Using the field_extract_value() function to fetch a single value:
// Extract the zeroeth (first) value from a simple value field,
// could be a string or a number
$value = field_extract_value('node', $node, 'field_just_a_value');
// Extract the "one-th" (second) value from a simple value field,
// could be a string or a number
$value = field_extract_value('node', $node, 'field_just_a_value', 1);
// Extract from a term reference field, this fetches the first value
// and extracts the actual 'tid' - see next example
$tid = field_extract_value('node', $node, 'field_term_ref', 0, array('key' => 'tid'));
// Extract from a term reference field, this fetches the whole term
// by default. If a field references an entity in some way
// the whole entity is returned
$term = field_extract_value('node', $node, 'field_term_ref');
// Extract from a date, this extracts the first value and provides a
// formatted date output, defaults to 'medium' format
$event_time = field_extract_value('node', $node, 'field_event_time');
// Extract from a date, this extracts the first value and provides a
// formatted date output, uses the specified format, by name.
$event_time = field_extract_value('node', $node, 'field_event_time', 0, array('format' => 'my_format'));
// Extract a different quantity from the field, other than the main value.
$format = field_extract_value('node', $node, 'body', 0, array('key' => 'format'));
// The formatter option causes the field data to be formatted for output using
// the specified formatter for that field without the field 'label'.
$output = field_extract_value('node', $node, 'body', 0, array('formatter' => 'default'));
Using the field_extract_values() function to get multiple values:
// Extract all the values from a simple value field, could be strings
// or numbers
$values = field_extract_values('node', $node, 'field_just_a_value');
// Extract the "one-th" (second) value from a simple value field, could be a
// string or a number. Same as field_extract_value('node', $node, 'field_just_a_value', 1)
$value = field_extract_values('node', $node, 'field_just_a_value', array('delta' => 1));
// Extract from a term reference field, this fetches all values as an array
$tids = field_extract_values('node', $node, 'field_term_ref', array('key' => 'tid'));
// Extract from a term reference field, this fetches all terms as an array
$terms = field_extract_values('node', $node, 'field_term_ref');
// The formatter option causes the field data to be formatted for output using
// the specified formatter for that field without the field 'label'.
$outputs = field_extract_values('node', $node, 'body', array('formatter' => 'default'));
Installation
- Install this module using the official Backdrop CMS instructions
Usage
- Usage instructions can be viewed and edited in the Wiki.
Issues
- Bugs and Feature requests should be reported in the Issue Queue.
Current Maintainers
- Laryn Kragt Bakker.
- Collaboration and co-maintainers welcome!
Credits
- Ported to Backdrop CMS by Laryn Kragt Bakker.
- Maintained for Drupal by adaddinsane
and garrettc. - Originally supported for Drupal by Catch Digital.
License
This project is GPL v2 software. See the LICENSE.txt file in this directory for
complete text.