[GUI Plugin] Ex Libris

[AlPe]

This plugin allows you to insert an ex libris into your eBooks in EPUB format.

The source code is available in this GitHub repo.

In particular, this is the Calibre plugin version of the CLI tool described in this discussion.

You can select a single ebook or your entire Calibre library, and have the same ex libris applied to all of them! You can both replace the existing eBooks or create a copy.

You must supply an XHTML file containing the ex libris to be inserted, and --- optionally --- any other resource needed (images, CSS files, fonts, etc.).

If you select a single EPUB book, the main window will show you its spine and TOC, to help you specify the insertion points of the ex libris page.

If you select multiple EPUB books, you can only specify "1" or "first" or "last" as insertion points, both for the spine and for the TOC. You can overrule this limitation (at your own risk!) unchecking the respective checkbox in the configuration window.

The current version can replace placeholders in the XHTML page (written as [%key%]) using the eBook metadata (e.g., [%title%]), Calibre metadata (e.g., [%calibre-title%]) or user-provided strings ([%yourMessageHere%]). The set of supported metadata tags can be found on the configuration window. In the latter case, the user can define her own keys.

Main Features as in v. 1.0.19

• Single EPUB or Multiple EPUBs selection
• Spine and TOC are displayed when a single EPUB is selected
• Replace existing EPUB file or create a copy
• Include external resources (images, CSS, fonts) beyond the ex libris XHTML page
• Replace string placeholders in the XHTML page (in the form: [%key%]) with book metadata, Calibre metadata, or user-supplied values that can be set through the configuration window of the plugin
• Ex libris removal function
• Help dialog
• Examples of XHTML ex libris pages included in the ZIP file

Special Notes

• Your eBook input file must be "EPUB 2.0.1"-compliant, and your ex libris input file must be "XHTML 1.1 strict"-compliant, otherwise exlibris is not guaranteed to work properly and it might produce an invalid EPUB file.
• Currently exlibris includes the additional files (images, CSS, fonts, etc.) using their extension to set the proper media-type field. Please name your file consistently. For example, do not name a JPEG image 'image.svg' but use 'image.jpg' or 'image.jpeg'.
• This Calibre plugin was developed under Calibre 0.8.51, but it might work on earlier versions.

Installation Steps

• Download the attached zip file and install the plugin/restart calibre/add to context menu or toolbar as described in the Introduction to plugins thread.
• Select at least one EPUB file
• Open the plugin window (you can use the keyboard shortcut CTRL+SHIFT+X)
• Click on 'Configure'
• Select your exlibris XHTML page and, optionally, other external resources and/or modify the default configuration options
• Click on 'OK'
• Congratulations, now you can apply your nice ex libris to all the EPUB eBooks you want!

Paypal Donations:
If you like this project, I ask you to consider supporting the eBook Club Italia (http://ebci.it/), a non-profit association that promotes reading, especially using digital devices. You can help through a donation (there is a PayPal button on the right column of the home page) or by becoming a member.

Version History

Spoiler:

Version 1.0.19 - 02 Sep 2014
Alignment with the plugin repo on GitHub: https://github.com/pettarin/exlibris
Version 1.0.18 - 30 Aug 2014
Courtesy of @davidfor of MobileRead, this plugin now works with Calibre 2
Version 1.0.17 - 25 Aug 2013
Fixed a bug preventing the expected operation of the plugin on eBooks already modified by Calibre, which was introduced in zipfile by Python 2.7.4: importing calibre.utils.zipfile instead.
Version 1.0.16 - 14 Nov 2012
Added support for series-index Calibre metadatum (use [%calibre-series-index%] placeholder).
Version 1.0.15 - 11 Nov 2012
Added support for replacing string placeholders in the XHTML ex libris page with Calibre metadata. Added HELP dialog. Added ex libris examples in the ZIP file.
Version 1.0.14 - 21 Oct 2012
Added ex libris removal function. Attempting at adding an ex libris to an EPUB already containing one will result in the latter being overwritten by the new one.
Version 1.0.13 - 02 Sep 2012
Fixed a bug that prevented the correct operation under Windows, by forcing the encoding to UTF8 while reading the original EPUB. Also improved the parsing routines.
Version 1.0.12 Not released
Version 1.0.11 - 26 Aug 2012
Fixed a critical bug involving the creation of a temporary directory to unpack the EPUB file. This bug prevented the correct operation of the plugin when not launched from a console.
Version 1.0.10 - 25 Aug 2012
Fixed two bugs, one in the main exlibris library, the other one in the exception handling.
Version 1.0.9 - 21 Aug 2012
Initial release.

[AlPe]

I attach some screenshots from v. 1.0.9.

[dtrounson]

Amazing, weirdly enough I was going to ask if anybody had thought of doing something like this, I will give it a shot later

[AlPe]

Hi, I have just attached v. 1.0.10, fixing two bugs, one in the main exlibris library (thanks to Terisa de morgan for reporting it and providing me with an EPUB), the other one in the exception handling (thanks to lucbolo in the SBF forum for reporting it).

[AlPe]

I am currently planning the following new features:

1) Align the shortcut management with the Calibre centralized one.
2) If you use the copy function, mark the copy EPUB (containing your ex libris) in some way, for example by setting its date to "today" instead of the currrent date. Is it possible to define custom fields in the metadata, so that I can add that column to my library view?
3) If I try to insert the ex libris and the eBook already contains one, just overwrite it.
4) Ex libris removal function.
5) Use calibre metadata (e.g., user-modified title) instead of book metadata when substituting string placeholders.

(Thanks to gnomik from SBF forum for suggesting some of them.)

[Terisa de morgan]

Now I have a different problem. The log is:

Spoiler:

Traceback (most recent call last):
File "calibre_plugins.exlibris_plugin.main", line 184, in apply_replace
File "calibre_plugins.exlibris_plugin.main", line 193, in applyExlibris
AttributeError: 'MainDialog' object has no attribute 'spine_max_index'

The same book works OK with the command version.

Sorry for being a spoilsport

[AlPe]

No, there is absolute no problem; given my knowledge of Python and the several different ways of formatting EPUBs, I am surprised that exlibris *works* in many cases :P

Are you using the EPUB file you sent me or another one? On the one you sent me, I do not get the same error.

In the main window, are the spine/TOC lists visible?

[Terisa de morgan]

No, it's another one, I apologize I'll try the other... And no, the spine/TOC lists are visible.

And yes, I agree that ePub can be a mess (I don't talk about python knowledge, mine is not very great, I can debug and modify some things, not going much further ).

[Terisa de morgan]

Checked. It doesn't work with that either. I'll try to explore a bit more (working knolewdge at hand )

[AlPe]

That's quite strange.

The error says that the field "spine_max_index" (= maximum index in the toc) has not been initialized. It should be set when you try to insert the ex libris on a single EPUB file, after getting the spine list. So, if you see the spine list in the window, "spine_max_index" should be set. I am confused.

What are your Calibre version and your OS ?

[Terisa de morgan]

Windows 7 64 bits and calibre 0.8.66. This evening I'll make more tests.

[Terisa de morgan]

And my mistake. I DON'T see the chapter list.

[AlPe]

Ok, that's makes sense. Probably the main exlibris library is not able to read the spine from the EPUB for some reason.

I got reports from fellow Italian users, using Windows/Linux machines, and almost always the plugin was working properly. However, in one case the plugin was not behaving correctly, and it was a portable version of Calibre.

I suspect that it is due to the exlibris attempt to create a temporary directory for unpacking the EPUB and examining its content, but I have to better explore the issue.

(I assume you upgraded correctly the plugin to the new version 1.0.10 --- please check the 'About' dialog out --- and restarted Calibre, right?)

[Terisa de morgan]

It's already checked. I'll try to look at temp dir, perhaps the properties.

[AlPe]

I am interacting with a user of the SBF forum, who has the same problem (on OS X, though.) and he seems to confirm that the problem relies on the attempt to create a tmp directory to unpack the EPUB.

I am planning to have a better look at the issue tomorrow, and I guess the solution involves taking advantage of the standard Calibre function that gives you a temp dir.

Another user confirmed that the plugin runs well on another Linux machine, with Calibre version 0.8.61 (which is different than mine).

EDIT: Terisa, would you mind 1) uninstalling the plugin; 2) installing from this file; 3) restarting Calibre; 4) trying to apply your ex libris? It should work now.