shu_epub
A Dart EPUB parser built from the ground up, and designed to support a variety of use cases and custom implementations such as on-device caching and serving content from a server. This package is current WIP and is NOT yet usuable.
Motivation
This package enables the application to only have the files needed from the EPUB file loaded into memory, instead of the entire EPUB file being required in memory like in other popular epub packages.
Features
- EpubControllerBase - An abstract class intended to be extended to enable flexibility inspired by Flutter's Widget class
- Enables use cases such asserving epubs from the web or caching epubs on the file system
- EpubArchiveController - Extends EpubControllerBase, reads in entire bytes of an .epub file for reading and independent from dart:io
- EpubArchiveIOController - Extends EpubControllerBase, uses file reference to the .epub file to only read in files when required. However, this cannot take advantage of the system cache.
- (flutter_shu_epub) EpubCacheController - Extracts ePub contents onto an Android or iOS device and caches the location, allowing for the reader to only load the needed files into memory
and more...
Progress and Plans
shu_epub (this package)
- Models
- Reader Controllers
- EpubContainerReaderController
- EpubPackageReaderController
- Support Epub 2 Out-Of-Line XML Islands, removed in Epub 3
- EpubNavigationReaderController
- EpubDetailsReaderController
- Combines the container, package, and navigation into one class
- Publication/Content Controller
- EpubControllerBase (abstract)
- Future getFilePaths - Method to get filepaths to all files in the epub
- Future getFileBytes - Method to get bytes of file from the filepath
- getEpubDetails
- others tbd...
- EpubArchiveController extends EpubController
- Given the loaded
.epub
file bytes - Overrides getFilePaths and getFileBytes to use
Archive
/ArchiveFile
- Given the loaded
- EpubArchiveIOController extends EpubController
- Given a file reference/path
- Overrides getFilePaths and getFileBytes to use filestream
Archive
/ArchiveFile
- (In
example.dart
) EpubExtractedController extends EpubController- Given a directory reference/path to the root folder of the extracted epub
- Overrides getFilePaths and getFileBytes to use async
dart:io
- Due to it requiring
dart:io
, it is not included in this package
- Function/Class to declare supported epub content media types
- Default is
application/xhtml+xml
- Old epubs may use the deprecated
application/x-dtbook+xml
andtext/x-eob1-document
- Default is
- EpubBook class to simplify access to Epub content and metadata
- EpubDetails (contains EpubContainer, EpubPackage, and EpubNavigation)
- EpubFiles (all files listed in manifest)
- Don't include items that are Out-Of-Line XML Islands
- EpubReadingOrder (spine)
- List of EpubFile (should all be xhtml files?)
- Files are from manifest items included in the spine, in the same order as listed in the spine. Automatically uses the fallback file if required-modules is specified, or if the media-type is not included in the supported mediaTypes configuration.
- EpubTableOfContents (ncx)
- Navigation Metadata
- Navigation Title
- Navigation Author
- Navigation Points (navMap)
- File
- CFI Location
- Pages Optional (pageList)
- Other Navigation Lists Optional (navList)
- CFI Generator
flutter_shu_epub (tenative)
- Uses Models and Parsers from dart_epub
- Platform specific implementation to handle caching, only loads the files it needs into memory
- Controllers
- EpubCacheController extends EpubController
- Reads from a
.epub
file extracted onto the file system, so only the files needed are loaded into memory - Overrides getFilePaths and getFileBytes to use dart:io
File
- Reads from a
- EpubCacheManagerSingleton
- Function to read an
.epub
file into memory and cache it on local storage for quick access later, with an optional id. The id is returned and it should be saved persistently with a package such as Hive - Local Database for each cached EPUB with EpubCache, which includes information about the EPUB and the EpubCacheController associated with it
- Clear cache
- Delete epub from cache
- Get all cached epub information
- Function to read an
- EpubCacheController extends EpubController
- Models
- EpubCache
- uid, can be specified
- epub name
- original filename
- cache path
- epubCacheController
- EpubCache
- Widgets
- Table of Contents Panel (Side panel, bottom sheet, or whole/half page)
- Contents View (Vertical scrolling or paged)
- Loading view while reading from
.xhtml
file - How HTML+CSS is rendered is TBD
- Text selection
- Add buttons to popup
- Custom text selection popup builder
- Text highlighting (maybe use CFIs?)
- Option to override font, font size, line spacing
- Go to CFI location (scroll or page)
- Go to CFI History
- Optional page between chapters
- Page turn transitions
- Bookmark support (through CFIs)
- Searchable
- Loading view while reading from
- Epub Title
- Pictures ListView
- Search Panel/Page
- Search current chapter or all chapters
Testing
Run tests with the following command
dart test
Test Coverage
Generate test coverage by running the following commands
dart pub global activate coverage
dart test --coverage="coverage"
dart pub global run coverage:format_coverage --lcov --in=coverage --out=coverage.lcov --packages=.packages --report-on=lib