Manual:Extension/BookshelfUI

1. REDIRECT Manual:Extension/BlueSpiceBookshelf

What is BookshelfUI?

About books

With BlueSpice Pro, you can assemble individual wiki pages into a book. When you access a page that is part of a book, the main navigation is replaced by the book navigation:

In book mode, you can read through a collection of pages in a linear fashion by moving through the book navigation. This is useful if you have lots of related pages that should be read in a particular order. And it makes it easy to write documentation and to comply with your documentation standards.

Characteristics of books

BookshelfUI provides a graphical interface for creating, editing and managing books. It consists of a book editor, a book management and an integrated navigation.

Where to find BookshelfUI?

Before you create a book from your wiki pages, consider the following main characteristics of books:

• Each wiki page can only be part of one book
• When a page is part of a book and a user navigates to it, it always jumps directly to the book navigation.
• Books can easily be converted into PDF format

Therefore, you want to create wiki pages that are exclusively part of a book if you use the book function of your wiki.

Creating a book

To create a book:

1. Go to Global actions

, BookManager

1. > Book manager:
   

Create Article/Page in the book

1. 

Create new book:

Give name to the book and select book type:

Book is created:

1. Select the Create (+) button.
2. Enter a Book title and the Type of the book:
   • General books: Visible to all users. It should have a book navigation.
   • Own books: Books only visible to me. Please note that pages in your own books can also only be in one book. If another user includes the same page in their own book, the page will "jump" to the book navigation of the user who last included the page in their book and saved it with the optional book navigation. It is therefore important to include only your own pages in your own books, unless you do not create the optional book navigation when you save your book. A good way of making your own books is by using subpages from your own user profile page in the namespace User.
3. Click Done. You now have created an empty book.

You can take the following actions on a book:

• Edit (1): Links to the Book editor where you can edit the book contents and metadata.
• Delete (2): Deletes the book without deleting the wiki pages.
• Duplicate (3): Duplicates this book, including all the pages of the book.
• Export (4): Exports the wiki pages in this book to PDF.
• Assign (5): Assigns the book to designated users.

Editing a book

Too create article in After you have created the book, click Add and specified the title:

or Mass add pages - select set of pages to be added (read more in Mass add section)

All changes will only become active after clicking on the "Save" button.

Right click to manage:

Add next Article/Page

To add next page, mark book and then Add button.

To add next page in the already existing page mark, that specific page where you want to add next one.

Or add a page that already exists:

Mass add pages

Pages can be added in a batch in addition to adding single page. There are different sources from which pages can be added:

• Subpages - all subpages of a given page.
• Category - all pages contained in the given category.
• Page collection - add pages from previously created Page collection.

Other extensions can define their own sources, like all pages with certain semantic property, so the list of sources may show adittional sources.

Books management

• In the book management books can be created, copied and deleted.
• When creating a title must be specified.
• The already existing books are displayed in a list.

Book Editor

• The book editor displays the contents of a book in a hierarchical folder structure.
• Book chapters are added in the form of wiki articles. A selection dialog opens for this purpose.
• Book chapters can be renamed.
• Book chapters can be dragged into the desired order by Drag'n'Drop.
• Book chapters can be deleted via an icon. It is not the article itself deleted, but only taken from the book.
• Metadata can be inserted via a dialog.
• All changes will only become active after clicking on the "Save" button.
• When saving, the bookshelf tags in the articles are copied (if desired).
• It is possible to mark individual chapters for export.
• If the user clicks on "Export selection", he receives a document in the selected format. At least one export extension must be activated for this.

Integrated navigation

• The navigation is a separate tab in the sidebar.
• It consists of two areas.
  • Available Books shows a list of all the books stored in the system.
  • Chapter shows the chapter navigation of the currently selected book.
• The two areas are represented by an accordion grid. This also means that only one area is open at a time.
• The ad will be preserved the same way the user selected it when the page was changed.

See also

Our reference page. on the name of the book. This opens the Book Editor:

• Book Manager (1): Link to the main Book manager page.
• Show source wikipage (2): Opens the book navigation page in view mode.
• Edit source wikipage (3): Opens the book navigation page in edit mode.
• Add page (4): Button for adding a page.
• Mass-add pages (5): Button for adding a set of pages (by category, subpages of a page, page collection, or semantic property).Remove page (6): Removes the selected pages.
• Manage metadata (7): Add or remove metadata.
• Export selection (8): Exports the selected pages to a PDF file.
• Book contents (9): Shows all pages in the book hierarchy Pages can be arranged by drag-and-drop. A multi-level organization is possible.

After adding pages to your book, you save the changes. When you click on Save, you have the option to also create the book navigation. If you want to add a book navigation tag to each wiki page, click Save and add book navigation to each wikipage instead:

When you add the book navigation to a wiki page, the corresponding bookshelf tag is added in its source code. In addition the page title now always includes the numbering from the book navigation:

Deleting a book

When you delete a book, you only remove the book information from Book manager. The wiki pages in the book, however, are not deleted. Before you delete the book, you are informed in a pop-up menu that the bookshelf tag is not automatically removed from the pages:

The bookshelf tags have no effect on the wiki pages after deleting the book. If you want to remove them manually, you can go to the page Special:ReplaceText and do a find and replace.

Duplicating a book

You can create an entire copy of the book by duplicating it:

To duplicate a book:

1. Enter a target name: The default vlaue is the book name with the suffix (copy). Change this to create a different book title.
2. Select a namespace: Choose a namespace that is different from the original namespace.

If you are not careful, you might experience some unintended consequences. By creating a new book, you also create copies of all the wiki pages in the original book. Since a namespace cannot contain the same page twice, you have to copy the files to a different namespace.

About the duplicated files:

• Book file: A new page in the namespace book. If you don't enter a new title, the book will be created with the same title and the suffix (Copy). E.g. Employee Manual (Copy). This file includes a copy of the structure of your original book with the corresponding links to the duplicated pages in the new copy.
• Book pages: All pages contained in the original book are duplicated. The following scenarios are possible:
  • Same namespace: If you duplicate a book in the same namespace, no actual duplicates of the actual wiki are created. Instead, the bookshelf tag is updated to point to the copy of the book. For example, if your original book contains the page HR:Quality assurance (the book is in the namespace HR), the Quality assurance page now contains the bookshelf tag <bs:bookshelf src="Book:Employee Manual (Copy)" />.
  • Different namespace: If you create the book copy in a different namespace, the bookshelf tag in the original files remains unchanged. The new pages in the different namespace are created with a bookshelf tag for the new book copy. This is most likely the scenario you want.
    

Related info

• Reference:BookshelfUI