Skip to content

Submission Request to IDPF: EPUB Widgets 1.0

Jump to bottom Edit New page
Ron Severdia edited this page Nov 8, 2013 · 1 revision

Metrodigi hereby submits to the IDPF the following specification for the foundation of a widget standard for the ePub format.

Table of Contents

Abstract

The ePUB Widgets Specification outlines approaches and structure for a widget framework, configurable parameters and usage in both Reading Systems and Authoring Systems.

ePub Widget Package

The primary need for a widget package is to share resources between widgets (e.g. having multiple widgets on a page can utilize the same shared resources).

Package Manifest

The ePub Widget package is a ZIP file containing metadata files and uses the following folder structure: 

 ROOT
 -- package.xml
 -- widgets
 ---- widget
 ------ config.xml
 ------ book
 ------ editor

The ePub Widget package must contain a package.xml file and widgets folder at the root level. Each widget subfolder contains a config.xml to define the widget configuration.

package.xml
The following is an example of defining a package manifest. 

 <?xml version="1.0" encoding="utf-8"?>
 	<widget-pack>
 		<shared scope="*" folder="common-shared"></shared>
 		<shared scope="editor" folder="editor-shared"></shared>
 		<shared scope="book" folder="book-shared"></shared>
 		<widgets>
 			<widget name="audio"/>
 			<widget name="video"/>
 		</widgets>
 	</widget-pack>
 </xml>

Above is an example package.xml, which defines two widgets: audio and video. The shared tag defines the shared resources between widgets and the scope attribute defines whether it's shared and available in the editor only (editor), book only (book) or in both (*).

Resources specific to either the book (Reading System) or editor (Authoring System) reside in their respective directories.

Widget Assets

For the purposes for defining resources for specific systems, the following definitions are used:

Authoring System: A tool by which ePub content is authored or edited Reading System: A tool by which ePub content is displayed

The widget configuration file (config.xml) defines all of the widget resource dependencies and resources.

config.xml 

 <?xml version="1.0" encoding="utf-8"?>
 <widget>
 <name>Audio Widget</name>
 <label>Audio</label>
 <description>Add audio to a book</description>
 <version>0.1</version>
 <id>2d86c4246f3c0eb516628bf324d6b9a3</id>
 <author url="http://www.metrodigi.com">Metrodigi</author>
 <license url="http://www.apache.org/licenses/LICENSE-2.0.html">Apache License, Version 2.0</license>
 <help url="http://widgets.chaucercloud.com/help">Get help for this widget at www.chaucercloud.com</help>
     <files>
         <filename resource="editor" mainView='true'>editor.html</filename>
         <filename resource="editor">editor.js</filename>
         <filename resource="editor">editor.css</filename>
         <filename resource="editor" type="icon">audio.gif</filename>
         <filename resource="editor" type="placeholder">audio.png</filename>
         <filename resource="book" init-script="true">audio.js</filename>
         <filename resource="book">audio.css</filename>
         <filename resource="book" type="shared">external/mootools-core-1.4.5-full-nocompat-yc.js</filename>
         <filename resource="book" type="shared">external/mootools-more-1.4.0.1.js</filename>
     </files>
     <params>
   	<param key="compatibility">
   	   	<access booktype="Reflowable">true</access>
   	   	<access booktype="FixedLayout">true</access>
   	</param>
   	<param key="editor">
   	   	<dimensions width=”600” height=”400”/>
   	</param>
   	<param key="custom-key">Custom Value</param>
     </params>
 </widget>

Above is sample config.xml of an ePub Widget containing the following attributes:

<name> Unique name of the widget
<label> Displayed name of the widget (visible to the user)
<description> Description of the widget
<version> Version of the widget
<id> Unique ID of the widget (MD5 hash, doesn’t change and must be unique)
<author> Author of the widget and url attribute specifies Author's web page
<license> License name for the widget and url attribute specifies Author's web page
<help> Help page for the widget and url attribute specifies (for Authoring System)
<files> Files required by the widget
<filename> Defines a dependent file entry:
resource attribute - Two accepted values:
editor specifies a resource used by an Authoring System
book specifies a resource used by or loaded in an ePub
type attribute - Three accepted values:
icon specifies an icon file used by an Authoring System (e.g. to show an icon list of widgets) placeholder specifies an image file used by Authoring System to show widget placeholder inside page (if needed)
shared specifies a resource shared by multiple widgets
main-view attribute - Only applicable to resource=editor and specifies an HTML file to display configuration options in Authoring System
init-script attribute - Only applicable to resource=book and specifies a JavaScript file as the main widget script loaded in book page
type attribute - A shared value which specifies external dependencies for the widget (e.g. shared styling/themes, or JavaScript libraries)

1. The node order is used as the load order for book pages
2. The file defined here should have a relative path from shared folder
<params> Define custom widget parameters:
  • Can contain multiple parameter nodes
  • key attribute defines key value for the parameter
  • Value of the key is placed in the content of parameter node. It can have direct value or a complex value tree.

Predefined parameters:
  • compatibility value defines compatibility based on book format or layout
  • key attribute: editor value defines optional configuration for Authoring System
  • dimensions specifies attributes width and height of view displaying configuration options in Authoring System

Additional Items for Consideration

The following widgets were released by Metrodigi at EDUPUB Boston (Oct. 29, 2013):

  • Audio
  • Video
  • Image gallery
  • Popup
  • Multiple-choice Quiz
  • Scrolling Sidebar
  • Text Resizer
These widgets were released under an open source license (MIT) and are in the IDPF code repository on GitHub. Also included are the following items:
  • A “playground” to test the widgets and preview code/configuration modifications
  • Working samples of all the widgets, including HTML layouts
  • Build scripts for creating widget packages

Suggested Action

We suggest that the IDPF start a Working Group whose goal is to produce a complete specification recommendation outlining the deployment and usage of widgets by refining this submission.

Contact and Additional Information

Ron Severdia, CTO
Metrodigi, Inc.
[email protected]

Submitted: October 29, 2013
Add a custom footer
Add a custom sidebar
Clone this wiki locally