Writing an interface action plugin

[kiwidude]

One feature I would love to have are some context menu items for looking up various things from the selected book on external websites in a separate browser window. For instance looking up the author on fantasticfiction.co.uk (so I can see other titles by the author or missing books in series), or looking up the book on Amazon to read reviews on it.

Reading about the lovely "plugin architecture" I thought I would look into dabbling myself with it. I've "had a go" with trial & error but stumped I think with the wrapper class.

Has anyone successfully attempted this and if so could they share their code or experiences? Is there an equivalent of the "HelloWorld" plugin example for an interface action? I have a bunch of questions but a simple example would solve most of them I am sure.

This is what I have so far (simplified) - all classes in the same file:

Filename: foo_plugin.py,
Zipped into: foo_plugin.zip

import webbrowser

from calibre.customize import InterfaceActionBase
from calibre.gui2.actions import InterfaceAction
from calibre.gui2 import error_dialog

class ActionFoo(InterfaceActionBase):
    name = 'Foo'
    actual_plugin = 'FooAction'

class FooAction(InterfaceAction)

   name = ... etc with implementation

I had a few compile errors which I corrected, so I know the UI is now processing the foo_plugin.py file. Now there are no more errors but the plugin doesn't appear in the list or context menu. I suspect (one of) the problems is setting the value of actual_plugin. What value do I use when what I want to point to is in the same file? Am I missing something else as well? Also do I need to restart Calibre after installing to get it to appear?

Many thanks for help - first time at trying to write Python (.NET developer in the day job) so please be gentle

[kiwidude]

Ok, so I got one step further... I changed the code line for actual_plugin to have this value:

actual_plugin = 'calibre.gui2.actions.foo_plugin:FooAction'

This got my plugin to appear on the preferences dialog. However my context menu action doesn't appear. So I restarted Calibre (in case the menus are built at startup)... no luck and also the plugin is no longer listed in the Preferences dialog until I manually add it again.

If I list the plugins using calibre-customize it appears in the list, and I can see the zip file in the Roaming\calibre\plugins folder.

There seems to be some trick I am missing though to (a) get the plugin to appear back in the Preferences dialog after a restart, and (b) to get my menu items to actually appear (which may or may not be related to the implementation).

I have tried copying directly an implementation from show_book_details.py into my FooAction class to prove it is not part of the code and it makes no difference? That version is now attached.

Apologies for being a pain for asking.

[kovidgoyal]

The InterfaceAction plugins aren't really designed to be loaded from zip files (this is because they depend on Qt, unlike most other plugin classes) that's why you have to jump through the "actual_plugin" hoops.

I'd suggest running calibre from source and implementing your plugin there. It's fairly trivial to run calibre from source, instructions in the user manual.

[kiwidude]

That's a shame.

Is there a way of getting just the 0.7.26 version of the code for me to run, rather than the trunk? I'm running on Windows btw.

[kovidgoyal]

you can check out any revision you like from the source code.

[kiwidude]

Ummm... could you please be so kind as to give me a command line I could type for that? Not familiar with Bazaar or your repo structure sorry. I followed the instructions on the web page previously with
bzr branch lp:calibre

[kovidgoyal]

do

bzr revert -r revision_number

in your checkout, get the revision_number you want with

bzr log

[kiwidude]

Brilliant, thank you very much.

Ok, time for the really dumb question.
I've setup my environment variable, got the right revision of code I want...

But how do I actually run from source?

[itimpi]

Originally Posted by kiwidude

But how do I actually run from source?

Once you have downloaded the source and set up the Environment variable correctly to specify its location, just start up Calibre in the normal way and the source is automatically picked up. Source files automatically supersede binary files if they are newer.

[kiwidude]

Originally Posted by itimpi

Once you have downloaded the source and set up the Environment variable correctly to specify its location, just start up Calibre in the normal way and the source is automatically picked up. Source files automatically supersede binary files if they are newer.

Thanks mate. Well I have tried that, but it seems that changes I make are not being picked up when it runs? For instance just to prove it wasn't my new interface action, I tried changing the implementation code of tweak_epub.py but it seems to be running the compiled version?

At a command prompt when I type echo %CALIBRE_DEVELOP_FROM% it gives me back "c:\calibre" which is my root directory that has a src subdirectory with the changes in.

Something else obvious I am doing wrong?

[kovidgoyal]

You need to use c:\calibre\src

[kiwidude]

That would be the obvious thing Thanks kovid, running from source now.

[kiwidude]

Ok, got my action plugged into the menu. For anyone else's info who follows in my footsteps (and for Kovid to tell me if I did wrong) I did these steps:

1. Add your implementation class file into \src\calibre\gui2\actions

2. Edit src\calibre\customize\builtins.py to add the wrapper class implementation pointing to the above. Also add the name of that wrapper class to the 'plugins' variable array.

3. Edit src\calibre\gui2\__init__.py to ensure the context menu item actually physically appears in the 'action-layout-context-menu' array in appropriate place you want it to appear in the menu. The value you add here matches that of the 'name' property of the implementation class.

4. Begin many iterations of opening and closing calibre as you learn how to write code in Python

I've got a working (crude) implementation though of launching the webpage for fantasticfiction for the current selected author which was the first goal so stoked with that. Thanks for the help to get up and running!

[kovidgoyal]

Note that 3 is not strictly necessary, you can control what appears in the context menus and toolbars via Preferences->Toolbars

[kiwidude]

Ahhh yes, did not know that, thanks Kovid.

Job done... loving it! A shame I have to run from source (would be nicer as a zip plugin) but that I was able to add this so easily is a tribute to the quality of the existing codebase - great job Kovid and whoever else wrote Calibre.

I've attached a screenshot for anyone interested in what I ended up with. The sub-menu options are currently defined in an array. You specify the name, icon and a url with tokens like {author}, {title} or {isbn} to be substituted by the plugin based on the selected row. You can also do empty rows for separators.

If there was any interest by others in this becoming a patch to add to the trunk whoever wants to do it is welcome to the code, let me know. It would be nice to make the array able to be specified via the tweaks file or some other configuration, so users can manipulate the menu with other websites etc. I've not written this to be "bulletproof" being a Python newbie but it does the job for me.