Difference between revisions of "Manual:Extension/BlueSpiceBookshelf"

{{DISPLAYTITLE:Bookshelf}}
        
        __TOC__
        
        
        
        
        ==What is Bookshelf?==
            
            
        The extension '''Bookshelf''' expands the BlueSpice distribution, enabling combining and collecting multiple articles wiki pages into a structured book. These books include convenient ways to navigate (by table of content or book navigation), and they can also be printed as a PDF file if needed. The PDF file includes an individual cover page, a clickable table of contents, and all attachments from the articles contained.
            
            
            
            
            
            ==Where to find Bookshelf?==
            
            [[File:Bookmaker1a.png|thumb]]
            
            [[File:Bookshelf8.png|thumb]] with chapter navigation. These books  can also be printed as a PDF file with a cover page and a clickable table of contents
            
            ==Characteristics of books==
            
            With BlueSpice Pro, you can assemble individual wiki pages into a book. In a book, 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.
        
        All the books that are available on the wiki are accessible through the left navigation menu, tab "Books" with athe book icon. Here 
            
            Books are shown all the types of books - "General books" and "Own books" by default. Clicking on one of these opens a list of all books available for that type. Clicking on any of the books will open selected book. View of books can be switched between list and grid view.
            
            
            
            Once the book is opened, its table of content will appear in the left navigation, under the same tab - "Book". This table of content can be expanded/collapsed by chapters, and allows for easy navigation throught the book.
            
            {{Clear}}
            
            
            
            ==Book manager==
            
            [[File:BlueSpiceBookmaker2.jpg|thumb]]
            
            
            
            Books can be managed through Special:BookshelfBookManager. It can be accessed from the overview of the books, as described in previous section, above the list of book or by navigating to Special:SpecialPages.
            
            In the Book manager, where overview of all books is available, books can be:* Added - by clicking "Add" button
            
            
            
            *Edited - by selecting a book and clicking the wrench icon
            
            *Copied - by selecting a book and clicking "copy" icon
            
            *Deleted - by selecting a book and clicking "delete" button
            
            *Exported to PDF - by selecting a book and clicking PDF icon
            
            *Assigned to a user/group - might be unavailble depending on the wiki configuration
            
            
            
            ===Create a new book===
            
            [[File:BlueSpiceBookmaker3.jpg|thumb]]
            
            [[File:BlueSpiceBookmaker4.jpg|thumb]]
            
            [[File:BlueSpiceBookmaker5.jpg|thumb]]
            
            [[File:BlueSpiceBookmaker6.jpg|thumb]]
            
            [[File:Bookshelf7.png|thumb]]
            
            
            
            Creating a new book is done by clicking the "plus" button. Here a name and a type for the book is given.
            
            After clicking "OK", book is created, and BookEditor is opened, which allows content to be added to the book. Pages can be added one by one, by clicking "Add" button - which opens a dialog to type the name of the page to be inserted, or in a batch using "Mass add" button.
            
            
            
            ====Mass adding pages====displayed as list or grid view. Clicking on a book opens the selected book. Once the book is opened, its chapter navigation appears in the left navigation.
            
            
            <br />[[File:BlueSpiceBookmaker2.jpg|thumb|link=https://en.wiki.bluespice.com/wiki/File:BlueSpiceBookmaker2.jpg|alt=Book list|center|650x650px|Book list]]
            
            
            
            ==Book manager==
            
            The menu item ''Global Actions > Book manager'' loads the page <code>Special:BookshelfBookManager</code>. Here, you can add a new book by clicking the ''plus ''button.
            
            
            <br />[[File:BlueSpiceBookmaker3.jpg|thumb|link=https://en.wiki.bluespice.com/wiki/File:BlueSpiceBookmaker3.jpg|alt=Book manager|center|650x650px|Book manager]]
            
            
            
            
            
            You can take the following actions on a book:
            
            
            
            *[[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 page in the namespace ''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.
            
            *[[Manual:Extension/BlueSpicePageAssignments|Assign]] (5): Assigns the book to designated users.<br />
            
            
            
            [[File:Manual:book-manager-actions.png|alt=Actions in the book manager|center|650x650px|link=https://en.wiki.bluespice.com/wiki/File:Manual:book-manager-actions.png|thumb|Actions in the book manager]]
            
            ==Creating a book==
            
            To create a book:
            
            
            
            #'''Go to''' ''Global actions > Book manager''.
            
            #'''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. <br />[[File:Manual:create-book.png|link=https://en.wiki.bluespice.com/wiki/File:Manual:create-book.png|alt=Screenshot:create book|center|650x650px]]
            
            #'''Click''' ''Done''.
            
            
            
            After that, the book editor opens. Here you can add pages to your book by clicking the ''plus'' button. A dialog opens, where you can select the pages you want to add to your book.You can also enter the name of a page that doesn't exist yet.[[File:BlueSpiceBookmaker5.jpg|thumb|link=https://en.wiki.bluespice.com/wiki/File:BlueSpiceBookmaker5.jpg|alt=Adding a page to a book|center|650x650px|Adding a page to a book]]
            
            ===Mass-adding pages===
        
        After clicking "Mass add", a dialog is opened, where criteria by which to select pages can be selected. It contains different criteria for page selection:
        
        
        
        *All pages of a category
        
        *All subpages of a certain page
        
        *From a page collection - page collections are lists of pages located in the MediaWiki namespace, which. They are usually created from [[Manual:Extension/BlueSpiceExtendedSearch#Export|search results]].
        
        *By a semantic property - pages can be selected based on athe value of a certain semantic property.
        
        
        
        
        
            
            
        After desired pages are adding your book pages click Save at the bottom of the page. Now you have created a page in the namespace Book. It contains the list of pages that have been added to the book, it can be saved by clicking "Save" button at the bottom.
            
            
            
            ===Editing a book===
            
            Editing a book involves much of the same procedure as when .[[File:BlueSpiceBookmaker6.jpg|thumb|link=https://en.wiki.bluespice.com/wiki/File:BlueSpiceBookmaker6.jpg|alt=Saving the book page|center|650x650px|Saving the book page ]]{{Box Note|boxtype=important|Note text=Each wiki page can only be added to one book. If a page later is added to another book with chapter navigation, the page always leads to the chapter navigation of the book that last  generated or updated its chapter navigation.}}
            
            
            
            ===Creating the chapter navigation===
            
            After saving a book page, you have created a wiki page in the namespace ''Book'' which contains a list of links to the wiki pages in the book. The chapter navigation is generated separately.
            
            
            
            To add the chapter navigation, go back to the book page in the book manager. Clicking on the book title opens the book page in the book editor. Scroll down to the ''Save'' button and select the drop-down arrow. Click ''Save and add book navigation to each wiki page''.[[File:Manual:book-createnav.png|alt=Create chapter navigation|center|650x650px|link=https://en.wiki.bluespice.com/wiki/File:Manual:book-createnav.png|thumb|Create chapter navigation]]This adds a bookshelf tag in the source code of all wiki pages that are part of this book. The tag, therefore, defines which book this page belongs to: <code><nowiki><bookshelf src="Book:EmployeeManual" /></nowiki></code>.[[File:Manual:bookshelf-tag.png|alt=Bookshelf tag in the source code|center|650x650px|link=https://en.wiki.bluespice.com/wiki/File:Manual:bookshelf-tag.png|thumb|Bookshelf tag in the source code]]{{Box Note|boxtype=note|Note text=If you later add more pages to a book, you have to generate the chapter navigation again. Without this step, the newly added pages will not have a bookshelf tag and therefore not be shown in the chapter navigation of the book. If you only added one or two new pages, you can also add the bookshelf tag manually to the source code of these new pages.}}
            
            
            
            ==Editing a book==
            
            After you have created the book, click on the name of the book. This opens the ''Book Editor''.
            
            
            
            Editing a bookis is similar to creating a new book, regarding adding pages to the book. 
            
            
        Pages can also be deleted by selecting a page in the book structure and clicking "delete" button.
            
            Chapters - and removed from a book by right-clicking on the page name and selecting ''Delete from book'' (this will not delete the wiki page itself). Chapters - and the general book structure - can be rearangedre-arranged by dragging and dropping pages in the book structure. By dragging and dropping PageA Page A over the PageB, PageA Page B, Page A will be placed underneat the PageB in the book hierarchy.
            
            
            
            
            
            ===Insertunderneath Page B in the book hierarchy.[[File:Manual:book-editor.png|alt=Book editor|center|650x650px|link=https://en.wiki.bluespice.com/wiki/File:Manual:book-editor.png|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, [[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.
            
            
            
            ===Inserting meta data===
        
        While editing a book (adding or removing pages), meta-data for the book can be added. To edit metadata, select top-most node of the book (first page) and click the wrench icon. A dialog will be opened where various meta-data can be added or removed. Some of the most important meta-data include:
        
        
        
        *Title
        
        *Subtitle
        
        *Author 1 and 2
        
        *Document-ID
        
        *Document type
        
        *Department
        
        *Version
        
        *Template (PDF)
        
        *Table of Contents (Only article titles, or Embed article TOCs)
        
        
        
        ====Add Adding a cover photo====
            
            In order to image===
            
            To add a cover photo for the book, add a metadata item "''Bookshelf image"''. Select this option from the dropdown and click "''Add"''. Once the meta data is added enter the name of the image in the value field. Any image currently uploaded to the wiki can be used. Type the name without the "File:" prefix, just   (enter the image name and file extension.
            
            
            
            
            
            ===Export books===
            
            Book can be exported, individual chapters or even pages into the PDF format).
            
            ==Exporting books==
            
            You can export an entire book, individual chapters or single pages as PDF:
        
        
        
        *Open the book in the book editor.
        
        *Select all pages or chapters you want to be exported export by clicking the associated checkboxes in front of them. Subchapters will be automatically selected.
        
        *Clicking on the "Export selection" dropdown menu, open opens a list of availble formats. By clicking on one of the formats offered,  the book export will start
            
            
            
            ====Configuration options====starts.
            
            
            
            [[File:Bookshelf7.png|thumb|link=https://en.wiki.bluespice.com/wiki/File:Bookshelf7.png|alt=Book export|center|650x650px|Book export]]
            
            ===Configuration options for the book export===
        
        Wiki administrators can configure the following settings:
        
        {{#dpl:title=Manual:Extension/BlueSpiceConfigManager|include=#Export}}
            
            ==Tipps for working with books==
            
            
            
            *Use a competent team to decide on the content that should be transferred into an online book.
            
            *Decide on how to handle existing numerations or references.
            
            *Seize the opportunity: get rid of unnecessary content (or don't include it in your wiki in the first place)
            
            *Decide on standards for documents: when does it make sense to link documents in the wiki? When is is sensible to include the document's content into a wiki article?
            
            *Decide on a fitting course of action: do you want to create the articles in the wiki first, and compile them in a book structure afterwards, or do you want to create the book structure first, and create and edit the articles contained gradually? Especially if you choose the latter, templates will be very important, because you can add the book navigation tag necessary already to the template. This saves a lot of time later on.
            
            
            
            
            
            
        <br />
            
            ==Deleting a book==
            
            When you delete a book, you only remove the book page in the namespace ''Book'' from the 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|link=https://en.wiki.bluespice.com/wiki/File:Manual:delete-book.png]]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 to delete the booktag from the pages.
            
            ==Duplicating a book==
            
            You can create an entire copy of the book by duplicating it:
            
            
            
            '''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.[[File:Manual:duplicate-book.png|alt=Duplicating a book|center|400x400px|link=https://en.wiki.bluespice.com/wiki/File:Manual:duplicate-book.png|thumb|Duplicating a book]]'''About the duplicated files:'''
            
            
            
            *'''Book page:''' 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.
            
            *'''Wiki 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 />
            
            
            
            
        ==Configuration==
        
        
        
        In the [[Manual:Extension/BlueSpiceConfigManager|Config manager]], you can change the following settings:
        
        
        
        
        In order to {{#dpl:title=Manual:Extension/BlueSpiceConfigManager|include=#BlueSpiceBookshelf}}
            
            
            
            ==Permissions==
            
            To create and edit books, user needs "edit"users need ''edit'' rights in Book namespace. Additionally, a user can only add pages to the book that that user can read. 
            
            {{#dpl:title=Manual:Extension/BlueSpiceConfigManager|include=#BlueSpiceBookshelf}}
            
            
            
            {{Box Links-en|Topic1=[[Reference:BlueSpiceBookshelf]]}}
            
            
            
            
        If a user tries to export a book to PDF that contains pages for which the user does not have permissions, the user will get an error message.<br />
            
            ==Tipps for working with books==
            
            
            
            *Use a competent team to decide on the content that should be transferred into an online book.
            
            *Decide on how to handle existing numerations or references.
            
            *Seize the opportunity: Get rid of unnecessary content (or don't include it in your book).
            
            *Decide on standards for documents: When does it make sense to link documents in the wiki? When is is sensible to include the document's content into a wiki article?
            
            *Decide on a fitting course of action: Do you want to create the articles in the wiki first, and compile them in a book structure afterwards, or do you want to create the book structure first, and create and edit the articles contained gradually?
            
            {{Box Links-en
            
            |Topic1=[[Reference:BlueSpiceBookshelf]]
            
            |Topic2=[[Reference:BlueSpiceBookshelfUI]]
            
            }}
            
            
        {{Translation}}