BookmakerPlugin

Provides a UI and an API for other extensions that support the definition and maintenance of a specific topic ordering

The Bookmaker plugin provides support for interactive capture and sorting of ordered lists of topics.

The lists are held in topics, and may be manually edited, or can be manipulated through the interface.

This plugin also provides an API for access to the lists, as a service to other extensions such as the PublishPlugin and TocPlugin.

The interactive features of this plugin require the JQueryPlugin, and requires Javascript to be enabled in the user's browser. The API can still be used without the interactive features enabled, however.

Usage

Enable the plugin, and revisit this page to enable the bookmaker interface, capturing a book in ExampleBook.

Once you have opened the bookmaker interface it will remain open until you close it again. The bookmaker interface comprises a horizontal bar across the top of the page that carries buttons which support selecting your book, and adding and removing topics. More complex interactions are enabled when you expand the bar to show the full interface. This then allows you to interactively sort the topic list, and modify the indentation level of entries.

You can copy-paste the following macro into your own topics to create a button that starts Bookmaker (change Sandbox.ExampleBookto the topic name of your choice):

%BUTTON{"Start Bookmaker" class="bookmaker_button" href="%SCRIPTURL{view}%/%WEB%/%TOPIC%?open_bookmaker=Sandbox.ExampleBook"}%

Format of a book topic

At their simplest, book topics contain a list of topics, which can optionally be indented. Topics can be specified using a variety of formats, best illustrated by an example:

   * Mybooks.ChapterOne
   * ChapterTwo
      1 [[Chapter2.SectionOne]]
   * [[Chapter three][Chapter 3]]
      * [[Chapter3.sad story][Sad Story]]

If topic names do not include a web specification, then the topics are assumed to be in the same web as the book topic.

A book topic may contain macros, but as soon as it is edited via the Bookmaker interface (e.g. by adding or removing a topic) those macros will be expanded, and the topic will be saved as a simple list of topic names.

Book topics may optionally represent hierarchy, through the use of indentation levels in the list.

An API is provided to allow other extensions to access the book. Note that the API should always be used to access book topics, as their format may change radically in the future. When the plugin is installed, the API will be documented here.

Macros

Macro	Description	Current value (if the bookmaker is enabled)
%BOOKMAKER_IN_OPEN_BOOK%	Used in %IF statements to test if the current topic is included in the currently open book. Always false if no book is open.	%BOOKMAKER_IN_OPEN_BOOK%
%BOOKMAKER_BOOK%	Name of the open book	%BOOKMAKER_BOOK%
%BOOKLIST%	Get a formatted list of the pages in the currently open book (or another book if a parameter is given, e.g. %BOOKLIST{"Otherweb.Bookname"}%.	%BOOKLIST%

Note that BOOKLIST will accept a book name with no web specification; in this case, the BOOKMAKER_BOOKWEB preference will be referred to for the name of a web or, if it is not set, the Sandbox web will be used.

BOOKLIST also accepts format and separator parameters. These are expanded to create each entry in the list, and the separator used in the list. For example, to use BOOKLISTto pull in the entire contents of the topics in the book, you could use:

%BOOKLIST{format="$percntINCLUDE{"$web.$topic"}$percnt" separator="$n()"}%

As well as $web and $topic, the index depth of the topic can be obtained from $level. All standard formatting tokens are also expanded.

Installation Instructions

You do not need to install anything in the browser to use this extension. The following instructions are for the administrator who installs the extension on the server.

Open configure, and open the "Extensions" section. Use "Find More Extensions" to get a list of available extensions. Select "Install".

If you have any problems, or if the extension isn't available in configure, then you can still install manually from the command-line. See http://foswiki.org/Support/ManuallyInstallingExtensions for more help.

Info

Many thanks to the following sponsors for supporting this work:

• DENX Software Engineering http://www.denx.de

Author(s):	Crawford Currie http://c-dot.co.uk
Copyright:	© 2011 Foswiki Contributors
License:	GPL (Gnu General Public License)
Release:	1.1.0
Version:	15213 (2012-07-26)
Change History:
1.1.0 (26 Jul 2012)	Foswiki:Tasks/Item12013: Add support for formatting the BOOKLIST
1.0.3 (25 May 2011)	Foswiki:Tasks/Item10786: Fix multiple BOOKLIST calls in same topic
1.0.2 (20 Apr 2011)	Moving the ExampleBook into the Sandbox web.
1.0.1 (15 Apr 2011)	Minor correction on file permissions.
1.0.0 (28 Mar 2011)	Initial version
Dependencies:	Name Version Description JSON >=0 Required, available from CPAN Foswiki::Plugins::JQueryPlugin >=0 Required, available from Foswiki.org Foswiki::Contrib::JSTreeContrib >=0 Required, JQuery plugin
Home page:	http://foswiki.org/bin/view/Extensions/BookmakerPlugin
Support:	http://foswiki.org/bin/view/Support/BookmakerPlugin