EPUB Widget Packaging and Integration
Editor's Draft 28 May 2014
This version:
http://www.idpf.org/epub/sc/pkg/packaging-20140528.html
Latest version:
http://www.idpf.org/epub/sc/pkg
Previous version:
N/A
Copyright © 2013-14 International Digital Publishing Forum™
All rights reserved. This work is protected under Title 17 of the United States Code. Reproduction and dissemination of this work with changes is prohibited except with the written permission of the International Digital Publishing Forum (IDPF).
EPUB is a registered trademark of the International Digital Publishing Forum.
Editors
Conboy, Garth (Google)
Manis, Will (Barnes & Noble)
Severdia, Ron (Metrodigi)
Lehmann, Darryl (Imagineeringart.com)
Vogel, Brad (Inkling)
Status of this Document
This document is an Draft Specification, produced by the IDPF EPUB 3 Working Group. This document may be updated, replaced, or rendered obsolete by other documents at any time.
Table of Contents
2.2.2 Reading System Conformance
2.5.3.2 The widget: Prefix Mapping
2.5.3.3 The widget:version property
2.5.3.4 The widget:storage-required property
2.5.3.5 The widget:network-access-required property
2.5.3.6 The widget:required-params property
2.7 Widget Size and Aspect Ratio
Appendix A. Example Packaging and Integration
A.1 Widget Container File Structure
Appendix B. Acknowledgements and Contributors
This section is informative
This specification, EPUB Widget Packaging and Integration, defines a method for the creation and inclusion of dynamic and interactive widgets in EPUB® Publications.
By packaging Widgets as EPUB Publications for distribution, all of the following benefits are realized:
Common EPUB packaging also makes it easier to integrate and use the Widgets in EPUB Publications, as the process is typically no more involved than copying the Widget resources and metadata into the Destination EPUB.
Refer to the EPUB Specifications for definitions of EPUB-specific terminology used in this document.
Destination EPUB (or Destination)
The EPUB Publication into which an EPUB Widget is integrated for use.
EPUB Widget (or Widget)
The dynamic XHTML component that is being distributed for use in other EPUB Publications.
Widget Base Document
The Widget Base Document is the XHTML Content Document that integrators reference to invoke a Widget.
Widget Container
An EPUB Container [OCF301] containing the Widget resources. The Widget Container is the distributable package for the Widget.
The following typographic conventions are used in this specification:
markup
All markup (elements, attributes, properties), code (JavaScript, pseudo-code), machine processable values (string, characters, media types) and file names are in red-orange monospace font.
markup
Links to markup and code definitions are underlined and in red-orange monospace font. Only the first instance in each section is linked.
http://www.idpf.org/
URIs are in navy blue monospace font.
hyperlink
Hyperlinks are underlined and in blue.
[reference]
Normative and informative references are enclosed in square brackets.
Term
Terms defined in the Terminology are in capital case.
Informative markup examples are in monospace font.
NOTE
Informative notes are preceded by a "Note" header.
The keywords must, must not, required, shall, shall not, should, should not, recommended, may, and optional in this document are to be interpreted as described in [RFC2119].
All sections of this specification are normative except where identified by the informative status label "This section is informative". The application of informative status to sections and appendices applies to all child content and subsections they may contain.
All examples in this specification are informative.
This section is informative
The first stage in the use of shared Widget components is the packaging of the Widget as a standalone EPUB Publication for general distribution.
This section outlines the requirements, from file structure to metadata to inclusion of a base document in the spine necessary to create a compliant EPUB Widget.
A conformant EPUB Widget must meet all of the following criteria:
› It must meet all requirements for EPUB Publications as defined in [Publications301].
› Its resources must be structured as defined in 2.3 File Structure.
› All Package Document id attribute values must conform to 2.4 Identifiers.
› It must meet all metadata requirements in 2.5 Metadata.
› It must include a reference to the Widget Base Content Document in the spine as defined in 2.6 Spine.
A conformant Reading System must meet all of the following criteria:
› It must process parameters as defined in 2.4.3.6 The widget:required-params property.
All resources of the EPUB Widget – those that need to be copied into a Destination EPUB to utilize the Widget – should be stored in a top-level directory in the Widget Container. For readability purposes, it is recommended that the name of the directory match the name of the Widget as expressed in the first dc:title element.
Resources that are expected to be shared between Widgets provided by the same Author must be stored in a top-level directory in the Widget Container. The name of this directory should be "shared".
The above naming conventions are recommended to facilitate the integration of Widgets in EPUB Publications in a regularized manner that requires no internal path fix-ups (see 4. Integration).
Refer to Appendix A.1 for an example of a Widget's structure.
To ensure the uniqueness of identifiers for integration in a Destination EPUB, all id attribute values in the Package Document [Publications301] must be universally unique identifiers (UUIDs) [RFC4122].
In order to identify that an EPUB Publication is a Widget, its Package Document metadata [Publications301] must include a dc:type element with the value "widget".
The following example shows how a Widget is defined in the Package Document metadata.
<package …>
<metadata xmlns:dc="http://purl.org/dc/elements/1.1/">
<dc:type>widget</dc:type>
…
</metadata>
</package>
Every EPUB Widget must include the required Dublin Core metadata properties defined in [Publications301].
In addition, every Widget must include at least one dc:creator, identifying the Author(s) of the Widget.
The dc:title element provides the name of the Widget. A Widget typically only includes one dc:title.
The value of the first instance of the dc:title and dc:creator elements in the Package Document metadata (in document order) should be suitable for use as a directory name (e.g., not contain any characters excluded for use in file names [OCF301]). Refer to 4.3 Resource Migration for more information on the use of these values to generate file paths.
This section is informative
This specification defines a set of properties that allow more precise information to be expressed about a Widget, each of which is outlined in the following subsections.
The properties defined in this section are expressed in the Package Document's meta element using the prefix "widget:", which maps to the base IRI "http://idpf.org/epub/vocab/widget/#".
The widget: prefix is reserved for use in Package Document metadata and does not need to be declared.
Definition The version number of the Widget. Allowed Value(s) must be a decimal-separated list of integers representing the major, minor and build numbers. Cardinality Exactly One Example <meta property="widget:version">1.0.127</meta> |
Definition Indicates whether the Widget requires access to local storage (e.g., localStorage, sessionStorage, app cache or indexedB). Allowed Value(s) "true" or "false". Default value is "false". Cardinality Zero or One Example <meta property="widget:storage-required">true</meta> |
Definition Indicates whether the Widget requires network access. Allowed Value(s) "true" or "false". Default value is "false". Cardinality Zero or One Example <meta property="widget:network-access-required">true</meta> |
Definition Defines the datatype of a parameter that has to be provided to invoke the Widget. When invoking the widget, the Reading System must provide the named parameter with appropriately typed data. Allowed Value(s) A string of the form: name=type where: name is any valid XML Name [XML] type is the name of a Primitive datatype [XSD-DATATYPES] (e.g., “string”, “gYearMonth”, “decimal”, “anyURI”) Cardinality Zero or More Example <meta property="widget:required-params">startDate=date</meta> |
Accessible nature of a Widget may be identified using the accessibility metadata properties [A11YProperties] from the [schema.org] CreativeWork type.
The vocabulary of recommended terms to use with these properties is maintained at the W3C Web Schemas Wiki [A11YProperties].
For more information on using these properties in the Package Document, refer to the Schema.org Metadata Integration Guide [SchemaGuide].
The Widget Base Document must be the only spine entry [Publications301] in the Package Document.
If a Widget Author wants to communicate a desired size or aspect ratio (e.g., to aid in scaling), the Destination EPUB may be constructed as a Fixed Layout EPUB Publication.
The fixed-layout viewport dimensions are then available for utilization by the inserting toolchain.
A Widget Container may include additional resources not specifically needed for the rendering of the Widget (e.g., a built-in editor for configuring the Widget).
As any such ancillary files are not Publication Resources (i.e., not intended for integration), they must not be included in the manifest [Publications301]. These resources do not need to be Core Media Types and are not subject to fallback requirements [Publications301].
The Widget may include custom metadata to identify such resources and provide any needed metadata using a custom prefix specified on the package element [Publications301]:
<meta property="xyz:editor">../editor/editor.htm</meta>
<meta property="xyz:prop1">Value1</meta>
<meta property="xyz:prop2">Value2</meta>
This metadata exists to allow integrators to find and use the embedded resources; it is not defined to enable Reading System access to the resources.
This specification does not define a method for defining more than one Widget in a Container. Each Container must include only a single EPUB widget.
Multiple Widget Containers can be zipped together to form a collection of widgets when it is necessary to bundle more than one Widget for distribution
This section is informative
In order to use a packaged EPUB Widget in an EPUB Publication, the Widget's resources and metadata have to be integrated into the Destination EPUB. The EPUB Widget can then be invoked from an [HTML5] iframe.
This section details the steps necessary to unpackage and integrate a Widget, including the preferred new file paths and the creation of a widget collection.
An EPUB Publication that incorporates a Widget must meet all of the following criteria:
› It should incorporate Widget resources as defined in 3.3 Resource Migration.
› It must include a widget collection conforming to the requirements in 3.4 Widget Collection.
In order to use an EPUB Widget in an EPUB Publication, the Widget resources first must be imported into the Destination EPUB. The process of integrating the resources involves the following steps:
Refer to Appendix A.3 for an example of resource restructuring.
In order to facilitate re-extraction and use of the Widget, the Destination EPUB must include a collection [Publications301] that identifies the Widget’s metadata and resources. The value of this collection element's role attribute must be "widget".
The widget collection must include all metadata from the Widget Package Document's metadata element, with the following exceptions: it must not include any primary expressions of identifiers (dc:identifier elements) or the last modified date (dcterms:modified property). All id attributes present in the EPUB Widget metadata must be retained.
All of the Widget resources imported into the EPUB Publication must be listed in a child manifest collection [MANIFEST].
The widget collection must include exactly one child link element. This link references the Widget Base Document. A link to the Widget Base Document is also required in the collection's manifest.
Refer to Appendix A.4 for an example of the widget collection.
NOTE
When extracting a Widget, the the Widget Base Document becomes the sole spine entry in the new Widget Container. A new EPUB Navigation Document also has to be generated with a single toc nav [ContentDocs301] entry pointing to the Widget Base Document.
This appendix is informative
The following subsections show the structure and metadata for an example gallery Widget, and the transformed structure and collection that results after integration.
The gallery Widget resources are structured as follows, with all core resources in the /Gallery directory and all shared components in the /shared directory:
/META-INF
/META-INF/container.xml
/mimetype
/Gallery
/Gallery/content.opf
/Gallery/nav.xhtml
/Gallery/gallery.html
/Gallery/css
/Gallery/css/common.sample.css
/Gallery/css/gallery.css
/Gallery/images
/Gallery/images/image-1.png
/Gallery/images/image-2.png
/Gallery/images/image-3.png
/Gallery/images/image-4.png
/Gallery/images/image-5.png
/Gallery/images/image-6.png
/Gallery/js
/Gallery/js/common.js
/Gallery/js/gallery.js
/Gallery/js/mootools-drag-touch.js
/shared/js/external
/shared/js/external/captionator-min.js
/shared/js/external/mootools-core-1.4.5-full-nocompat-yc.js
/shared/js/external/mootools-more-1.4.0.1-yc.js
The Package Document metadata for the gallery Widget includes all of the following properties (non-essential metadata, such as the identifier, has been omitted):
<package …>
<metadata>
<dc:type>widget</dc:type>
<dc:title>Gallery</dc:title>
<dc:creator>WidgetInc</dc:creator>
<dc:language>en</dc:language>
…
<meta property="widget:version">1.0</meta>
<meta property="widget:scripted">true</meta>
<meta property="widget:local-storage-required">true</meta>
<meta property="widget:network-access-required">true</meta>
<meta property="widget:params-required">true</meta>
<meta property="widget:viewport">width=1200, height=900</meta>
<meta property="schema:accessibilityFeature">alternativeText</meta>
<meta property="schema:accessibilityFeature">longDescription</meta>
<meta property="schema:accessibilityAPI">ARIA</meta>
<meta property="schema:accessibilityControl">fullKeyboardControl</meta>
<meta property="schema:accessibilityControl">fullMouseControl</meta>
<meta property="schema:accessibilityControl">fullTouchControl</meta>
</metadata>
…
</package>
The resources from the source Widget Container are stored under the /components/WidgetsInc/ directory in the Destination EPUB, as follows:
/components/WidgetInc/Gallery/gallery.html
/components/WidgetInc/Gallery/css
/components/WidgetInc/Gallery/css/common.sample.css
/components/WidgetInc/Gallery/css/gallery.css
/components/WidgetInc/Gallery/images
/components/WidgetInc/Gallery/images/image-1.png
/components/WidgetInc/Gallery/images/image-2.png
/components/WidgetInc/Gallery/images/image-3.png
/components/WidgetInc/Gallery/images/image-4.png
/components/WidgetInc/Gallery/images/image-5.png
/components/WidgetInc/Gallery/images/image-6.png
/components/WidgetInc/Gallery/js
/components/WidgetInc/Gallery/js/common.js
/components/WidgetInc/Gallery/js/gallery.js
/components/WidgetInc/Gallery/js/mootools-drag-touch.js
/components/WidgetInc/shared/js/external
/components/WidgetInc/shared/js/external/captionator-min.js
/components/WidgetInc/shared/js/external/mootools-core-1.4.5-full-nocompat-yc.js
/components/WidgetInc/shared/js/external/mootools-more-1.4.0.1-yc.js
The following example shows the widget collection that would be created when integrating the Widget into the Destination EPUB (not all metadata and resource links are reproduced).
<collection
role="widget">
<metadata>
<dc:type>widget</dc:type>
<dc:title>Gallery</dc:title>
<dc:creator>WidgetInc</dc:creator>
<dc:language>en</dc:language>
<meta property="widget:version">1.0</meta>
…
</metadata>
<collection
role="manifest">
<link href="../components/WidgetInc/Gallery/gallery.html"/>
<link href="../components/WidgetInc/Gallery/css/
common.sample.css"/>
<link href="../components/WidgetInc/Gallery/css/
gallery.css"/>
…
<link href="../components/WidgetInc/shared/js/external/
captionator-min.js"/>
…
</collection>
<link href="../components/WidgetInc/Gallery/gallery.html"/>
</collection>
This appendix is informative
Active members of the working group included:
IDPF Members
Invited Experts/Observers
[A11YProperties] Schema.org Accessibility Metadata Properties.
[ContentDocs301] EPUB Content Documents 3.0.1
[HTML5] HTML5: A vocabulary and associated APIs for HTML and XHTML.
[MANIFEST] EPUB Manifest Role.
[OCF301] Open Container Format 3.0.1.
[Publications301] EPUB Publications 3.0.1.
[RFC2119] Key words for use in RFCs to Indicate Requirement Levels (RFC 2119) . March 1997.
[RFC4122] A Universally Unique IDentifier (UUID) URN Namespace (RFC 4122). P. Leach, et al. July 2005.
[schema.org] schema.org.
[XSD-DATATYPES] XML Schema Part 2: Datatypes Second Edition . Paul V. Biron, et al. 28 October 2004.
[XML] Extensible Markup Language (XML) 1.0 (Fifth Edition). T. Bray, et al. 26 November 2008.
[SchemaGuide] Schema.org Metadata Integration Guide for EPUB 3.