Sign up
internetarchive
/
bookreader
Public
The Internet Archive BookReader
openlibrary.org/dev/docs/bookreader
AGPL-3.0 License
669 stars
320 forks
Star
Notifications
master
Go to file
iisa
4 days ago
README.md
Internet Archive BookReader
Disclaimer: BookReader v5 is currently in beta. It's stable enough for production use (and is what is being used on archive.org), but there will be some breaking changes in the next ~month or so to public BookReader APIs.
The Internet Archive BookReader is used to view books from the Internet Archive online and can also be used to view other books.
See live examples:
Demos
See BookReaderDemo directory. These can be tested by building the source files (make sure Node.js is installed):
npm run build
and starting a simple web server in the root directory:
npm run serve
And then open http://localhost:8000/BookReaderDemo/demo-simple.html​.
Usage
Here is a short example.
// Create the BookReader objectvar options = { data: [ [ { width: 800, height: 1200, uri: '//archive.org/download/BookReader/img/page001.jpg' }, ], [ { width: 800, height: 1200, uri: '//archive.org/download/BookReader/img/page002.jpg' }, { width: 800, height: 1200, uri: '//archive.org/download/BookReader/img/page003.jpg' }, ], [ { width: 800, height: 1200, uri: '//archive.org/download/BookReader/img/page004.jpg' }, { width: 800, height: 1200, uri: '//archive.org/download/BookReader/img/page005.jpg' }, ] ], bookTitle: 'Simple BookReader Presentation', // thumbnail is optional, but it is used in the info dialog thumbnail: '//archive.org/download/BookReader/img/page014.jpg'​, // Metadata is optional, but it is used in the info dialog metadata: [ {label: 'Title', value: 'Open Library BookReader Presentation'}, {label: 'Author', value: 'Internet Archive'}, {label: 'Demo Info', value: 'This demo shows how one could use BookReader with their own content.'}, ], ui: 'full', // embed, full (responsive)};var br = new BookReader(options);// Let's go!br.init();
Architecture Overview
Starting at v5, BookReader introduces hybrid architecture that merges the core code written in jQuery closer to its evolution as a web component. As we march toward the future of BookReader as a web component, we are taking an Event Driven approach to connect the two together.
Approach:
Menu panels: Web Components via LitElement
BookReader's side navigation is powered by LitElement flavored web components.
Core: jQuery
BookReader's core functionality is in jQuery. This includes:
A peek in how to use/extend core functionality:
Embedding BookReader in an iFrame
BookReader can be embedded within an <iframe>. If you use the IFrame Plugin inside the <iframe>, the reader will send notifications about changes in the state of the reader via window.postMessage(). The parent window can send messages of its own (also via window.postMessage()) and the IFrame Plugin will handle updating the reader to match.
Message Events
Fragment Change
The Fragment Change message is sent to the parent window when the embedded BookReader moves between pages/modes. When the <iframe> receives this message, it moves to the specified page/mode. The “fragment” is formatted in accordance with the BookReader URL spec.
{ "type": "​bookReaderFragmentChange​"​, "fragment": "page/n1/mode/2up" }
Development
(updates?)
The source JavaScript is written in ES6 (located in the src/js directory) and in ES5 (located in BookReader). npm run serve-dev starts an auto-reloading dev server, that builds js/css that has been edited at localhost:8000.
Until the next major version bump, we have to store the build files inside the repo to maintain backwards compatibility. Please DO NOT include these files in your PR. Anything in the BookReader/ directory should not be committed.
Releases
To version bump the repo and prepare a release, run npm version major|minor|patch (following semver), then (something like) git push origin HEAD --tags. It'll automatically update the version number where it appears, build the files, and ask you to update the CHANGELOG.
We release BookReader in-repo as tags & also as a node module @internetarchive/bookreader
Tests
We would like to get to 100% test coverage and are tracking our progress in this project: BookReader Fidelity
End to end tests
We also have end to end tests using Testcafe. We write tests for the repo itself and also for our use on archive.org. You can read about them in here. These are relatively easy to do, and a fantastic way of getting introduced to the wonders of BookReader. Check the project board for open tickets to work on. And if you don't see a test for something you spotted, feel free to make an issue.
To run all local end to end tests, run command: npm run test:e2e
To keep end to end test server on while developing, run command: npm run test:e2e:dev
Unit tests
We have unit tests and use Jest to run them. For mocks, we use Jest's internal mocking mechanism and Sinon to set spies.
To run all local unit tests, run command: npm run test
Ways to contribute
We can always use a hand building BookReader. Check out the issues and see what interests you. If you have an idea for an improvement, open an issue.
More info
Developer documentation: https://openlibrary.org/dev/docs/bookreader
Hosted source code: https://github.com/internetarchive/bookreader
IIIF (http://iiif.io) See BookReaderDemo/demo-iiif.html to see an example of how to load an IIIF manifest in BookReader.
Target Devices
Note that BookReader is a core part of Archive.org's mission of Universal Access to All Knowledge. Therefore, care must be taken to support legacy browsers. It should still work and be useable on old devices.
Areas for improvement
Change libraries to be NPM dependencies rather than included in the source code
See CHANGELOG.md for history of the project.
License
The source code license is AGPL v3, as described in the LICENSE file.
Other credits
The ability to test on multiple devices is provided courtesy of Browser Stack.
Releases 110
v5.0.0-22Latest
4 days ago
+ 109 releases
Packages 1
bookreader
Contributors 43
+ 32 contributors
Languages
JavaScript76.0%
HTML16.4%
CSS4.4%
SCSS3.2%
© 2021 GitHub, Inc.
Terms
Privacy
Security
Status
Docs
Contact GitHubPricingAPITrainingBlogAbout
CodeCodeIssuesIssues96Pull requestsPull requests77ActionsActionsProjectsProjects4WikiWikiSecuritySecurityInsightsInsights Code Issues Pull requests Actions Projects Wiki Security Insights