Is there any documentation on how to use this?

[IneffableBunch]

Hi @mickael-menu

I'm trying to work with this package, but I'm really struggling to decipher the workings of it from the TestApp. is there any documentation I can look to?

Thank you :)

[mickael-menu]

Unfortunately the documentation is still really sparse, and I just recently started writing user guides for new features: https://github.com/readium/swift-toolkit/tree/develop/Documentation/Guides

To understand the models (Publication, Locator, etc.) used in the toolkit, as well as the main components, you can take a look at this repo: https://github.com/readium/architecture

If you have more practical questions or issues, write them down here and I'll try to answer or point in the right direction.

[mickael-menu]

To get you started, here's how to build a minimal EPUB reader using the Readium Swift toolkit:

1. Parse an EPUB file into a Publication model using the Streamer

let streamer = Streamer()
let epubAsset = FileAsset(url: epubURL)

streamer.open(asset: epubAsset, allowUserInteraction: true) { result in
    switch result {
    case .success(let publication):
        presentNavigator(publication)
    case .failure(let error):
        showError(error)
    case .cancelled:
        break
    }
}

2. Add the Publication to the local HTTP server to serve the EPUB content

To render an EPUB, it needs to be served through an HTTP server. The streamer package provides one.

You need to create it once and keep an instance throughout your app:

guard let server = PublicationServer() else {
    fatalError("Can't start the publication server")
}

Then when you're ready to present a publication with the EPUB navigator, you can add it to the server:

try server.add(publication)

3. Present the EPUB with EPUBNavigatorViewController

let navigator = EPUBNavigatorViewController(
    publication: publication,
    // This is used to restore the reading progression
    initialLocation: nil,
    resourcesServer: server,
)
present(navigator)

The EPUBNavigatorViewController only provides:

• Rendering and scrolling through the EPUB pages
• Reporting the current location (Locator object)
• Navigating to other locations (e.g. a Link from the table of contents)
• Delegate callbacks for events such as "didTap"

What the EPUBNavigatorViewController doesn't provide:

• There is no user interface except for the EPUB content, the UX is up to you in the parent view controller.

What you could/should do:

• Implementing NavigatorDelegate.navigator(_:locationDidChange:) to save the last location in your database, to be used as the initialLocation when creating the EPUBNavigatorViewController.
• Toggling a custom navigation bar / toolbars when receiving the VisualNavigatorDelegate.navigator(_:didTapAt:) event.

5. What to expect for the future of the toolkit

Some steps are still a bit complicated to integrate in the current version of Readium, and we want to improve these areas.

• Get rid (or at least hide) the HTTP server.
• Simpler user settings API integrated in the Navigator.

[Pasta]

this should be in the getting started wiki page

[mickael-menu]

It is, but only for the v3 API. This comment relates to version 2.

[IneffableBunch]

Wow, I did not expect an answer let alone such a comprehensive one so fast. Thank you so much!
This is really valuable info that would be very helpful to most!

[mickael-menu]

I'm closing this discussion as the answer concerns the deprecated v2. v3 will be released early January.