Manual:Extension/PDFCreator

Migration of existing custom PDF templates:

Custom PDF templates from earlier BlueSpice versions require manual updates to the new PDFCreator functionality. Depending on the requirements, the templates can be newly created in the wiki. For complex customizations, the support of a developer is required.

For existing BlueSpice cloud templates, there are some instructions for the necessary changes.

Exporting a page or a book

To print a page to PDF, click on the page-icon in the page tools. This opens the export dialog field.

PDF export dialog

Select the export settings.

• Mode:
  • Page: Prints the page.
  • Page with subpages: Prints the page and all its subpages. This option is only shown if the page has subpages.
  • Page with linked pages: Prints the page and the pages that are linked directly from this page
• Template:
  • StandardPDF: This prints the page or pages without a cover sheet (unless the template has been edited).
  • StandardBookPDF: This adds a cover sheet to the PDF (unless the template has been edited).

Whether linked pages should be considered in the PDF export is defined in the chosen export template.

By default, the template StandardPDF shows the wiki's logo (from the skin settings page). If there are no custom settings, the default BlueSpice logo is used.

Exporting media links

By default, media links (=links that point directly to the file on the server) will add an attachment to the exported PDF File. This is independent of the chosen export mode (Page, Page with linked pages).

This is also true for PDF files that are embedded via Content Droplet PDF preview.

If no attachments should be added, this has to be defined in the Properties of the PDF template.

Exporting pages with linked pages

When pages are exported with their linked pages, link types are processed as follows:

• Media links will add an attachment to the exported PDF File
• File links are clickable and forward to the corresponding file page
• Mentions are clickable and forward to the user page

If no attachments should be added, this has to be defined in the Properties of the PDF template.

If no links to pages that are not included in the PDF should be added, this has to be defined in the Properties of the PDF template.

Adding a new template

By default, the wiki provides two PDF templates:

• StandardPDF: Template without a cover page for the single-page export.
• StandardBookPDF: Template with a cover page for the book export.

Starting with BlueSpice 5.1, PDF templates can be created from the page Special:PDF templates.

Copy an existing template

To create a new PDF template:

1. Go to the page Special:PDF_templates.
2. Copy an existing template.

   

   Copy a template

3. Enter a name for the new template.
4. Click Copy.

Click Edit template to start customizing your template.

Edit template properties

Select general template properties

1. Select the page orientation and the general export properties (for example, whether to show the Table of Contents for each page or whether to include links to pages that are not exported in the PDF itself).
2. Click Next.

Select the template elements

Select the checkboxes for each element you want to include in your template:

• Header: Page header for the template pages
• Footer: Page footer for the template pages
• Document preface: Cover page
• Document appendix: Additional page that is added at the end of the pdf. It is formatted like the content pages (with header and footer) and adds to the PDF page count.

Click Configure for each template element to design the layout.

Configure the header

The header elements can consist of a header image (usually your logo) and some text (which can be a combination of predefined parameters and your own text).

Defining the header

If you want to show an image that is different from your wiki logo, you can select "Use custom logo" and enter an existing image name or upload a new image.

Configure the footer

By default, the wiki provides localization system messages for each footer section. Use system messages if you want to support the language settings of your users. For example, in an English wiki, the English system message for {{int:pdfcreator-pdf-disclaimer}} can be changed on the page MediaWiki:pdfcreator-pdf-disclaimer. the German language version on page MediaWiki:pdfcreator-pdf-disclaimer/de.

Alternatively, you can simply type your own text if the PDF export does not have to consider user languages. Or leave the section blank if you don't want to print text.

Configure the document preface (PDF cover)

You can define the following elements on your cover page:

Background image:

• If a bookshelf image exists, the bookshelf image is used as cover image for the Book PDF export.
• If no bookshelf image exists, the default image defined in the Configuration Manager is used as cover image for the Book PDF export.
• If a custom image is defined in the PDF template, the custom image will be used for the Book PDF export.

If you do not want to use any background image on your PDF cover page, all three locations for defining a book image must be empty.

Properties

The following properties can be configured:

{
	"embed-page-toc": true,
	"nsPrefix": true,
	"attachments": true,
	"suppress-links": false,
	"no-redirect": true,
	"coverBackground": ""
}

Label	Name	Default value	Description
Show namespace prefix	nsPrefix	true	The namespace prefix of pages is not printed in the page titles.
Show table of contents	embed-page-toc	true	Include the table of contents of each exported page.
Ignore redirect	no-redirect	false	If links are redirecting to a different page, the target page is not included in the pdf.
Allow attachments	attachments	true	If files are directly linked with syntax Media: , the files are also attached in the pdf.
Disable links in PDF	suppress-links	false	Replaces all links in the pdf with a span-element if they do not link to a target within the pdf.
-	coverBackground	<File:filename.png>	This property is set programmatically when a custom cover background image is provided.

PDF template slots

All templates are saved as subpages of MediaWiki:PDFCreator.

There, you can see the syntax for the different template elements.

Template elements

Each template consists of the same elements (slots):

Template slot	Description
Header	The page header of each PDF page. The basic structure is: <div class="pdfcreator-runningheaderfix"> <table> <tr> <td> <div class="pdfcreator-runningheader-logo"> {{{logo}}} </div> </td> <td> <h1 class="title">{{{title}}}</h1> </td> </tr> </table> </div> Important! The class .pdfcreator-runningheaderfix is necessary to top-align the header on the page. It works in conjunction with the class-declaration in the "Styles" tab of the template. Both need to be modified together.
Content	The content layout. The basic structure is: {{{content}}}
Footer	The page footer of each PDF page. The basic structure is: <div class="pdfcreator-runningfooterfix"> <table> <tr> <td> <span>{{int:pdfcreator-pdf-disclaimer}}</span> </td> <td> <span>{{int:pdfcreator-pdf-export-time}}:{{#time:d.m.Y|now}}</span> </td> <td> <span>{{int:pdfcreator-pdf-param-currentpagenumber-label}} </span>{{{currentpagenumber}}} <span> {{int:pdfcreator-pdf-param-totalpagescount-label}} </span>{{{totalpagescount}}} </td> </tr> </table> </div> Important! The class .pdfcreator-runningfooterfix is necessary to top-align the header on the page. It works in conjunction with the class-declaration in the "Styles" tab of the template. Both need to be modified together.
Document preface	The cover page. It is meant for the book export, but can also be used for a page export. The basic structure for a book cover page is: <div class="pdfcreator-intro"> <div class="pdfcreator-intro-title">{{{title}}}</div> </div> Important! The class .pdfcreator-intro is necessary to display the image for the {{{logo}}}-parameter. Without this class present in the template, the {{{logo}}}-parameter has no effect.
Document appendix	The last page of the PDF export. It has no predefined basic structure.
Styles	Style declarations for the CSS classes that are used in any of the template elements. You can view the standard styles here.
Properties	Allows to control some aspects of the PDF output. The following properties are available (shown in default settings): { "embed-page-toc": true, "nsPrefix": true, "attachments": true, "suppress-links": false, "no-redirect": false, "coverBackground": "File:filename.jpg" }
Description	Internal notes for the usage of this template. The description has no effect on the template itself.

Configuration

PDFCreator Konfiguration

Hide namespace prefix in PDF: Removes the namespace prefix from titles and from template parameter "title" in the PDF output.

• Default export template for pages: The default template is shown when users select an export template in "Page" mode. It is also used when clicking on the PDF link for the Content Droplet PDF Link .

• Default cover background image

Admins can also set a default cover background image. It is applied whenever the document preface of the template contains the standard "intro"-wrapper:

<div class="pdfcreator-intro">
....
</div>

Default image:

/app/bluespice/w/extensions/BlueSpiceBookshelf/data/common/images/bs-cover.png

Output:

Default PDF cover image

​The image path can be deleted. In this case, no image will be output by default.

Alternatively, an uploaded image file can be specified (without a namespace prefix), for example: industry.jpg

Default image for the cover sheet

If a book has its own bookshelf-image, this will be generated in the PDF when exporting directly from the special page "Books".

Customizations

Semantic property

It is possible to print a semantic property value in any template slot. The following example prints the value of the property "Revision_ID" of a page in the PDF footer.

<div class="pdfcreator-runningfooterfix">
	{{#show:{{FULLPAGENAME}}|?Revision_ID}}
</div>

Background color for header and footer

In the Styles tab, add:

/* add a background color to the header and footer */
.pdfcreator-runningheaderfix, .pdfcreator-runningfooterfix {
background-color: #eee;
}

This adds a grey background color.

Remove the underline from the header and footer

In the Styles tab, add:

/* remove the border from the header */
.pdfcreator-runningheaderfix > table {
border-bottom: none !important;
}

/* remove the border from the header */
.pdfcreator-runningfooterfix > table {
border-top: none !important;
}

Remove page Table of Contents

The table of contents at the beginning of a PDF should be displayed, but not the table of contents for the sections of the pages.

In the Styles tab, add:

/* remove the border from the header */
.pdfcreator-type-page .toc {
    display:none;
}

To also remove the toc at the beginning of the PDF:

/* remove the border from the header */
.toc {
    display:none;
}

Related content droplets

The following content droplets are available:

Droplet name	Comments
Book PDF link	Inserts a link on the page to a book. Clicking the link immediately downloads the PDF.
PDF link	Inserts a link on the page to the same or any other page. Clicking the link immediately downloads the page.
PDF preview	Opens the PDF directly on a page in a PDF viewer.
Exclude content in PDF	Wraps content in the tags <pdfexcludestart />...<pdfexcludeend />You can expand the excluded content by moving the tags in source edit mode to a different content location. Note: The tag <uenoexport /> is deprecated, but still supported. It should no longer be used.
PDF page break	The inserted page break marker is visible both in editing and in view mode. To hide this visual marker in view mode, you can add the following declaration to MediaWiki:Common.css: /*Hide PDF page break marker in view mode */ .bs-tag-pdfpagebreak {display:none} .bs-tag-pdfpagebreak.ve-ce-leafNode {display:block}

Semantic Mediawiki

The books in which a page exists can be queried via the semantic property Books (Property:Books).

Semantic property "Books"

Migrating existing cloud templates

For information about migrating your existing cloud template, click here.

Technical Reference: PDFCreator

PDF exclude - start

---

To submit feedback about this documentation, visit our community forum.

PDF exclude - end