Plugin Development

[Vroni]

Originally Posted by KevinH

A book path (...) is a unique relative path from the ebook root to a specific file.

If its from the root isnt it then an absolute path?

[KevinH]

In a way, as it is a partial path. So it is relative to the ebook folder path itself. The path to the ebook root folder is not part of it. Just the path within the ebook.

[KevinH]

FYI,
Updated the Sigil Plugin Framework epub to rev12 and it now includes and documents the extensions for the upcomig Sigil-0.9.991 (pre 1.0) alpha release.

Plugin developers should be able to use Sigil-0.9.991 to test and debug their plugins under the new interface, especially with non-standard epub layouts.

[KevinH]

Hi All,

For what it is worth, my plugins (FolderIn, FolderOut, ePub3-itizer, Access-Aide) all should now support the new Sigil-1.0 plugin interface.

I would be happy to help anyone else convert their plugins.

Just ask here.

[CalibUser]

Originally Posted by KevinH

Under Sigil 1.0 and later, the original epub structure will be preserved meaning that file names like "content.opf" could be named "package.opf", and be placed almost anyplace inside the epub. This is true for almost all files.

Would it be possible for somebody to provide a 'non-standard' Sigil-structured epub with at least two xhtml sections so that I can test my plugins on it? I have always used the standard structure that Sigil sets up so I am not familiar with the other types of structures that Sigil 0.9.991 can handle.

Under Sigil version 0.9.991 I renamed content.opf to package.opf and toc.ncx to toc1.ncx to make a non-standard epub but my pluging - FootnoteManipulator plugin for epub 2.0 publications - that was built for previous versions of Sigil still runs on this structure with Sigil 0.9.991. I do not know what else to change in the structure to fully test my plugin.

Thanks

[KevinH]

I will dig one up and post it for you today. In the meantime, you can select any file or group of files in the BookBrowser and use the context menu to run Move on them and set a new destination. So move one of your *.xhtml files into a new lication, then move a second someplace else.

[CalibUser]

@KevinH:

Originally Posted by KevinH

..In the meantime, you can select any file or group of files in the BookBrowser and use the context menu to run Move on them and set a new destination. So move one of your *.xhtml files into a new location, then move a second someplace else.

Thanks for this. I experimented with your suggestion and now see that other folders can be created in the epub file by moving them; I moved a file to TestFolder and found

print(bk.group_to_folders("Text"))

returns

['OEBPS/Text', 'TestFolder']

With the older version of Sigil I could iterate through all the xhtml files using:

for (id, href) in bk.text_iter()

so I tried running the following code in Sigil 0.9.991

 	for (id, href) in bk.text_iter():
		print("id= ", id)
		print("href= ", href)

and this returned:

id=  sec_01.xhtml
href=  Text/sec_01.xhtml
id=  Section0001.xhtml
href=  ../TestFolder/Section0001.xhtml
id=  Section0002.xhtml
href=  Text/Section0002.xhtml

showing that the same code can still be used to iterate through all the xhtml files.

I hope this information may be of some use to other plugin developers.

[KevinH]

Yes and the href in that case is the relative path from the OPF. If you want the path from the root folder of the epub, you can now use bk.id_to_bookpath(id) on the id that iterator provides to get the bookpath as well.

KevinH

[KevinH]

Here is a simple non-standard test epub that DiapDealer gave to me to test things with.

It is laid out as a simple compendium style epub might be but the files are pretty much empty.

Hope this helps,

KevinH

[DiapDealer]

Is there any kind of simple algorithm that could be used to calculate a relative href between two files?

If one is creating a new xhtml file, I'm trying to think of a consistent way to come up with the proper src to a particular image file (already in the epub) based on the known factors.

Say I've created an xhtml file with my plugin whose href (relative to the opf file) is something like:

"book1/xhtml/newfile.xhtml"

and I have an image file with an href (relative to the opf file) of:

book1/images/myimage,jpg

I'm looking for some sort of reusable, failsafe function that could take two hrefs (from the various iter functions) as parameters (source and target) and give me a relative href from the first parameter's file to the second parameter's file.

Consider the two previously mentioned sample hrefs:

getRelativeHref('book1/xhtml/newfile.xhtml', 'book1/images/myimage,jpg')

needs to be able to return a value of '../images/myimage.jpg' so it can be used in an img tag in newfile.xhtml. Is that possible to do with any two files' hrefs in any epub structured in any way? Or will I need to build a relative href from the root of the epub up to be able to make it work under any conditions?

Or am I overthinking this?--which is entirely possible!

[KevinH]

Yes, the new interface offers just such a function:


# returns the href relative path from source bookpath to the target bookpath
#
def get_relativepath(self, from_bookpath, to_bookpath)

So bk.get_relativepath(from_bookpath, to_bookpath)

will nicely create for you the href to reference the to_bookpath file from the "from_bookpath" file. You still need to deal with any fragments afterwards and of course url encode it before writing it to a file.

There are examples of this and routines to help in hrefutils.py as well as that is what the plugin wrapper itself uses.

If you want sample code that builds links to an image file from an html file that is backwards compatible with older versions of Sigil check out ePub3-itizer, and Access-Aide for many examples.

[DiapDealer]

Well looky there. If only I knew how to read, I could have answered my own question, huh?

Thanks!

[CalibUser]

Originally Posted by KevinH

Here is a simple non-standard test epub that DiapDealer gave to me to test things with.

It is laid out as a simple compendium style epub might be but the files are pretty much empty.

Hope this helps,

KevinH

Thanks for this.

[Vroni]

If i understand this correct to save a file to the epub you need something like a complete "file selection" browser as the only folder you can trust to be present by default is the root folder of the epub.

Any best practices or is something availöable in the API to make use of?

[Doitsu]

Originally Posted by Vroni

If i understand this correct to save a file to the epub you need something like a complete "file selection" browser as the only folder you can trust to be present by default is the root folder of the epub.

AFAIK, bk.addfile() will work with both standard and non-standard epub files. You'll only need to worry about the actual folder structure, if you want to create a plugin that allows the user to save a file to an arbitrary folder.

What kind of functionality are you trying to implement?