|
| 1 | +# Getting started |
| 2 | + |
| 3 | +The Readium Swift toolkit enables you to develop reading apps for iOS and iPadOS. It provides built-in support for multiple publication formats such as EPUB, PDF, audiobooks, and comics. |
| 4 | + |
| 5 | +:warning: Readium offers only low-level tools. You are responsible for creating a user interface for reading and managing books, as well as a data layer to store the user's publications. The Test App is an example of such integration. |
| 6 | + |
| 7 | +## Design principles |
| 8 | + |
| 9 | +The toolkit has been designed following these core tenets: |
| 10 | + |
| 11 | +* **Modular**: It is divided into separate modules that can be used independently. |
| 12 | +* **Extensible**: Integrators should be able to support a custom DRM, publication format or inject their own stylesheets without modifying the toolkit itself. |
| 13 | +* **Opiniated**: We adhere to open standards but sometimes interpret them for practicality. |
| 14 | + |
| 15 | +## Packages |
| 16 | + |
| 17 | +### Main packages |
| 18 | + |
| 19 | +* `R2Shared` contains shared `Publication` models and utilities. |
| 20 | +* `R2Streamer` parses publication files (e.g. an EPUB) into a `Publication` object. |
| 21 | +* [`R2Navigator` renders the content of a publication](Navigator/Navigator.md). |
| 22 | + |
| 23 | +### Specialized packages |
| 24 | + |
| 25 | +* `ReadiumOPDS` parses [OPDS catalog feeds](https://opds.io) (both OPDS 1 and 2). |
| 26 | +* [`ReadiumLCP` downloads and decrypts LCP-protected publications](Readium%20LCP.md). |
| 27 | + |
| 28 | +### Adapters to third-party dependencies |
| 29 | + |
| 30 | +* `ReadiumAdapterGCDWebServer` provides an HTTP server built with [GCDWebServer](https://github.com/swisspol/GCDWebServer). |
| 31 | + |
| 32 | +## Overview of the shared models (`R2Shared`) |
| 33 | + |
| 34 | +The Readium toolkit provides models used as exchange types between packages. |
| 35 | + |
| 36 | +### Publication models |
| 37 | + |
| 38 | +#### Publication |
| 39 | + |
| 40 | +`Publication` and its sub-components represent a single publication – ebook, audiobook or comic. It is loosely based on the [Readium Web Publication Manifest](https://readium.org/webpub-manifest/). |
| 41 | + |
| 42 | +A `Publication` instance: |
| 43 | + |
| 44 | +* holds the metadata of a publication, such as its author or table of contents, |
| 45 | +* allows to read the contents of a publication, e.g. XHTML or audio resources, |
| 46 | +* provides additional services, for example content extraction or text search. |
| 47 | + |
| 48 | +#### Link |
| 49 | + |
| 50 | + |
| 51 | +A [`Link` object](https://readium.org/webpub-manifest/#24-the-link-object) holds a pointer (URL) to a resource or service along with additional metadata, such as its media type or title. |
| 52 | + |
| 53 | +The `Publication` contains several `Link` collections, for example: |
| 54 | + |
| 55 | +* `readingOrder` lists the publication resources arranged in the order they should be read. |
| 56 | +* `resources` contains secondary resources necessary for rendering the `readingOrder`, such as an image or a font file. |
| 57 | +* `tableOfContents` represents the table of contents as a tree of `Link` objects. |
| 58 | +* `links` exposes additional resources, such as a canonical link to the manifest or a search web service. |
| 59 | + |
| 60 | +#### Locator |
| 61 | + |
| 62 | +A [`Locator` object](https://readium.org/architecture/models/locators/) represents a precise location in a publication resource in a format that can be stored and shared across reading systems. It is more accurate than a `Link` and contains additional information about the location, e.g. progression percentage, position or textual context. |
| 63 | + |
| 64 | +`Locator` objects are used for various features, including: |
| 65 | + |
| 66 | +* reporting the current progression in the publication |
| 67 | +* saving bookmarks, highlights and annotations |
| 68 | +* navigating search results |
| 69 | + |
| 70 | +### Data models |
| 71 | + |
| 72 | +#### Publication Asset |
| 73 | + |
| 74 | +A `PublicationAsset` is an interface representing a single file or package holding the content of a `Publication`. A default implementation `FileAsset` grants access to a publication stored locally. |
| 75 | + |
| 76 | +#### Resource |
| 77 | + |
| 78 | +A `Resource` provides read access to a single resource of a publication, such as a file or an entry in an archive. |
| 79 | + |
| 80 | +`Resource` instances are usually created by a `Fetcher`. The toolkit ships with various implementations supporting different data access protocols such as local files, HTTP, etc. |
| 81 | + |
| 82 | +#### Fetcher |
| 83 | + |
| 84 | +A `Fetcher` provides read access to a collection of resources. `Fetcher` instances are created by a `PublicationAsset` to provide access to the content of a publication. |
| 85 | + |
| 86 | +`Publication` objects internally use a `Fetcher` to expose their content. |
| 87 | + |
| 88 | +## Opening a publication (`R2Streamer`) |
| 89 | + |
| 90 | +To retrieve a `Publication` object from a publication file like an EPUB or audiobook, begin by creating a `PublicationAsset` object used to read the file. Readium provides a `FileAsset` implementation for reading a publication stored on the local file system. |
| 91 | + |
| 92 | +```swift |
| 93 | +let file = URL(fileURLWithPath: "path/to/book.epub") |
| 94 | +let asset = FileAsset(file: file) |
| 95 | +``` |
| 96 | + |
| 97 | +Then, use a `Streamer` instance to parse the asset and create a `Publication` object. |
| 98 | + |
| 99 | +```swift |
| 100 | +let streamer = Streamer() |
| 101 | + |
| 102 | +streamer.open(asset: asset, allowUserInteraction: false) { result in |
| 103 | + switch result { |
| 104 | + case .success(let publication): |
| 105 | + print("Opened \(publication.metadata.title)") |
| 106 | + case .failure(let error): |
| 107 | + alert(error.localizedDescription) |
| 108 | + case .cancelled: |
| 109 | + // The user cancelled the opening, for example by dismissing a password pop-up. |
| 110 | + break |
| 111 | + } |
| 112 | +} |
| 113 | +``` |
| 114 | + |
| 115 | +The `allowUserInteraction` parameter is useful when supporting a DRM like Readium LCP. It indicates if the toolkit can prompt the user for credentials when the publication is protected. |
| 116 | + |
| 117 | +## Accessing the metadata of a publication |
| 118 | + |
| 119 | +After opening a publication, you may want to read its metadata to insert a new entity into your bookshelf database, for instance. The `publication.metadata` object contains everything you need, including `title`, `authors` and the `published` date. |
| 120 | + |
| 121 | +You can retrieve the publication cover using `publication.cover`. Avoid calling this from the main thread to prevent blocking the user interface. |
| 122 | + |
| 123 | +## Rendering the publication on the screen (`R2Navigator`) |
| 124 | + |
| 125 | +You can use a Readium navigator to present the publication to the user. The `Navigator` renders resources on the screen and offers APIs and user interactions for navigating the contents. |
| 126 | + |
| 127 | +```swift |
| 128 | +let navigator = try EPUBNavigatorViewController( |
| 129 | + publication: publication, |
| 130 | + initialLocation: lastReadLocation, |
| 131 | + httpServer: GCDHTTPServer.shared |
| 132 | +) |
| 133 | + |
| 134 | +hostViewController.present(navigator, animated: true) |
| 135 | +``` |
| 136 | +Please refer to the [Navigator guide](Navigator/Navigator.md) for more information. |
0 commit comments