Functions/item

< Functions(Redirected from Theme API/item)

Summary

The item() helper retrieves the data for a given field of a specific item, usually the current item on the page. As arguments passed to the function, it requires the name of the Element Set, you can optionally specify the particular Element Name that you're retrieving data for, and you can pass options to the function as well.

To use the item() helper function, you must get a specific item. You can either use the set_current_item helper to set the current item, or get a specific item and set it as a variable (like $item) to use inside the item helpers. For example, the Items Show page (example.com/items/show/21) already has the metadata for the specific item passed to the page (in that example, item 21), so you can use item() without any additional code. For use on the Items Browse page (example.com/items/), see loop_items(), or for using items on other pages, see set_items_for_loop().

Since

0.10

Usage

<?php item($elementSetName, $elementName, $options = array, $item = null); ?>

Arguments

string $elementSetName {{#if
| (optional)}}
The element set to use. Additionally, the item() helper accepts 'special values' here that do not correspond to an Element Set or Element. Those values are:
  • id
  • item type name
  • date added
  • date modified
  • collection name
  • featured
  • public
  • permalink
{{#if: | Default: {{{default}}}}}
string $elementName {{#if
null | (optional)}}
The name of the element to display.
{{#if: null | Default: null}}
array $options {{#if
array() | (optional)}}
Options that affect the output of the function. See the Options section below for details on valid options.
{{#if: array() | Default: array()}}
Item $item {{#if
null | (optional)}}
The Item object to work on. The default (null) is to use the current item.
{{#if: null | Default: null}}

Options

Each of the option names listed below is the array key. Some options also have different behavior based on their associated value.

'delimiter'
String
Return the entire set of metadata as a string, where each entry is separated by the string delimiter.
'index'
Integer
Return the metadata entry at the specific integer index, starting at 0.
'no_escape'
Boolean
If set to true, return the text without HTML-escaping.
'no_filter'
Boolean
Return the set of metadata without running any of the filters.
'snippet'
Integer
Trim the length of each piece of text to the given integer length.
'all'
Boolean
If set to true, this will retrieve an array containing all values for a single element rather than a specific value. If set to false, an array is still returned containing only a single value. If set to null, no array is returned.

Return Value

mixed
A string or an array suitable for echoing to the screen, or looping to echo each value

See Also

Examples

Special Values

The following will retrieve and display the ID for an item:

<?php echo item('ID'); ?>

Dublin Core Field

The following code will retrieve and print the Dublin Core Title from the current item:

<?php echo item('Dublin Core', 'Title'); ?>

Item Type Metadata Field

Similarly, following code will retrieve and print the Text field from the Item Type Metadata set for the current item:

<?php echo item('Item Type Metadata', 'Text'); ?>

Passing Options

The following examples pass various options to the item() helper.

Snippet

Here's how to retrieve and print the Dublin Core Description of a specific item, and trim the number of characters to approximately 150:

<?php echo item('Dublin Core', 'Description', array('snippet'=>150)); ?>

Displaying All Values

Omeka allows you to store multiple values for each item field, but by default, the item() helper will only return the first value for any field.

The simplest way to display all the values for a field is to use the 'delimiter' option.

<?php 
    echo item('Dublin Core', 'Creator', array('delimiter' => ', '));
?>

This will print all the Creator values, separated by commas. The helper includes the 'delimiter' text in between each of the different values automatically.

If you want to do something more complex, you'll need to get an array of the values. item() will return an array if you set the 'all' option to 'true', like so:

<?php 
    $creators = item('Dublin Core', 'Creator', array('all' => true)); 
?>

Note that there is no echo in the above example. You need to do a little more work to print out an array. To display each value in this array, one value per line, you can use a foreach block along with echo:

<?php 
    $creators = item('Dublin Core', 'Creator', array('all' => true));
    foreach ($creators as $creator) {
        echo "$creator<br />";
    }
?>

Specify an Item Object

If you want to display metadata for a particular object, you can specify that item by its ID using the get_item_by_id helper function, like so:

<?php 
  $creators = item('Dublin Core', 'Creator', array('all' => true), get_item_by_id(17)); 
?>

This will get an array of all the Dublin Core Creator texts for Item #17.