Home > Item

Overview

When manipulating resources (XHTML, images, audio...) in EPUB, EPUB::Publication::Package::Manifest::Item object will be used. And objects which EPUB::Book::Features#each_page_on_spine yields are also instances of this class.

Here's the tutorial of this class.

Getting Items

Getting the Item object you want is due to other classes, mainly EPUB module:

book = EPUB::Parser.parse('book.epub')
book.resouces                    # => all items including XHTMLs, CSSs, images, audios and so on
book.cover_image                 # => item representing cover image file
book.each_page_on_spine do |page|
  page                           # => item in spine(order of "page" the author determined, often XHTML file)
end
book.package.manifest.navs       # => navigation items(XHTML files including <nav> element)
book.package.manifest['item-id'] # => item referenced by the ID "item-id"

For the last two examples, knowledge for EPUB structure is required.

Using Items

Once you've got an Item, it provides informations about the item(file).

item.id                   # => the ID of the item
item.media_type           # => media type like application/xhtml+xml
item.href                 # => Addressable::URI object which represents the IRI of the item
item.properties           # => array of properties
item.fallback             # => see the next section for details
item.fallback_chain       # => ditto.
item.using_fallback_chain # => ditto.

And Item also provides some methods which help you handle the item.

For example, for XHTML:

item.read                # => content of the item
Nokogiri.HTML(item.read) #=> Nokogiri::HTML::Document object

For image:

uri = 'data:' + item.media_type + '; base64,' + Base64.encode64(item.read)
img = %Q!<img src="#{uri}" alt="#{item.id}">!

Fallback Chain

Some items have fallback attribute, which provides the item to be used when reading system(your app) cannot handle with given item for some reason(for example, media type not supported).

Of course, you can get it by calling fallback method:

item.fallback # => fallback `Item` or nil

Also you can use use_fallback_chain not to check if you can accept item or not for every item:

item.use_fallback_chain :supported => 'image/png' do |png|
  # do something with PNG image
end

If item's media type is, for instance, 'image/x-eps', the fallback is used. If the fallback item's media type is 'image/png', png variable means the item, if not, "fallback of fallback" will be checked. Finally you can use the item you want, or EPUB::MediaType::UnsupportedMediaType exception will be raised(if no item you can accept found). Therefore, you should rescue clause:

# :unsupported option can also be used
# fallback chain will be followed until EPUB's Core Media Types found or UnsupportedMediaType raised
begin
  item.use_fallback_chain :unsupported => 'application/pdf' do |page|
    # do something with item with core media type
  end
rescue EPUB::MediaType::UnsupportedMediaType => evar
  # error handling
end