EPUB Widget Packaging and Integration

Draft Specification 28 May 2014

This version:

http://www.idpf.org/epub/widgets/epub-widgets20140528.html

Latest version:

http://www.idpf.org/epub/widgets

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)

Garrish, Matt (Invited Expert)

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

1. Overview

1.1 Purpose and Scope

1.2 Terminology

1.3 Typographic Conventions

1.4 Conformance Statements

2. Packaging

2.1 Introduction

2.2 Conformance

2.2.1 Content Conformance

2.2.2 Reading System Conformance

2.3 File Structure

2.4 Identifiers

2.5 Metadata

2.5.1 Identification

2.5.2 Dublin Core

2.5.3 Widget Properties

2.5.3.1 Introduction

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.5.4 Accessibility

2.6 Spine

2.7 Widget Size and Aspect Ratio

2.8 Ancillary Resources

2.9 Multi-Widget Distribution

3. Integration

3.1 Introduction

3.2 Conformance

3.3 Resource Migration

3.4 Widget Collection

Appendix A. Example Packaging and Integration

A.1 Widget Container File Structure

A.2 Widget Container Metadata

A.3 Integrated Resources

A.4 Integrated Collection

Appendix B. Acknowledgements and Contributors

References

Normative References

Informative References

1. Overview

1.1 Purpose and Scope

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.

1.2 Terminology

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.

1.3 Typographic Conventions

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.

1.4 Conformance Statements

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.

2. Packaging

2.1 Introduction

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.

2.2 Conformance

2.2.1 Content Conformance

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.

2.2.2 Reading System Conformance

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.

2.3 File Structure

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.

2.4 Identifiers

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].

2.5 Metadata

2.5.1 Identification

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>

2.5.2 Dublin Core

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.

2.5.3 Widget Properties

2.5.3.1 Introduction

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.

2.5.3.2 The widget: Prefix Mapping

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.

2.5.3.3 The widget:version property

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>

2.5.3.4 The widget:storage-required property

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>

2.5.3.5 The widget:network-access-required property

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>

2.5.3.6 The widget:required-params property

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>

2.5.4 Accessibility

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].

2.6 Spine

The Widget Base Document must be the only spine entry [Publications301] in the Package Document.

2.7 Widget Size and Aspect Ratio

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.

2.8 Ancillary Resources

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.

2.9 Multi-Widget Distribution

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

3. Integration

3.1 Introduction

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.

3.2 Conformance

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.

3.3 Resource Migration

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:

  1. All Widget resources, except the EPUB Navigation Document, must be copied into the Destination EPUB, and should be placed two levels deeper under a /components/<WidgetAuthor>/ directory at the root of the OCF Container. The value of the dc:creator metadata property should be used for <WidgetAuthor>.
  2. The manifest item elements [Publications301] for all resources, except the EPUB Navigation Document, must be copied into the manifest of the Destination EPUB, adjusting the href attribute values to the new paths defined in step #1.
  3. The Widget Base Document must be referenced from at least one [HTML5] iframe element.
  4. If the Widget includes obfuscated fonts [OCF301], the fonts must be de-obfuscated and then re-obfuscated using the Destination EPUB’s Unique Identifier [Publications301]. The Destination EPUB's encryption.xml file must be updated to include entries for the obfuscated fonts (see 4.4 Specifying Obfuscated Resources [OCF301]).

Refer to Appendix A.3 for an example of resource restructuring.

3.4 Widget Collection

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.


Appendix A. Example Packaging and Integration

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.

A.1 Widget Container File Structure

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

A.2 Widget Container Metadata

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>

A.3 Integrated Resources

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

A.4 Integrated Collection

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>

Appendix B. Acknowledgements and Contributors

This appendix is informative

Active members of the working group included:

IDPF Members

Invited Experts/Observers

References

Normative References

[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.

Informative References

[SchemaGuide] Schema.org Metadata Integration Guide for EPUB 3.