Difference between revisions of "Manual:Extension/BookshelfUI"

[quality revision][quality revision]
m
(Changed categories.)

About books[edit | edit source]

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:

Screenshot: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[edit | edit source]

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[edit | edit source]

To create a book:

  1. Go to Global actions > Book manager:
    Screenshot:create book
  2. Select the Create (+) button.
  3. 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.
  4. Click Done. You now have created an empty book.

You can take the following actions on a book:

Screenshot: Bookmanager actions
  • 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[edit | edit source]

After you have created the book, click on the name of the book. This opens the Book Editor:

Screenshot: 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:

Screenshot: save book navigation

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:

Screenshot: bookshelf tag

Deleting a book[edit | edit source]

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:

Screenshot: delete book menu

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[edit | edit source]

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

Screenshot: Duplicate book

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

{{DISPLAYTITLE:Books}}
        
        __TOC__
        

        ==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:
        
        [[File:book-nav.png|alt=Screenshot:Book navigation|center|256x256px]]
        

        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==
        
        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:'''
        

        #'''Go to''' ''Global actions > Book manager'':<br />[[File:Manual:create-book.png|link=https://en.wiki.bluespice.com/wiki/File:Manual:create-book.png|alt=Screenshot:create book|center|650x650px]]
        
        #'''Select''' the ''Create (+)'' button.
        
        #'''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''.
        
        #'''Click''' ''Done''. You now have created an empty book.
        

        You can take the following actions on a book:
        

        [[File:Manual:book-manager-actions.png|alt=Screenshot: Bookmanager actions|center|650x650px]]
        

        *[[Manual:Extension/BookshelfUI#Book editor|Edit]] (1): Links to the Book editor where you can edit the book contents and metadata.
        
        *[[Manual:Extension/BookshelfUI#Deleting a book|Delete]] (2): Deletes the book without deleting the wiki pages.
        
        *[[Manual:Extension/BookshelfUI#Duplicating a book|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==
        
        After you have created the book, click on the name of the book. This opens the ''Book Editor'':
        

        [[File:Manual:book-editor.png|alt=Screenshot: book editor|center|650x650px]]
        

        *'''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, [[Manual:Extension/ExtendedSearch#Export search|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:
        

        [[File:Manual:book-createnav.png|alt=Screenshot: save book navigation|center|650x650px]]
        

        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:
        

        [[File:Manual:bookshelf-tag.png|alt=Screenshot: bookshelf tag|center|650x650px]]
        

        ==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:
        
        [[File:Manual:delete-book.png|alt=Screenshot: delete book menu|center|300x300px]]
        
        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:
        

        [[File:Manual:duplicate-book.png|alt=Screenshot: Duplicate book|center|400x400px]]
        

        '''To duplicate a book:'''
        

        #'''Enter''' a ''target name'': The default vlaue is the book name with the suffix ''(copy)''. Change this to create a different book title.
        
        #'''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 <code><nowiki><bs:bookshelf src="Book:Employee Manual (Copy)" /></nowiki></code>.
        
        **'''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.<br />
        
        {{Box Links-en|Topic1=[[Reference:BookshelfUI]]}}
            
            [[Category:Organization]]
            
            [[Category:Content]]
Line 82: Line 82:
 
**'''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.<br />
 
**'''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.<br />
 
{{Box Links-en|Topic1=[[Reference:BookshelfUI]]}}
 
{{Box Links-en|Topic1=[[Reference:BookshelfUI]]}}
 +
[[Category:Organization]]
 +
[[Category:Content]]

Attachments

Discussions