This plugin allows you to display readable versions of (non-DRM) Epub books, navigable via the internal chapters, on your Umbraco site. The Epub file format is basically a .zip archive with embeded html, css, font & image files.
This version of the plugin is for Umbraco v8.1+. For Umbraco v7.6+ use the Tag 0.1.1
Using the provided example 'Book' & 'Books' Document Types and Templates (included in the installable package - not the nuget package) and Setup (see 'Setting Up' below), you can view/read your epub books by simply navigating to:
...to view a list of all your books. Uses the 'Books' template.
...to see the book info page. This page uses the 'Body Text' and 'Book Cover Image' from the related 'Book' content node. Uses the 'Book' template.
...to actually read the book. This page (which uses the view: /Views/UmbEpubReader_Read.cshtml) displays the 'Book' node Cover Image as well as the actual epub chapter content and Table of Contents. This View can be ammended as needed. It has access to the 'EpubDisplayModel' model from which you can access any of the model's properties, some of which are: Title, Authors, Cover Image, Chapter Html, Table of Contents (List<EpubLink>), an html <UL> formatted verion of Table of Contents, Previous/Next Chapter EpubLink navigation links. By default the first chapter will be displayed, unless the 'Start at Chapter' Book property has been set, in which case, that chapter will be the default chapter displayed.
Note: The provided templates/views are only basic examples of the plugin functionality. You can adapt them to your requirements.
Epub books have embeded files such as images and fonts, and the plugin allows these file to be served/accessed via custom book routing i.e. /books/{NAME OF BOOK}/read/images/cover.jpg. Embeded book css styles are added automatically to the outputted html to speed up rendering. See the Security section below.
Please note this plugin has been developed for a specific project and as such may not provided an exhaustive list of functionality or deal with all possible eventualities when encountering different epub books. You can, however, use the plugin source code as a basis for your own requirements.
This documentation/plugin assumes your site already has a basic setup e.g a Homepage Doc type and Master template or 'Umbraco Starter Kit' or similar has been installed.
Any feedback/comments/question are welcome - please use the Umbraco Project Forum https://our.umbraco.com/projects/website-utilities/epub-reader/issues-and-feedback/.
Install the package through the Umbraco backoffice (Note: This is the preferred method as it includes the required Document Types/Templates):
- In Developer -> Packages backoffice. Search for 'Epub Reader', in 'Website Utilities'
- or download the package as a zip from https://our.umbraco.org/projects/website-utilities/epub-reader/. Manually install via 'Install local' in your Umbraco package backoffice.
- or download the package as a zip from this project's GitHub page https://github.com/willroscoe/UmbEpubReader/releases. Manually install via 'Install local' in your Umbraco package backoffice.
or via NuGet (Note: Not preferred, as doesn't include the example Document Types/Templates - see above):
PM> Install-Package UmbEpubReader- or manually download the NuGet Package. Install the NuGet package in your Visual Studio project.
To use the provided example 'Book/Books' Document Types and Templates.
Once the package has been installed, there is a small amount of setting up to do before being able to add books. In Admin:
- Settings -> Templates - Make sure the 'Books' and 'Book' templates are children of the 'Master' template
- Settings -> Document Types -> Home -> Permissions -> Add Child -> Select the 'Books' Document Type -> Save
- Content -> Home -> Create an Item under Home -> Books -> Titled 'Books' -> Using the 'Books' template -> Save and Publish (or Save)
Once setup is complete you can add book pages to your site:
- Content -> Home -> Books -> Create Book -> Add the book items.
The path to the books will be /books/{NAME OF BOOK}. If you want a different path e.g. /ebooks/{NAME OF BOOK} you should rename the 'Books' item in 'Setting up' point 3 (above) to the desired name i.e. 'Ebooks'. In order for the plugin routing to work correctly for the '/read' route you will also need to add/update the 'UmbEpubReader.BooksPathSegment' app setting in your Web.Config. See 'Web.Config Settings'
Optional appSettings:
<appSettings>
...
<add key="UmbEpubReader.BooksPathSegment" value="books"/>
<add key="UmbEpubReader.ReadPathSegment" value="read"/>
...
</appSettings>
The key 'UmbEpubReader.BooksPathSegment' allows you to override the /books/{NAME OF BOOK} path segment (however, you must also update the 'Books' Content node name to the same value). e.g. setting it to 'ebooks' will allow the following path /ebooks/{NAME OF BOOK} to work.
The key 'UmbEpubReader.ReadPathSegment' allows you to override the /books/{NAME OF BOOK}/read path segment. e.g. setting it to 'readonline' will allow the following path /books/{NAME OF BOOK}/readonline to work
Please bear in mind that Epub books could potentially contain malicious embeded files which could be served by the plugin. As a precaution the plugin currently only permits the following file extensions to be served: .html, .htm, .xhtml, .jpg, .gif, .png, .css, .ttf, .otf, .woff, .woff2, .svg
It is advisable to vet/check any epub files before using. This can be done by changing the .epub extension to .zip and uncompressing the archive in order to inspect all the contained files.
This project references the following additional projects:
Copyright © 2018 Will Roscoe
Licensed under the MIT License
- 0.1.0
- Initial release
- 0.1.1
- Fixed TOC UL output
- 8.0.1
- Updated for Umbraco v8.1+. NOte: Major version number now reflects the Umbraco major verion number