opubWriter

For two weeks I have been grappling manfully with treeview data bindings and nested repeater event bubbles to create a new look for opubWriter. I realised that I was trying to do too much on the ‘Content’ screen – edit documents, add and remove documents, and rearrange the table of contents – so I have split this functionality to create two new screens.

The Editor screen simply shows the table of contents as a treeview and the wysiwyg editing area, along with a Save button. A significant improvement is that opubWriter can now create and handle book structures of arbitrary depth – hence the nested repeater event bubbles.

New Editor screen

This following screenshot shows four levels. To display a document, you click on its name in the treeview.

The plus and minus icons can be used to expand and collapse the divisions of the book so you can bring the part you’re working on conveniently into view.

The screenshot also shows that the editing area can be resized to match your preference.

One feature that’s slightly less attractive than before is that I’ve removed the ‘save’ option from the editing area and replaced it with a ‘Save’ button. I couldn’t get the tinyMCE plugin to work reliably, and there are risks that it will behave differently in different browsers. I notice that WordPress and Blogger both have separate Save buttons, so opubWriter is in good company in that respect.

The next screenshot shows the Navigation tab of the Organisation screen.

Organisation/Navigation screen

On this screen you also see the hierarchical structure of the book, but this time you don’t expand and collapse the view.

To the left of each content document  you will see a group of icons each of which represents an action you can perform. The icons and their meanings are listed in the table below.

	Download the content document.
	Delete the content document.
	Move the content document up within its level.
	Move the content document down within its level
	Save the title of the content document.

The download option allows you to save a single content document, which you might want to do in order to upload it into another book. This post show you how to do that below. This action keeps the document in the current publication and doesn’t affect it in any way.

The delete option allows you to remove a content document completely from the publication. Obviously, you must think carefully before taking this action. For instance, you might want to take a copy of the .epub file or download the content document before you delete it.

The actions to move a content document up and down in the reading order act only at the current level of the document. Where a content document is the first one at its level e.g. the Introduction to Part 1 in the screenshot, the ‘move up’ icon is not shown. Conversely, a document which is the last at its level does not have a ‘move down’ icon. If you really must promote or demote a content document to a different level, the approach is to save it first by downloading it and then uploading it to its new position. Again, uploading a content document is explained below.

The ‘save’ action refers to the text of the table of contents entry. You can use this option to change the text displayed in the table of contents. Technically, this will be saved in the NCX file of the epub in the <navLabel><text> element.

The second tab to mention on the Organisation screen is the Content tab. This provides the ability to add new content at any position within an epub publication. The new content document can either be created from scratch using details you provide or it can be uploaded from an existing content document on your computer system.

The screenshot below shows the Organisation/Content screen.

Organisation/Content screen

To create a new content document, you enter three pieces of information:

1. The entry to appear in the table of contents.
2. A unique filename for the document.
3. An optional document heading.

 To upload an existing content document, you use the Browse button to locate the file on your computer system; then you enter the following two pieces of information:

Having selected the source of the new content, you then select where it will go. There is a dropdown list that lets you specify a relative position which contains the following options:

1. The entry to appear in the table of contents.
2. A unique filename for the document.

The document relative to which the new content is placed is selected in the next dropdown list. The entries in this list show the full path to each document. This allows you to distinguish between, for instance, “PART ONE/Chapter 5″ and “PART TWO/Chapter 5″.

The screenshot shows the Content screen completed and ready for the Create button to be clicked.

Notice there’s also a tab on the Organisation screen called ‘Spine’. At some point this will be developed to allow control over the reading sequence defined by the spine and the ability to change the ‘linear’ attribute of a spine item which identifies content as primary or  auxiliary.

This morning I added two new articles to the opubWriter User Guide.

The first is concerned with adding images to your epub books, both uploading them to be included in the manifest and then inserting them into the content documents where they are relevant. There are 4 image formats you can use (gif, jpeg, png, and svg). In the current release of opubWriter there’s a limit of 100Kbytes for any one image file.

The second User Guide article covers the subject of CSS styling – how to add, modify, and apply CSS stylesheets to your content documents. The Styles screen is where you upload new stylesheets and edit their style rules. It’s also here you can delete a stylesheet – provided it’s not referenced anywhere in your book. You use the Style Usage screen to control which stylesheets are applied to which documents. The article shows how a content document can have more than one stylesheet and also how you can get close control of styling by creating your style classes which appear in a dropdown list in the editing window. Don’t assume that your readers will like your style; they may want to read taupe text on a puce background, I say ‘let them’.

Today I implemented the following changes to opubWriter:

1. Pass multiple CSS stylesheets to TinyMCE initialisation. Now that the ‘Style Usage’ form is available, the user can assign more than one stylesheet to a content document. The TinyMCE editor has the ability to work with multiple stylesheets; what was needed to TinyMCE to apply a document’s stylesheets was to find all the ‘text/css’ link elements in the selected document and set the content_css property of TinyMCE during initialisation to a comma-separated list of absolute URLs to these stylesheets.
2. Disallow stylesheet deletion if it’s in use. On the Styles form the user has the ability to upload, modify, and delete stylesheets. An epub would fail validation if a referenced item were not in the manifest. When a user selects a stylesheet for deletion, a check is now made across all content documents (media-type = ‘application/xhtml+xml’) in the manifest for a element that refers to the selected stylesheet. If any reference is found, a message is displayed and the stylesheet is not deleted.
3. New Epub form now has a dropdown list of languages. When a user creates a new epub book using the New button on the Library form, a screen is displayed which captures some intial metadata. One of the mandatory items captured is the language code identifying the language in which the intellectual content is written. The code must conform to RFC 3066. In order to save the user the effort of looking up the code for their selected language, the New Epub form now offers a dropdown list of language names, defaulted to English, and the list delivers the language code for the selected language to the application.
4. More validation. Characters that are not allowed in filenames and XML documents are detected when the user types into the Contents Entry field when adding a content document to a publication. A suitable error message is displayed. On the New Epub form, the user must provide a title and an identifier which are mandatory metadata items in epub.

opubWriter User Guide

I have started a User Guide for opubWriter which is available as Pages within this blog. The articles to date (shown to the right of this screen) are:

• Register and Login
• Managing Your Library
• Editing Epub Contents

Articles in the pipeline are:

• Managing Metadata
• Managing Styles
• Document Organisation