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
echo
ing to the screen, or looping toecho
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.