7 Books

{{Textbox|boxtype=note|header=BlueSpice 4.5:|text=This help page applies to the book functionality for BlueSpice 4.5+. For earlier versions, go to the [[Manual:Extension/BlueSpiceBookshelf/4-4|previous documentation.]]|icon=yes}}<bookshelf src="Book:User manual" />
{{DISPLAYTITLE:Books}}
In ''BlueSpice pro'', wiki pages can be displayed as a structured book with chapter navigation. A book can also be printed as a PDF file with a cover sheet.
{{TOClimit|limit=1}}
==Characteristics==
<span class="youtubelink">[[File:book example.png|alt=introduction page of the user manual with chapter navigation|thumb|450x450px|[[File:youtube-icon.png|alt=YouTube icon|left|22x22px]][https://youtu.be/koPjB2KSZow YouTube: Books (5:22 min.)]|link=https://youtu.be/koPjB2KSZow]]</span>Books have the following characteristics:

*On book pages, the book navigation is displayed instead of the main navigation.
* A wiki page can be in multiple books. If a page is in multiple books, the book navigation shows a dropdown menu that allows to switch between these books.
*Books can be printed completely or partially as a PDF with a cover sheet.
*Books can be grouped into individual bookshelves.

== Differences to previous versions == 
*A page can now be in multiple books.
*The books are displayed as thumbnails and can be organized on different "shelves".
*There are no more "own" or "temporary" books since these were edge use cases. Own books will not get lost after updating to BlueSpice 4.5, but rather be stored as a list of links  on subpages of the user profile page (e.g., <code>User:JaneDoe/...</code>).
* There is no option to duplicate a book since this was also an edge use case.
*There is no more separate book manager. All books can now be managed directly from the Books page.

==Creating a book==
Books are created from the page  ''Special:Books''. 
[[File:Bookshelf create book action.png|alt=Page Special:Books with actions menu|center|thumb|650x650px|"Create new book" ]] 

'''To create a book:''' 
#'''Click''' ''Create new book'' in the actions menu of the page tools. This opens a dialog box.
#'''Enter''' a book title.
#'''Enter''' a subtitle (optional).
#'''Select''' a bookshelf (optional). This puts the book in a group of books. If you do not select a bookshelf, the book will be listed under the heading ''Various books''.
#'''Upload or select''' a cover image (optional)'''.''' If you do not upload or select a cover image, a random cover image will be applied.
#'''Click''' ''Save''.  The book is now shown in its bookshelf group and can be edited.
#'''Click''' ''Done''. The book editor loads next.
[[File:book dialog box.png|alt=Create book dialog box with completed fields for a user manual|center|thumb|400x400px|Dialog box]]

==="New" button===
Alternatively, you can create a book via the "New" button. The next steps to save the book are as described above.
[[File:new button menu.png|alt=New button with open drop-down menu|center|thumb|229x229px|New book menu item]]

==Editing a book==
To switch to the book edit mode, '''click''' ''Edit'' in the book preview on the Books page. 

This opens the book editor.

==Adding elements==
To add a wikipage to a book:

#'''Click''' ''Add element.''
#'''Select''' the node type ''Wiki page chapter.''
#'''Enter''' the name of the wikipage you want to add in the field ''Target''.
#'''Enter''' the label you want show for the page in the field ''Text''.
#'''Click''' ''Done''. The page is added to the end of the book.
#'''Drag-and-drop''' the page to the desired section.
#'''Repeat''' steps 1-6 if you want to add another page.
#'''Click''' ''Save'' when you are done.

==Editing meta data==
While editing a book (adding or removing pages), metadata for the book can be added. References to these metadata can be included in the PDF template.  The following table shows which of the Paramters are by default part of the PDF-Printout. All Paramters are part of the user-defined document properties of the printed PDF.  
{| class="wikitable" style="width: 100%;"
|+Meta data and their functionality
!Parameter
!Beschreibung
! style="width:100px;" |in Standard-Vorlagen
|-
|Author 1
|User-defined PDF-document property. Not included in PDF pages.
| style="width:100px;" |no
|-
|Author 2
|User-defined PDF-document property. Not included in PDF pages.
| style="width:100px;" |no
|-
|Bookshelf
|Lists the book on the Books page of the wiki under a particular bookshelf.  It has no relevance for the printed PDF.
| style="width:100px;" |no
|-
|Bookshelf Image
|Image that is shown as preview image. It can be used as [[Manual:Extension/BlueSpiceUniversalExport/Customization#Book cover|cover image of the printed PDF in the Cloud]].
| style="width:100px;" | yes (cloud only)
|-
|Department
|User-defined PDF-document property. Not included in PDF pages.
| style="width:100px;" |no
|-
|Document type
|User-defined PDF-document property. Not included in PDF pages.
| style="width:100px;" |no
|-
|Document-ID 
|Manually assigned document ID.
| style="width:100px;" |no
|-
|Subtitle
|Printed on the cover page.
| style="width:100px;" |yes 
|-
|Table of contents
|''Only article titles:''The PDF TOC does not include the individual page TOCs.
''Embed article TOCs:'' The PDF TOC includes the individual page TOCs.
| style="width:100px;" |yes
|-
|Template (PDF)
| By default, there is only one book PDF template (BlueSpice Book). If custom PDF templates exist (possible in on-premise hosting only), they are listed as options.
|no 
|-
|Title
|Printed on cover page. Overwrites the book title of the wiki for the PDF-printout. It will be used as PDF file name and title on the cover page.
| style="width:100px;" |yes
|-
|Version 
|Manually assigned book version number.
| style="width:100px;" |no
|}

== Mass adding pages==
After clicking "Mass add", a dialog is opened. It contains different criteria for page selection:

*All pages of a category: All pages of a category are added at the end of the book (regardless of whether some of the pages already exist in the book).
*All subpages of a certain page: After selecting a page, all its subpages are added at the end of the book.
* From a page collection: Page collections are lists of pages located in the MediaWiki namespace. They  an be created from a [[Manual:Extension/ImportOfficeFiles|Word import]] or from [https://en.wiki.bluespice.com/wiki/Manual:Extension/BlueSpiceExtendedSearch#Export search results].
{{Textbox|boxtype=important|header=Moving chapters:|text=Currently, it is not possible to move multiple mass-added pages together to a different location in the book. To rearrange the chapters, you can open the book in source editing mode and copy-and-paste chapters to reorder the book pages.|icon=yes}}

== Exporting a book==
'''To download the book as PDF:'''

'''Click''' ''Export'' on the ''Books'' page. This immediately downloads the book.

'''To download individual chapters:'''

#'''Go to''' the entrypoint ''Pages''. If your wiki does not show this link, go directly to the page ''Special:Pages''.
#'''Click''' on a book name.
#'''Select''' the chapters you want to export.
#'''Click''' E''xport'' above the chapter tree.

The book is then downloaded.

==More actions==
The ''More actions'' button allows to delete, assign, or edit the metadata of the book.
[[File:bookshelf more actions.png|alt=expanded "more actions"  menu of a book|center|thumb|287x287px|button "more actions"]]

===Delete===
When you delete a book, you only remove the book page of the book (that is, the table of contents) in the "Book" namespace. The wiki pages in the book are not deleted and they are no longer associated with the book.

===Edit metadata===
This provides the same functionality as the button [[Manual:Extension/BlueSpiceBookshelf#Editing metadata|''Edit metadata'' in the menu editor]].

===Assign ===
A book page can be assigned to individual users or usergroups like any other wiki page. The book will then show up under the user's [[Manual:Extension/BlueSpicePageAssignments|assignments]] in the user menu.

== Including a book table of contents on a page {{Bsvs|bsvFrom=4.4}}==
The [[Manual:Extension/ContentDroplets|Content droplet]] “Book table of contents” can be used to insert the an entire book TOC or an individual chapter navigation of a book on any wiki page.
[[File:droplet-BookTOC.png|alt=Chapter from an admin manual|center|thumb|650x650px|Content droplet "Book table of contents"]]

==Adding a PDF-download link to a page==
The [[Manual:Extension/ContentDroplets|Content droplet]] “Book PDF link” can be used to insert a link on a page that will download a book directly as a PDF.

==Permissions==
To create and edit books, users need ''edit'' rights in Book namespace. Additionally, a user can only add pages to the book that that user can read. 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.

==Configuration==
===Display options===
{{#dpl:title=Manual:Extension/BlueSpiceConfigManager|include=#BlueSpiceBookShelf}}

===Export===
Wiki administrators can make the following adjustments for the book export:
{{#dpl:title=Manual:Extension/BlueSpiceConfigManager|include=#Export}}

===Configuring the file size limits  (server)===
By default, the book export is limited to 50MB in file size. To adjust this value, complete the following steps: 

#In Apache Tomcat, open the file ''web.xml'': <syntaxhighlight lang="c">
sudo -s
nano /opt/tomcat/webapps/manager/WEB-INF/web.xml
</syntaxhighlight>
#Look for the following lines and adjust the value (e.g. for 250MB=26214400) <syntaxhighlight lang="c">
<max-file-size>262144000</max-file-size>
<max-request-size>262144000</max-request-size>
</syntaxhighlight>
# The web app BShtml2PDF also has a setting that needs to be adjusted: <syntaxhighlight lang="c">
nano /opt/tomcat/webapps/BShtml2PDF/WEB-INF
</syntaxhighlight>
#Enter your values in the following lines: <syntaxhighlight lang="c">
<param-name>maxMemSize</param-name> <param-value>26214400</param-value>
<param-name>maxFileize</param-name> <param-value>26214400</param-value>
</syntaxhighlight>
#Restart Apache Tomcat  <syntaxhighlight lang="c">
service tomcat restart
</syntaxhighlight>


{{Box Links-en|Topic1=[[Manual:Extension/BlueSpiceUniversalExport/Customization|PDF Customization (Cloud only)]]}}
{{Translation}}

[[Category:Organization]]