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