EPUB Scriptable Components Packaging and Integration, defines a method for the creation and inclusion of dynamic and interactive components in EPUB® Publications.

Overview

Purpose and Scope

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:

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.

Relationship to Other Specifications

Relationship to Distributable Objects

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

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

Conformance

Content Conformance

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

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

Reading System Conformance

A conformant Reading System MUST meet all of the following criteria:

Packaging and Integration

Distributable Objects

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

Packaged Components

Introduction

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.

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 3.3 Embedding Components).

Refer to Appendix A.1 for an example of a Scriptable Component's structure.

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

Metadata

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 identifier "distributable-object" is not used with Scriptable Components.

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 3.3.2 Resource Migration for more information on the use of these values to generate file paths.
Scriptable Component Properties
Introduction

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.

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.

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
<meta property="epubsc:version">1.0.127</meta>
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
<meta property="epubsc:storage-required">true</meta>
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
<meta property="epubsc:network-access-required">true</meta>
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 [[!XMLSCHEMA-2]] (e.g., “string”, “gYearMonth”, “decimal”, “anyURI”)
Cardinality

Zero or More

Example
<meta property="epubsc:required-params">startDate=date</meta>

Spine

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

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.

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.

Embedding Components

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.

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:

  1. The Base Document MUST be referenced from at least one [[!HTML5]] iframe element.
  2. 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.2 for an example of resource restructuring.

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

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.2.2 for an example of a scriptable-component collection.

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.

Example Packaging and Integration

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

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

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

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):

<package …>
<metadata>
<dc:type>scriptable-component</dc:type>
<dc:title>Gallery</dc:title>
<dc:creator>DynamicInc</dc:creator>
<dc:language>en</dc:language>
…
<meta property="epubsc:version">1.0</meta>
<meta property="epubsc:storage-required">true</meta>
<meta property="epubsc:network-access-required">true</meta>
<meta property="epubsc:required-params">true</meta>
<meta property="rendition: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>

Embedded Component

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

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):

<manifest>
        …
        <item 
                href="components/DynamicInc/Gallery/gallery.xhtml"
                media-type="application/xhtml+xml"/>
        <item
                href="components/DynamicInc/Gallery/css/common.sample.css"
                media-type="text/css"/>
        <item
                href="components/DynamicInc/Gallery/css/gallery.css"
                media-type="text/css"/>
        …
</manifest>

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.

<collection role="scriptable-component">
        <metadata>
                <dc:type>scriptable-component</dc:type>
                <dc:title>Gallery</dc:title>
                <dc:creator>DynamicInc</dc:creator>
                <dc:language>en</dc:language>
                <meta property="epubsc:version">1.0.1</meta>
                …
        </metadata>
        <collection role="manifest">
                <link href="components/DynamicInc/Gallery/gallery.xhtml"/>
                <link href="components/DynamicInc/Gallery/css/common.sample.css"/>
                <link href="components/DynamicInc/Gallery/css/gallery.css"/>
                …
                <link href="components/DynamicInc/shared/js/external/captionator-min.js"/>
                …
        </collection>
        <link href="components/DynamicInc/Gallery/gallery.xhtml"/>
</collection>

Acknowledgements and Contributors

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:

Active members of the working group at the time of publication were:

IDPF Members

Invited Experts/Observers