Package: eea.epub
A product which allows you to import in Plone epub files.ContentsContentsContentsIntroductionMain featuresEpub compatibilityDebuggingInstallationAsynchronous setupGetting startedImportExportCustom permissionsCan download ePub (eea.epub.download)Can customize ePub (eea.epub.customize)Content rulesePub export succeededePub export failedePub export failed (admin)Content rules email string substitution${download_came_from_url}${download_email}${download_error}${download_from_email}${download_from_name}${download_title}${download_url}${download_type}Disable ePub exportContent rulesTroubleshootingDependeciesLive demoSource codeCopyright and licenseLinksFundingChangelog7.4 - (2018-09-06)7.3 - (2018-05-25)7.2 - (2018-04-24)7.1 - (2017-12-12)7.0 - (2017-11-07)6.9 - (2017-05-22)6.8 - (2017-05-15)6.7 - (2017-04-24)6.6 - (2016-10-03)6.5 - (2016-05-19)6.4 - (2016-05-04)6.3 - (2015-08-18)6.2 - (2015-03-17)6.1 - (2015-02-27)6.0 - (2015-02-25)5.9 - (2015-02-16)5.8 - (2015-02-03)5.7 - (2014-09-15)5.6 - (2014-08-12)5.5 - (2014-08-12)5.4 - (2014-07-15)5.3 - (2014-06-06)5.2 - (2014-01-21)5.1 - (2013-11-20)5.0 - (2013-10-22)4.9 - (2013-10-07)4.8 - (2013-10-04)4.7 - (2013-06-17)4.6 - (2013-01-15)4.5 - (2012-11-22)4.4 - (2012-06-12)4.3 - (2012-04-26)4.2 - (2012-02-06)4.1 - (2012-02-06)4.0 - (2011-11-06)0.6 - (2011-04-07)0.5 - (2011-03-17)0.4 - (2011-03-09)0.3 - (2011-03-01)0.2 - (2010-10-29)0.1 - (2010-10-11)IntroductionEEA Epub product allows you to import in Plone epub files. On upload,
Epub content will imported as Plone folders, files, images and documents.Export to Epub is also available.As of version 4.3 epub files created withAdobe InDesign CS4andSigilare tested and known to work with this package, previous versions of this
package only supported epubs created with InDesign.Main featuresEEA Epub features:Imports epub files as Plone content.Stores the original epub in the main folder for easy retrieval.Exports the Plone content back into an epub.Clean filename as you import the epub and they contain characters that
wouldn’t be allowed as a Plone id.
This behaviour is on by default but it can be disabled by unchecking
the boolean flag at portal_properties/site_propertiesclean_epub_file_names.
If you find that the Document Pages added by the Epub process has broken
links try to re-upload without this boolean flag.Possibility to temporarily disable dynamic ePub creation by adding an item
called ‘action-download-epub’ within contextAsynchronously generate ePub files and notify users by email
when ePub is readyEpub compatibilityEEA Epub makes the following assumptions about the loaded epub:You don’t use unicode or other special characters into the name
of the epub, images or linksYou’ve created the epub with “Adobe InDesign CS4” or “Sigil” which uses
some standards for the following:The table of contents is named toc.ncx and is placed inside OEBPSBook text & images are placed inside the folder OEBPS or other folders
that are children of OEBPSItems ids doesn’t contain the following characters . / ( if
possible stick to letters, numbers and - _ )Best practices when creating an epub:Chapter names should not be all uppercase or use special charactersImage names should not contain spaces, periods, / or other special charactersDebuggingAt this moment any errors that would appear on the site are surpressed
with a info message.If you want to see the detailed error check the Plone instance log usually
found in buildout-folder/var/log.InstallationThe easiest way to get eea.epub support in Plone 4 using this
package is to work with installations based onzc.buildout.
Other types of installations should also be possible, but might turn out
to be somewhat tricky.To get started you will simply need to add the package to youreggsandzcmlsections, run buildout, restart your Plone instance and install theeea.epubpackage using the quick-installer or via the “Add-on
Products” section in “Site Setup”:[instance]
eggs =
    eea.epub

zcml =
    eea.epubYou can download a sample buildout at:https://github.com/eea/eea.epub/tree/master/buildouts/plone4Asynchronous setupBy default all ePubs areNOTgenerated asynchronous. You’ll needeea.pdfinstalled in order to be able to enable asynchronous download or you can
provide an os environment calledEEACONVERTER_ASYNC.Also some extra config is needed within your buildout in order for this
to work properly.First of all you’ll need a folder were to store generated ePub files. For this
you can create it manually within buildout:directory/var/ or
you can let buildout handle it:[buildout]

parts +=
    media-downloads
    media-downloads-temp

media-downloads-path = ${buildout:directory}/var/downloads/pdf
media-downloads-temp = ${buildout:directory}/var/downloads/tmp

[media-downloads]
recipe = ore.recipe.fs:mkdir
path = ${buildout:media-downloads-path}
mode = 0700
createpath = true

[media-downloads-temp]
recipe = ore.recipe.fs:mkdir
path = ${buildout:media-downloads-temp}
mode = 0700
createpath = trueThis will create a folder nameddownloadswithin buildout:directory/var/Next, in order for this folder to be visible from your website and your users to
be able to download generated ePubs you’ll need to tell to your zope instances
about it:[buildout]

media-downloads-name = downloads
media-downloads-path = ${buildout:directory}/var/downloads/pdf
media-downloads-temp = ${buildout:directory}/var/downloads/tmp

[instance]

environment-vars +=
  EEADOWNLOADS_NAME ${buildout:media-downloads-name}
  EEADOWNLOADS_PATH ${buildout:media-downloads-path}
  EEACONVERTER_TEMP ${buildout:media-downloads-temp}
  EEACONVERTER_ASYNC TrueAlso, don’t forget to setupplone.app.async[buildout]

[instance]
eggs +=
    plone.app.async
zcml +=
    plone.app.async-single_db_workerGetting startedImportFrom “Add new” menu select “EpubFile” and upload an epub file.ExportGo to Home page and click on download as ePub icon at the bottom of the pageor directly accesshttp://localhost:8080/Plone/front-page/download.epubCustom permissionsCustom permissions added by this packageCan download ePub (eea.epub.download)Assign this permission to roles that you want to be able to download content as ePub
Default: Owner, Manager, EditorCan customize ePub (eea.epub.customize)Assign this permission to roles that you want to be able to contextually customize
the output ePub look and feel
Default: Manager, Site AdministratorContent rulesThis package uses Plone Content-rules to notify users by email when an asynchronous
ePub job is done. Thus 3 custom content-rules will be added within
Plone > Site Setup > Content-rulesWarningAs these content-rules are triggered by an asynchronous job, while
you customize the email template for these content-rules,
pleaseDO NOT USE OTHERstring substitutionsthat the onesthat start
with$download_as you’ll break the download chain.
Also if you disable these content-rules the users will never know when the
ePub is ready and what is the link where they can download the output ePub.ePub export succeededNotify the person who requested a ePub export that the ePub successfully exported
and provide a link to the downloadable ePubePub export failedNotify the person who requested a ePub export that the ePub export failed.ePub export failed (admin)Notify admin that there were issues while exporting ePubContent rules email string substitutionIn order to be able to easily customize emails sent by this package the following
custom email template string substitutions can be made${download_came_from_url}The absolute URL of the Plone object which is downloaded as ePub${download_email}Email address of the user that triggered the download as ePub action${download_error}Error traceback when download as ePub job fails${download_from_email}Site Admin email address customizable via Plone > Site Setup > Mail${download_from_name}Site Admin name customizable via Plone > Site Setup > Mail${download_title}Title of the Plone object which is downloaded as ePub${download_url}The absolute URL where the generated output ePub can be downloaded${download_type}Download type. Default to EPUB for this package. It is package specific and it
can be EPUB, PDF, etc.Disable ePub exportYou have the possibility to temporarily disable dynamic ePub export contextually
by adding a static ePub file (or a Python Script, Page Template, etc)
within context calledaction-download-epub. This way /download.epub will
return this file instead of generating one based on context data.NoteThis works only with folderish items.Content rulesThis package uses Plone Content-rules to notify users by email when
an asynchronous ePub job is done. Thus 3 custom content-rules will be added
within Plone > Site Setup > Content-rulesWarningAs these content-rules are triggered by an asynchronous job, while
you customize the email template for these content-rules,
pleaseDO NOT USE OTHERstring substitutionsthat the onesthat start
with$download_as you’ll break the download chain.
Also if you disable these content-rules the users will never know when the
ePub is ready and what is the link where they can download the output ePub.TroubleshootingePub files are generated asynchronously using a parallel zc.async queue.quota.
The number of workers that will generate ePUBs in parallel is automatically
calculated based on the number of zeo-clients registered withplone.app.async-*_db_worker.As everydb_workercan handle simultaneouslymaximum 3 jobs(hard-coded in zc.async Agent),
if you have2 workersthen the maximum number of ePub files that will be generated
at the same time will be6(2 workers * 3). Same if you have5, you’ll get15 ePub filesgenerated at the same time.If for any reason you don’t want them to be generated simultaneously you can set
environment variableEEAEPUB_ASYNC_THREADSto1within buildout:[buildout]

...

[instance]

...

environment-vars +=
    EEAEPUB_ASYNC_THREADS 1Also, if you experience issues by having too many simultaneously ePub jobs, you
can limit them in the same way as above.DependeciesBeautifulSoupLxmlPlone 4.xplone.app.asynceea.convertereea.downloadseea.pdf(optional for advanced themes and asynchronous download)Live demoHere some live production demos at EEA (European Environment Agency)https://www.eea.europa.eu/soer/synthesisSource codeLatest source code (Plone 4 compatible):https://github.com/eea/eea.epubPlone 2 and 3 compatible:https://github.com/eea/eea.epub/tree/plone25Copyright and licenseThe Initial Owner of the Original Code is European Environment Agency (EEA).
All Rights Reserved.The EEA Epub (the Original Code) is free software;
you can redistribute it and/or modify it under the terms of the GNU
General Public License as published by the Free Software Foundation;
either version 2 of the License, or (at your option) any later
version.More details under docs/License.txtLinksEEA Epub wiki page:https://taskman.eionet.europa.eu/projects/zope/wiki/HowToEpubFundingEEA- European Enviroment Agency (EU)Changelog7.4 - (2018-09-06)Change: Added uninstall profile
[avoinea refs #96114]Change: updated URLs pointing to eea.europa.eu withhttps://[alecghica refs #95849]Change: fixed the usage of BeautifulSoup
[alecghica refs #96974]7.3 - (2018-05-25)Bug fix: Speed-up cache invalidation for backward-references
[avoinea refs #95020]7.2 - (2018-04-24)Change: Make zc.async logs less verbose about ePub downloads
[avoinea]7.1 - (2017-12-12)Change: Replace eeacms/zptlint with eeacms/plone-test:4 zptlint
[avoinea refs #90415]7.0 - (2017-11-07)Change: Remove Sphinx generated documentation
[petchesi-iulian refs #88212]6.9 - (2017-05-22)Change: Run async ePub jobs in parallel
[avoinea refs #84915]Change: fixed PyLint warnings and errors
[valipod refs #84949]6.8 - (2017-05-15)Change: fixed PyLint warnings and errors
[eduard-fironda refs #84949]6.7 - (2017-04-24)Change: updated package information
[eduard-fironda]6.6 - (2016-10-03)Change: Updated to use plone.stringinterp IContextWrapper adapter
[avoinea]6.5 - (2016-05-19)Bug fix: Fix pylint warnings
[chiridra refs #71940]6.4 - (2016-05-04)Update eea.translations with the latest translation strings -
fixed errors in templates
[chiridra refs #69753]6.3 - (2015-08-18)Change: Auto-include zcml within plone context in order to make this package
work without having to add it within buildout zcml directive.
[avoinea]6.2 - (2015-03-17)Change: Switched to curl in the jenkins build install script
[olimpiurob refs #22402]Change: Changed fetch url for jenkins build install script to the install
script from the main EEA CPB repository
[olimpiurob refs #22402]Bug fix: Added a way to know if the ePub is being generated even if the
async worker is down or the queue is too busy.
[voineali refs #23411]6.1 - (2015-02-27)Bug fix: Fixed validation errors for exported ePubs (epubchecker)
[avoinea]6.0 - (2015-02-25)Upgrade step:
I. Within “Plone > Site setup > Add-ons” install “EEA Converter”
II. WithinPlone > Site setup > Content Rules:
1. Filter byAsync PDF Export (fail)andAsync PDF Export (success)2. Disable founded rules
3. Filter byAsync Export (fail)andAsync Export (success)4. Update these rulesemail textswith previous disabled ones (PDF ones) by changingPDFwith${download_type}5. DeleteAsync PDF Export (fail)andAsync PDF Export (success)related rules
[voineali refs #22971]Feature: Added possibility to download documents as ePub asynchronously
[voineali refs #22971]Bug fix: fixed UnicodeDecodeError within download.epub template
[voineali refs #23338]5.9 - (2015-02-16)Feature: Added possibility to add a fallback ePub file within context calledaction-download-epubin order to temporarily stop dynamic ePub
generation and statically return this item.
[voineali refs #22970]5.8 - (2015-02-03)Feature: Added “Download as ePub” action also within export_actions category
[voineali refs #22686]5.7 - (2014-09-15)Change: Made @@epub.support/can_download accessible from URL
[voineali refs #20846]5.6 - (2014-08-12)Bug fix: fixed tests
[ghicaale refs #20451]5.5 - (2014-08-12)Upgrade step: Assign “Can download ePub” permission to
CommonEditorUpgrade step: Within “Plone > Site setup > Add-ons” click on
upgrade button available for eea.epubChange: Renamed epub_view to download.epub
[voineali refs #20393]Feature: Added “Can download ePub” and “Can customize ePub” permissions
[voineali refs #20436]5.4 - (2014-07-15)Bug fix: Export to epub even if there is no PDF cover set for content-type
[voineali refs #20268]Change: Removed collective.sendaspdf dependency
[voineali refs #20268]5.3 - (2014-06-06)Upgrade step: Within “Plone > Site setup > Add-ons” click on
upgrade button available for eea.epub
[voineali refs #19882]Change: Moved EPUB related images and actions from eea.soercontent package
[voineali refs #19882]5.2 - (2014-01-21)Feature: adding Sphinx-generated documentation in Page Template format
[batradav refs #9502]Bug fix: removed wrongly added blockquotes within README.rst
[ichim-david refs #18064]Bug fix: Updated old URLs pointing Trac
[ghicaale refs #18003]5.1 - (2013-11-20)Bug fix: links were missing any style
[simiamih refs #16799]5.0 - (2013-10-22)Feature: improved epub - daviz reference, toc, styles, cover
[simiamih refs #16799]4.9 - (2013-10-07)Feature: major export improvements - image files, cover photo, css
[simiamih refs #16799]4.8 - (2013-10-04)Change: updated zope imports with the versions that require minimum Plone 4.1
for eea.epub
[ichimdav refs #15651]4.7 - (2013-06-17)Change: use BeautifulSoup4 instead of deprecated BS 3
[tiberich #14584]4.6 - (2013-01-15)Upgrade step: Within “Plone > Site setup > Add-ons” click on
upgrade button available for eea.epub
[ichimdav #9068]Feature: register epubs with application/epub+zip mimetype
[ichimdav #9068]4.5 - (2012-11-22)Upgrade step: Within “Plone > Site setup > Add-ons” click on
upgrade button available for eea.epub
[ichimdav #3621]Feature: use filename id when creating plone content, cleaning the filename
id when it contains illegal characters if boolean property
clean_epub_filename is enabled at portal_properties/site_properties
[ichimdav #3621]4.4 - (2012-06-12)Bug fix: fixed markup of HISTORY.txt file
[ciobabog refs #5231]Change: Change code in eea.epub to fix translation problem
[prospchr refs #5159]4.3 - (2012-04-26)Feature: import epubs that are not created by Adobe Indesign which have the
images and the html pages in separate folder like those created by Sigil
[ichimdav #5054]4.2 - (2012-02-06)no changes4.1 - (2012-02-06)Bug fix: Added dependencies to setup.py
[voineali]4.0 - (2011-11-06)Bug fix: proper parsing of html entities by using an html parser instead of
an xml one
[ichimdav #4523]Bug fix: cleaned spaces defined as &nbsp that can’t be read as xml
[ichimdav #4271]Cleanup: fixed all pylint, pyflakes violations
[voineali #4121]Feature: added upgrade steps
[voineali @4392]Feature: Plone 4.0.4 compatible release
[tiberich #4121]0.6 - (2011-04-07)Bug fix: clean epub import to prevent navigation portlet from miss-behaving
[ichimdav #4242]Bug fix: fixes #4242 Removed / clean up, the portlet epub and toc,
we can use standard plone nav
[demarant]Feature: force documents/chapters not to be renamed after title change
[demarant]0.5 - (2011-03-17)Bug fix: fixed wrong anchors that spanned over paragraphs
[ichimdav #4196]Bug fix: added translation domain to ZCML files
[voineali #4139]0.4 - (2011-03-09)Change: cleaned test, added doctypes, fixed pylint violations warnings
[ichimdav #4140]0.3 - (2011-03-01)Change: surpressed error messages with an info status message
[ichimdav #3883]Bug fix: fix epub file import
[ichimdav #3883]0.2 - (2010-10-29)Feature: add-to-folder menu item
[thuliper #3627]Bug fix: image link fixes
[thuliper #3711]0.1 - (2010-10-11)Initial release