EPUB Scriptable Components
Packaging and Integration 1.0

Draft Specification 23 July 2015

This version:

http://www.idpf.org/epub/sc/pkg/packaging-20150723.html

Latest version:

http://www.idpf.org/epub/sc/pkg

Previous version:

http://www.idpf.org/epub/sc/pkg/packaging-20150706.html

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

Garth Conboy, Google

Will Manis, Invited Expert

Ron Severdia, Metrodigi

Darryl Lehmann, Imagineeringart.com

Brad Vogel, 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 Relationship to Other Specifications

1.2.1 Relationship to Distributable Objects

1.3 Terminology

1.4 Typographic Conventions

1.5 Conformance Statements

2. Conformance

2.1 Content Conformance

2.2 Reading System Conformance

3. Packaging and Integration

3.1 Distributable Objects

3.2 Packaged Components

3.2.4.1 Identification

3.2.4.2 Dublin Core

3.2.4.3 Scriptable Component Properties

3.2.4.3.1 Introduction

3.2.4.3.2 The epubsc: Prefix Mapping

3.2.4.3.3 The epubsc:version property

3.2.4.3.4 The epubsc:storage-required property

3.2.4.3.5 The epubsc:network-access-required property

3.2.4.3.6 The epubsc:required-params property

3.2.5 Spine

3.2.6 Component Size and Aspect Ratio

3.2.7 Ancillary Resources

3.3 Embedding Components

3.3.1 Translating States

3.3.2 Resource Migration

3.3.3 Embedded Component

3.4 Extracting Components

Appendix A. Example Packaging and Integration

A.1 Packaged Component

A.1.1 Container File Structure

A.1.2 Component Metadata

A.2 Embedded Component

A.2.1 Integrated Resources

A.2.2 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 Scriptable Components Packaging and Integration, defines a method for the creation and inclusion of dynamic and interactive components in EPUB® Publications.

By packaging Scriptable Components as EPUB Publications for distribution, all of the following benefits are realized:

No new XML vocabularies are required.
The epubcheck validation tool can be used to ensure validity of the Scriptable Components, and that all necessary resources are present.
The Package Document can be used to store Scriptable Component metadata.
Fixed-layout metadata can be used to communicate the desired aspect ratio.
Standalone debugging of Scriptable Components is possible, as the Scriptable Components can be ingested into any Reading System with scripting support (a component is simply a “page” with spine-level scripting).

Common EPUB packaging also makes it easier to integrate and use Scriptable Components in EPUB Publications, as the process is typically no more involved than copying the resources and metadata into the Destination EPUB.

1.2 Relationship to Other Specifications

This section is informative

1.2.1 Relationship to Distributable Objects

This specification subsets the framework for identifying, packaging and integrating objects defined in the EPUB Distributable Objects 1.0 specification.

1.3 Terminology

Refer to the EPUB Specifications for definitions of EPUB-specific terminology used in this document.

Refer to [DistributableObjects] for definitions of Distributable Object-specific terminology used in this document.

Base Document

The Base Document is the Scripted Content Document integrators reference to invoke a Scriptable Component, and that conforms to the content requirements defined in [ScriptableComponents].

Destination EPUB (or Destination)

The EPUB Publication into which an Scriptable Component is integrated for use.

Embedded Component

The collection element definition of the Scriptable Component created when a Packaged Component is integrated into a Destination EPUB. An Embedded Component is an Embedded Object [DistributableObjects] that meets the additional requirements defined in 3.3 Embedding Components.

Packaged Component

The Packaged Component is the distributable package for the Scriptable Component. A Packaged Component is a Packaged Object [DistributableObjects] that meets the additional requirement defined in 3.2 Packaged Components.

Scriptable Component

A scripted Distributable Object that is distributed for use in other EPUB Publications. A Scriptable Component conforms to all content requirements in this specification and in [ScriptableComponents].

1.4 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.5 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. Conformance

2.1 Content Conformance

A conformant Scriptable Component must meet all of the following criteria:

› It must meet the requirements for a Packaged Object [DistributableObjects] with the following modifications:

› Its Base Document must be a valid XHTML Content Document ‒ content fragments are not permitted.

› Its resources must be structured as defined in 3.2.2 File Structure.

› It must adhere to the metadata differences outlined in 3.2.4 Metadata.

› It must only reference the Base Document in the spine, as defined in 3.2.5 Spine.

An EPUB Publication that incorporates a Scriptable Component must meet all of the following criteria:

› It should incorporate Scriptable Component resources as defined in 3.3.2 Resource Migration.

› It must include a scriptable-component collection conforming to the requirements in 3.3.3 Scriptable Component Collection.

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 epubsc:required-params property.

3. Packaging and Integration

3.1 Distributable Objects

Unless specified otherwise in the following sections, Scriptable Components inherit the framework for identifying, packaging and integrating Distributable Objects defined in [DistributableObjects].

3.2 Packaged Components

3.2.1 Introduction

This section is informative

The first stage in the use of shared Scriptable Components is their packaging as a Packaged Object [DistributableObjects] for general distribution.

This section builds on the requirements for Packaged Object, outlining the additional requirements necessary to create a compliant Scriptable Component.

3.2.2 File Structure

All resources of the Scriptable Component – those that need to be copied into a Destination EPUB to utilize the Scriptable Component – should be stored in the directory /<EPUB>/components/<ComponentAuthor>/, where:

<EPUB> is the dedicated directory [OCF301] where EPUB Publication resources are located inside the OCF Container. This specification does not require a specific name for this directory, in keeping with [OCF301], but the name "EPUB" is suggested.
<ComponentAuthor> should be the value of the dc:creator metadata property.

Resources that are expected to be shared between Scriptable Components provided by the same Author should be stored in a subdirectory beneath <ComponentAuthor> with the name "shared".

The above naming conventions are recommended to facilitate the integration of Scriptable Components 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 Scriptable Component's structure.

3.2.3 Identifiers

It is strongly recommended that all id attribute values in the Package Document [Publications301] be universally unique, since Scriptable Components are designed to be integrated into other EPUB Publications. See also 2.4 Identifiers [DistributableObjects].

3.2.4 Metadata

3.2.4.1 Identification

In order to identify that an EPUB Rendition represents a Scriptable Component ‒ not a generic Distributable Object as defined in 2.2.2.1 Package Document Structure [DistributableObjects] ‒ this specification defines the dc:type identifier "scriptable-component". This identifier must be specified.

The following example shows how a Scriptable Component is defined in the Package Document metadata.

<dc:type>scriptable-component</dc:type>

…

</metadata>

</package>

NOTE

The identifier "distributable-object" is not used with Scriptable Components.

3.2.4.2 Dublin Core

This specification adds the following metadata requirement to the ones outlined in 2.2.3 Metadata [DistributableObjects]:

Every Scriptable Component must include at least one dc:creator, identifying the Author(s) of the Scriptable Component.
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.

3.2.4.3 Scriptable Component Properties

3.2.4.3.1 Introduction

This section is informative

The following subsections define properties that Authors can use to specify information specific to Scriptable Components.

Only the epubsc:version property has to be specified for all Scriptable Components. The other properties are specified only when they apply.

3.2.4.3.2 The epubsc: Prefix Mapping

The properties defined in this section are expressed in the Package Document's meta element using the prefix "epubsc:", which maps to the base IRI "http://idpf.org/epub/vocab/sc/#".

The epubsc: prefix is reserved for use in Package Document metadata and does not need to be declared.

3.2.4.3.3 The epubsc:version property

Definition

The version number of the Scriptable Component.

Allowed Value(s)

must be a decimal-separated list of integers representing the major, minor and build numbers.

Cardinality

Exactly One

Example

3.2.4.3.4 The epubsc:storage-required property

Definition

Indicates whether the Scriptable Component requires access to local storage (e.g., localStorage, sessionStorage, app cache or indexedDB).

Allowed Value(s)

"true" or "false". Default value is "false".

Cardinality

Zero or One

Example

3.2.4.3.5 The epubsc:network-access-required property

Definition

Indicates whether the Scriptable Component requires network access.

Allowed Value(s)

"true" or "false". Default value is "false".

Cardinality

Zero or One

Example

3.2.4.3.6 The epubsc:required-params property

Definition

Defines the datatype of a parameter that has to be provided to invoke the Scriptable Component.

When invoking the Scriptable Component, 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

3.2.5 Spine

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

3.2.6 Component Size and Aspect Ratio

If an Author wants to communicate a desired size or aspect ratio (e.g., to aid in scaling), the Packaged Component may be constructed as a Fixed Layout EPUB Publication.

The fixed-layout viewport dimensions are then available for utilization by the inserting toolchain.

3.2.7 Ancillary Resources

A Packaged Component may include additional resources not required for the rendering of the Scriptable Component (e.g., a built-in editor for configuring the Scriptable Component).

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 Scriptable Component may include custom metadata to identify such resources and provide any needed metadata using a custom prefix specified on the package element [Publications301]:

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.

3.3 Embedding Components

3.3.1 Translating States

In order to use a Scriptable Component in an EPUB Publication, the resources and metadata in the distributable Packaged Component first have to be integrated into the Destination EPUB. The Scriptable Component can then be invoked from an [HTML5] iframe.

This specification leverages the model for integrating Packaged Objects into a Destination EPUB defined in 3.3 Packaged to Embedded of [DistributableObjects], adding only a few minor modifications detailed in the following subsections to handle the specific requirements of Scriptable Components.

3.3.2 Resource Migration

In order to use a Scriptable Component in an EPUB Publication, the Packaged Component's resources must be imported into the Destination EPUB.

The process of integrating the resources from a Packaged Object is defined in 3.3.3 Migrate Resources [DistributableObjects]. The process for Packaged Components only modifies these steps as follows:

The Base Document must be referenced from at least one [HTML5] iframe element.
If the Scriptable Component 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.3.3 Embedded Component

When migrating a Packaged Component to a Destination EPUB, the creation of an Embedded Component [DistributableObjects] is required.

The steps to produce an Embedded Object are defined in 3.3.2 The distributable-object Collection [DistributableObjects]. Production of an Embedded Component only modifies these requirements in the following ways:

The Embedded Component collection must have the role attribute identifier "scriptable-component".
The collection must not include the following metadata from the Packaged Component:

primary expressions of identifiers (dc:identifier elements), including any expressions that refine them;
the last modified date (dcterms:modified property).

NOTE

Identifiers and the last modified date are stripped as Scriptable Components are often modified for use after integration (e.g., skinned to a particular ebook). If subsequently re-extracted, the resulting Packaged Component will differ from the source and therefore a new identifier and modification date are necessary.

Refer to Appendix A.4 for an example of a scriptable-component collection.

3.4 Extracting Components

Depending on rights permissions, it might be possible to extract a Scriptable Component from one EPUB Publication and reuse it in another.

The [DistributableObjects] specification defines the steps necessary to extract the resources and recreate a Packaged Component from an embedded definition, after which the process of embedding the Scriptable Component defined in 3.3 Embedding Components can be followed.

Note that in the case of Scriptable Components, as identifiers and the last modified date are stripped when integrating the Packaged Component into a Destination EPUB, any process that re-extracts the Scriptable Component will have to create new values.

Appendix A. Example Packaging and Integration

This section is informative

The following subsections show the structure and metadata for an example gallery, and the transformed structure and collection that results after integration.

A.1 Packaged Component

The following subsections shows the structure and metadata of the gallery when it is packaged as a standalone EPUB Publication (i.e., prior to integration and use).

A.1.1 Container File Structure

The gallery resources are structured as follows when it exists as a Packaged Component, with all core resources in the /Gallery directory and all shared components in the /shared directory.

Note that the content.opf file is stored in the content root, as it is not copied into the Embedded Object, and putting it at the root minimizes the need to change paths when the content gets integrated (assuming the Destination EPUB's Package Document is similarly located). The EPUB Navigation Document (nav.xhtml) is similarly located outside the components directory as it is not copied.

/META-INF

/META-INF/container.xml

/mimetype

/EPUB/content.opf

/EPUB/nav.xhtml

/EPUB/components/DynamicInc/Gallery

/EPUB/components/DynamicInc/Gallery/gallery.xhtml

/EPUB/components/DynamicInc/Gallery/css

/EPUB/components/DynamicInc/Gallery/css/common.sample.css

/EPUB/components/DynamicInc/Gallery/css/gallery.css

/EPUB/components/DynamicInc/Gallery/images

/EPUB/components/DynamicInc/Gallery/images/image-1.png

/EPUB/components/DynamicInc/Gallery/images/image-2.png

/EPUB/components/DynamicInc/Gallery/images/image-3.png

/EPUB/components/DynamicInc/Gallery/images/image-4.png

/EPUB/components/DynamicInc/Gallery/images/image-5.png

/EPUB/components/DynamicInc/Gallery/images/image-6.png

/EPUB/components/DynamicInc/Gallery/js

/EPUB/components/DynamicInc/Gallery/js/common.js

/EPUB/components/DynamicInc/Gallery/js/gallery.js

/EPUB/components/DynamicInc/Gallery/js/mootools-drag-touch.js

/EPUB/components/DynamicInc/shared/js/external

/EPUB/components/DynamicInc/shared/js/external/captionator-min.js

/EPUB/components/DynamicInc/shared/js/external/mootools-core-1.4.5-full-nocompat-yc.js

/EPUB/components/DynamicInc/shared/js/external/mootools-more-1.4.0.1-yc.js

A.1.2 Component Metadata

The Package Document metadata for the gallery includes all of the following properties (non-essential metadata, such as the identifier, have been omitted):

<dc:type>scriptable-component</dc:type>

<dc:title>Gallery</dc:title>

<dc:creator>DynamicInc</dc:creator>

<dc:language>en</dc:language>

…

</metadata>

…

</package>

A.2 Embedded Component

The following subsections shows the resources and metadata after the gallery has been packaged as a standalone EPUB Publication.

A.2.1 Integrated Resources

All of the resources in the components directory (see A.1.1) can be copied directly into the Destination EPUB. Note the two files that are not in this directory do not move.

These resources are listed in the Destination EPUB's manifest (not all shown):

…
        <item id="04c312de-da60-462d-9df5-903b47851d80"
                href="components/DynamicInc/Gallery/gallery.xhtml"
                media-type="application/xhtml+xml"/>
        <item id="04c312de-da60-462d-9df5-903b47851d81"
                href="components/DynamicInc/Gallery/css/common.sample.css"
                media-type="text/css"/>

…

</manifest>

A.2.2 Integrated Collection

The following example shows the scriptable-component collection that would be created when integrating the gallery into a Destination EPUB (not all metadata and resource links are reproduced).

Note that both the package manifest and the collection manifest have to list all the resources.

<dc:type>scriptable-component</dc:type>

<dc:title>Gallery</dc:title>

<dc:creator>DynamicInc</dc:creator>

<dc:language>en</dc:language>

…
</metadata>

<collection role="manifest">
<link href="components/DynamicInc/Gallery/gallery.xhtml"/>
<link href="components/DynamicInc/Gallery/css/

common.sample.css"/>

gallery.css"/>

…

captionator-min.js"/>

…

</collection>

</collection>

Appendix B. Acknowledgements and Contributors

This section is informative

EPUB has been developed by the International Digital Publishing Forum in a cooperative effort, bringing together publishers, vendors, software developers, and experts in the relevant standards.

The EPUB Scriptable Components Packaging and Integration 1.0 specification was prepared by the International Digital Publishing Forum's EPUB Working Group, operating under under the leadership of: