Representative Files for Records

Added in version 2.2.

Traditionally in Omeka, only Files and Items could easily be represented by graphics like thumbnails. Files can be displayed with file_markup or as thumbnails with file_image, and Items could use files_for_item to show all their files, or item_image to show the thumbnail of their first attached File.

Omeka 2.2 allows records other than Items to show thumbnails and other functionality that depends on File records by choosing a “representative” file. Omeka uses this functionality in the views for some records like Collections and Files, and also in the search results page.

Themes and plugins can use a new helper function to display thumbnails for records with representative files, and plugins can also select and expose representatives for their own records.

Showing thumbnails for records

Instead of the existing functions which are different for every type of record that can have a thumbnail, the new representative file system has just one helper function: record_image. record_image works just like file_image or item_image, but it will work for any type of record that has a representative file.

So, a theme can use this same function across the views for any number of record types, and can even use it on views where multiple different record types may appear.

To directly use the existing functions that work on Files, you can also call the Omeka_Record_AbstractRecord::getFile method on the record, which will return the File object for the representative file. You can pass that File to helpers like file_markup.

Using representative files in plugin records

Plugins can also add representative file support to their own records. These records will then work with record_image, so the plugin’s views can use that function to show thumbnails. Thumbnails will also show when those records appear in search results and any other places already using record_image.

To have a representative files for its instances, a Record subclass must override Omeka_Record_AbstractRecord::getFile. getFile takes no arguments, and the record simply has to return a File object from it. Records can use any strategy they want to select a representative file.

For example, Omeka’s own records use a variety of strategies:

  • Files return $this, since they “represent” themselves

  • Items return their first attached File

  • Collections select an item in the collection, preferring featured items, and return that item’s first File

  • Exhibits return the attached File that appears earliest in the exhibit