Skip to content

Latest commit

 

History

History
269 lines (212 loc) · 8.28 KB

presentation.md

File metadata and controls

269 lines (212 loc) · 8.28 KB
Raw

Presentation Hints

The Presentation Hints extension defines a number of hints for User Agents about the way content should be presented to the user.

1. Presentation Hints in metadata

In order to provide publication-wide Presentation Hints, this extension introduces a new element in the metadata object of the Readium Web Publication Manifest:

Key Semantics Type
presentation Publication-wide presentation hints. Object

The following elements may be included in presentation:

2. Presentation Hints as Link Properties

In addition to publication-wide hints, this extension defines a number of Link Properties to provide resource-level hints in readingOrder or resources.

The following elements may be included in properties:

3. Properties

clipped

The clipped property is meant to adapt visual resources to any given viewport ratio. The clipped areas must not contain information which are mandatory for the comprehension of the resource.

Key Semantics Type Values Default
clipped Specifies whether or not the parts of a linked resource that flow out of the viewport are clipped. Boolean true or false false

In this example, resources are handled in a discontinuous way and each resource is scaled to fit the viewport height and clipped to fit different viewport widths. It behaves like turbomedia.

"metadata": {
  "readingProgression": "ttb",
  "presentation": {
    "continuous": false,
    "fit": "height",
    "clipped": true

  }
}

In this example, a specific resource is scaled to fit the viewport width and clipped to fit different viewport heights.

"readingOrder": [
  {
    "href": "image1.webp",
    "type": "image/webp",
    "properties": {
      "fit": "width",
      "clipped": true
    }
  }
]

continuous

Key Semantics Type Values Default
continuous Indicates if consecutive linked resources from the readingOrder should be handled in a continuous or discontinuous way. Boolean true or false true

In this example, the user will not experience discontinuities between the different resources

"metadata": {
  "presentation": {
    "continuous": true
  }
}

fit

Key Semantics Type Values Default
fit Specifies constraints for the presentation of a linked resource within the viewport. String contain, cover, width or height contain
Value Definition
contain The content is centered and scaled to fit both dimensions into the viewport.
cover The content is centered and scaled to fill the viewport.
width The content is centered and scaled to fit the viewport width.
height The content is centered and scaled to fit the viewport height.

In this example, resources are handled in a continuous way, the content is scrollable on the vertical axis and each resource fits the viewport width. It behaves like a webtoon.

"metadata": {
  "readingProgression": "ttb",
  "presentation": {
    "continuous": true,
    "overflow": "scrolled",
    "fit": "width"
  }
}

In this example, a specific resource is scaled to fit the viewport.

"readingOrder": [
  {
    "href": "image1.webp",
    "type": "image/webp",
    "properties": {
      "fit": "contain"
    }
  }
]

orientation

Key Semantics Type Values Default
orientation Suggested orientation for the device when displaying the linked resource. String landscape, portrait or auto auto

The orientation property is mostly relevant for resources with fixed dimensions (images, videos), where the orientation has an actual impact on how the resource is displayed.

In this example, each resource should be displayed in portrait mode.

"metadata": {
  "presentation": {
    "orientation": "portrait"
  }
}

In this example, a specific resource should be displayed in landscape mode.

"readingOrder": [
  {
    "href": "page1.html", 
    "type": "text/html",
    "properties": {
      "orientation": "landscape"
    }
  }
]

overflow

Key Semantics Type Values Default
overflow Indicates if the overflow of linked resources from the readingOrder or resources should be handled using dynamic pagination or scrolling. String paginated, scrolled or auto auto
Value Definition
paginated Content overflow should be handled using dynamic pagination.
scrolled Content overflow should be handled using scrolling.
auto The User Agent can decide how overflow should be handled.

Here is an example of a paginated mode requested by the author

"metadata": {
  "readingProgression": "ltr",
  "presentation": {
    "continuous": true,
    "overflow": "paginated"
  }
}

page

The page property is meant to provide a hint to Use Agents that rely on synthetic spreads to display more than a single resource at once.

Key Semantics Type Values Default
page Indicates how the linked resource should be displayed in a reading environment that displays synthetic spreads. String left, right or center None

In this example, the first page should be displayed of the left of a synthetic spread, the second page on the right.

"readingOrder": [
  {
    "href": "page1.jpg", 
    "type": "image/jpeg",
    "properties": {
      "page": "left"
    }
  },
  {
    "href": "page2.jpg", 
    "type": "image/jpeg",
    "properties": {
      "page": "right"
    }
  }
]

spread

Key Semantics Type Values Default
spread Indicates the condition to be met for the linked resource to be rendered within a synthetic spread. String landscape, both, none or auto auto
Value Definition
landscape The resource should be displayed in a spread only if the device is in landscape mode.
both The resource should be displayed in a spread whatever the device orientation is.
none The resource should never be displayed in a spread.
auto The resource is left to the User Agent.

In this example, content should be displayed in a spread only if the device is in landscape mode.

"metadata": {
  "presentation": {
    "spread": "landscape",
    "fit": "contain"
  }
}

In this example, content of these two pages should be displayed in a spread, one on the left, the other on the right, whatever the device orientation is.

"readingOrder": [
  {
    "href": "page1.jpg", 
    "type": "image/jpeg",
    "properties": {
      "spread": "both",
      "page": "left"
    }
  },
  {
    "href": "page2.jpg", 
    "type": "image/jpeg",
    "properties": {
      "spread": "both",
      "page": "right"
    }
  }
]

Appendix A - JSON Schema

The following JSON Schemas for this module are available under version control:

For the purpose of validating a Readium Web Publication Manifest, use the following JSON Schema resources: