Plugin Development

[KevinH]

Given that order of attributes in pure xml is variable (not order specific) and given the line oriented structure of the manifest and spine, and even metadata, character offsets into the line are basically meaningless.

But that is of course your call.

KevinH

Originally Posted by BeckyEbook

@DiapDealer. Thank you. I will try it.


A version with line offsets only was not enough for me. I wanted better

[KevinH]

BTW:

I just committed a first shot at allowing custom icons for plugin quicklaunch toolbar buttons to master.

I have not tested it much but I wanted people to try it out and see if it does the trick.

To use a custom icon for your plugin on the toolbar:

1. pull from master and rebuild

2. simply create a 48x48 png file called "plugin.png" and put it at the root of your plugin folder right beside plugin.xml and plugin.py.

3. Make sure your plugin is set to be one of the 5 allowed quick-launched plugins.

It should hopefully just work. Comments and improvements welcome.

[BeckyEbook]

It works OK for me.

Although the icons for plugins selected in "Manage plugins" appear only after restarting Sigil. Can you force the refresh "Tools" toolbar?

[KevinH]

Hi All,

Based on the discussion here and in the FolderIn/FolderOut thread, I have just committed to master support for two new plugin features available in edit, output, and validation plugins:

bk.get_epub_is_modified()
   returns boolean True if the epub inside Sigil has been modified 
   but not yet saved to disk

bk.get_epub_filepath()
   returns a string of the filepath for the epub currently open in Sigil 
   or the null string "" if the current epub is unsaved/untitled

Here is snippet of code you can add to your current plugin.py to test these features available in any build of Sigil from current master

   # status of epub inside Sigil and its current path
    if bk.launcher_version() >= 20180122:
        print("\nExercising: get_epub_is_modified and get_epub_filepath")
        print("epub inside Sigil is Modified: ", bk.get_epub_is_modified())
        print("filepath of epub open inside Sigil: ", bk.get_epub_filepath())

These new features will appear in the next release of Sigil.

[KevinH]

Yes, this should now be fixed in master as of 30 seconds ago.

Thanks!

Originally Posted by BeckyEbook

It works OK for me.

Although the icons for plugins selected in "Manage plugins" appear only after restarting Sigil. Can you force the refresh "Tools" toolbar?

[slowsmile]

@Becky...

Again me: Validate OPF and offset.
I found the issue that bothered me.

bk.get_opf() -- is not perfect.

Why?
Result of bk.get_opf() is not current state of file .opf. This is state "what will the .opf file look like after saving" + missing two spaces before <metadata and </metadata> + missing four spaces before each <dc:… and <meta ….

I'm not sure whether I've got your problem right but, as far as I'm concerned, what really matters when you use the bk.get_opf() method is when you actually run it in your program. So if you've already changed epub files in the epub itself and then you run the get_opf() function then you will get errors because it also changes and updates epub files on the fly as someone has already said.

The way round this problem is just to create a separate work directory for all the files that your are going to change or update in the epub with your plugin code. Use the python mkdtemp() method to create the work directly. In your plugin just save all your changed files to the work dir. The very last task for your plugin should be to write all new or changed files from your work dir to your epub.

If you use a work dir and, as your last plugin task, save all changed or new files back to the epub, then it won't matter how many times you run get_opf() in your plugin because all the epub files will still be in their original state because nothing has been saved or changed yet. So doing it this way should give you correct line numbers.

I remember, somewhere in the distant past, Kevin patiently explaining all this to me in an email and enlightening me in the way the container updates all files that you've changed with your plugin after end-of-run. The container processing runs in this this order: delete files, add files(adds new files), write files(write existing files back to the epub). Appreciating the container processing order and always using a temp work dir in my plugins has stood me in good stead because that's what really helped me to understand how I could safely use the get_opf() function in my IDErrorCheck plugin without any problems.

[BeckyEbook]

Thank you very much for the comprehensive answer.
I am currently using the code:

opf_data = bk.readotherfile("OEBPS/content.opf")

For the needs of my little validator – it works well enough and I can get the exact offset in most cases.

[Maui]

Hi,

yesterday i tried to make use of my first own sigil plugin. I'm a python beginner and the only purpose of learning python is to devekol a sigil plugin. Yeserday my plugin cashed with this:

bk.readfile(id)

The reason was quite simple: someone deleteted all ttf font files an replaced them by the otf variant for any reason. But in the manifest those ttf entries were still present. So the iterator seems to read the manifest but as the file wasnt present the readfile method failed. Is there any was to capture errors like this to present a more meaningful errormessage to the user instead of getting a dump by the launcher?

M

[KevinH]

Crashed or threw an exception? Exceptions can easily be caught and handled. My real concern is that Sigil had a manifest that was wrong. That should never happen. My guess is you are being confused by manifest ids that look like file names. Please post the opf you are working on in your plugin or better yet your ePub. Old / any manifest ids can be used but the manifest should always be correct. If not there is a real bug that needs to be tracked down and fixed.

[KevinH]

Actually you should not really need to use a temp folder at all. The plugin itself only has read access to the files inside Sigil. If you try to make a change, the plugin interface code will take a copy of the file, allow you to change the copy and store it hidden away. Once your plugin is complete and returns, Sigil itself will will be given a list of changes you requested and access to the hidden changes files and it will make the changes.

Bk.get_opf should always keep the opf updated and return a correct opf behind the scene but since it is rebuilt from a parsed structure, it may not keep the exact same white space as the original opf.

Originally Posted by slowsmile

@Becky...

I'm not sure whether I've got your problem right but, as far as I'm concerned, what really matters when you use the bk.get_opf() method is when you actually run it in your program. So if you've already changed epub files in the epub itself and then you run the get_opf() function then you will get errors because it also changes and updates epub files on the fly as someone has already said.

The way round this problem is just to create a separate work directory for all the files that your are going to change or update in the epub with your plugin code. Use the python mkdtemp() method to create the work directly. In your plugin just save all your changed files to the work dir. The very last task for your plugin should be to write all new or changed files from your work dir to your epub.

If you use a work dir and, as your last plugin task, save all changed or new files back to the epub, then it won't matter how many times you run get_opf() in your plugin because all the epub files will still be in their original state because nothing has been saved or changed yet. So doing it this way should give you correct line numbers.

I remember, somewhere in the distant past, Kevin patiently explaining all this to me in an email and enlightening me in the way the container updates all files that you've changed with your plugin after end-of-run. The container processing runs in this this order: delete files, add files(adds new files), write files(write existing files back to the epub). Appreciating the container processing order and always using a temp work dir in my plugins has stood me in good stead because that's what really helped me to understand how I could safely use the get_opf() function in my IDErrorCheck plugin without any problems.

[slowsmile]

@KevinH. Thanks for explaining it so thoroughly. And it's definitely worth remembering. I also remember that when I was writing the IDErrorCheck plugin I was determined to use the bk.get_opf() method because I'd never used it before and it looked so easy. But I had to play around with it for quite a while(and read DiapDealer's Sigil manual) before I clocked and understood what it did and eventually got the opf line numbering right.

[KevinH]

Yes, playing around with the opf can be tricky. When your plugin adds and removes files, as long as it uses the plugin interface to make the changes properly, the get_opf call should always return an automatically updated opf for you. It just may not have the exact same whitespace as before.

[Maui]

Originally Posted by KevinH

Crashed or threw an exception? [...] If not there is a real bug that needs to be tracked down and fixed.

It's a collection of Novels from EA Poe and i dont think that Sigil is the root cause for the incorrect manifest. I'm pretty sure that this book was maintained manually and someone just forgot to delete the old manifest lines.

At least, i got an error saying the the file couldnt be loaded (of course, it was not present) and then a traceback to the launcher followed with some additional error messages.

I would just like to have a more user friendly error message when bk.readfile isnt able to load a file and dont know how to catch such a kind of error.

M

[Doitsu]

Originally Posted by Maui

I would just like to have a more user friendly error message when bk.readfile isnt able to load a file and dont know how to catch such a kind of error.

Check out the documentation for try & except.

[DiapDealer]

Also... a non-copyright-violating epub sample that can be used to reproduce the error would be nice. If Sigil can make use of the file in the epub without problems, then the plugin framework's bk.readfile() really shouldn't barf on it either. Perhaps there's something unforeseen we need to account for.