Plugin: Bookmarks

Name	Bookmarks
Files	bookmarks.swf bookmarks.asul
Related plugins	Anchors

The bookmarks plugin allows adding bookmarks (or tabs) to your book, which will be placed according to where their corresponding page is in the book's edge. When clicked, the book will go to the page the bookmark belongs to.

Settings

bookmarksalongedge

• Type: Boolean
• Default: true

This determines whether the position should be adjusted accordingly to the thickness and curvature of the book's edge. If this is set to false, the bookmarks will not be indented accordingly to the book's edge, but like they normally would be in the containing flow element.

When set to false, you should also adjust the bookmarks.asul file accordingly, more specifically look for the two occurrences of the wrapfactor attribute of the vflows named "left" and "right" and remove them, To allow bookmarks to spread out over multiple columns.

This can be useful when using a lot of plugins, so that most of them are covered up by the next five or so bookmarks, but more should be visible at once.

Tags

This plugin uses an extra child node of the book node to define the bookmarks available per default.

The main node name is bookmarks. This node can contain any number of child nodes named bookmark, which must have the two attributes named title and page. This is the displayed title of the bookmark, and the page to jump to when the bookmark is clicked. Note that the page may also be an anchor, as long as the anchors plugin is loaded.

Optionally, an attribute named color may be given. This is an integer defining the color in which to tint the bookmark.

The bookmark nodes must contain no more nodes themselves.

Localization

Bookmarks may also be localized. To do this:

• create localization files
• set bookmarks@langfiles attribute
• set bookmarks' titles accordingly

Localization files

Localized titles for bookmarks are stored inside XML files alike to those used for localizing the GUI. They basically have this format:

<lang id="ID">
    <langstring name="LNG_ENTRY">Localized string</langstring>
    ...
</lang>

Where there can be any number of langstring entries. The points to look out for here are to

• make sure the lang@id is correct. This must be the same shortcut as used for the language in the book@langs attribute.
• use unique values in the langstring@name attributes.

Write the titles of all bookmarks to be used in this file.

The bookmarks@langfiles attribute

This attribute can be used to tell the engine where to find the localization files for the bookmarks. What this attribute basically must contain is a path to the localization files created in the previous step. Because you'll obviously have more than on file (one for each language) there is a "variable" available, that will be replaced with the id of the language that the engine tries to load: $1.

So the value might look like this:

bookmarks/$1.xml

If the languages English (en), German (de) and French (fr) are set, the engine would try to load the files bookmarks/en.xml, bookmarks/de.xml and bookmarks/fr.xml.

Using the localized strings as titles

Finally, you'll still need to tell your bookmark entries to use the localized strings. This is done the same way ASUL localization works: setting the title to localize(LNG_ENTRY), where LNG_ENTRY corresponds to one of the langstring@name attributes' values.

Example

<book plugins="bookmarks">
    <bookmarks>
        <bookmark title="Cover" page="0" color="#33FF44"/>
        <bookmark title="Chapter II" page="download" color="#CC6666"/>
        <bookmark title="Hello There" page="30" color="#3366EE"/>
        <bookmark title="&lt;i&gt;Italic&lt;/i&gt;" page="55" color="#DD3399"/>
        <bookmark title="Epilogue" page="epilogue" color="#3366EE"/>
        <bookmark title="Finally" page="last" color="#FFDD33"/>
        <!-- and so on... -->
    </bookmarks>
    <chapter>
        <!-- Actual book content -->
    </chapter>
</book>

Example (Localization)

Langfiles

In a file named en.xml:

<lang id="en">
    <langstring name="BOOKMARK_ONE">The first bookmark</langstring>
    <langstring name="BOOKMARK_TWO">This is English</langstring>
</lang>

In a file named de.xml:

<lang id="de">
    <langstring name="BOOKMARK_ONE">Das erste Lesezeichen</langstring>
    <langstring name="BOOKMARK_TWO">Dies ist Deutsch</langstring>
</lang>

Book definition

In the megazine.mz3 file:

<book plugins="bookmarks">
    <bookmarks langfiles="$1.xml">
        <bookmark title="localize(BOOKMARK_ONE)" page="0" color="#33FF44"/>
        <bookmark title="localize(BOOKMARK_TWO)" page="20" color="#CC6666"/>
    </bookmarks>
    <chapter>
        <!-- Actual book content -->
    </chapter>
</book>