Manual:Extension/BlueSpiceUniversalExport/PDF templates: Difference between revisions

Latest revision as of 12:15, 27 March 2024

If you have server access, you can customize the PDF templates for your wiki. If your wiki is hosted in the BlueSpice cloud, basic customizations can be made directly in the wiki. These instructions refer to the PDF single page export and the book export. Please note that the book export is only available inBlueSpice pro.

Directory paths for templates

Standard BlueSpice templates

Common: extensions/BlueSpiceUEModulePDF/data/PDFTemplates/common
Single page: extensions/BlueSpiceUEModulePDF/data/PDFTemplates/BlueSpice
Book: extensions/BlueSpiceUEModuleBookPDF/data/PDFTemplates/BlueSpice Book

The Common directory contains common files such as page.css that defines the page margins.

Safe directories for your own templates

The PDF templates may not be customized in the standard template directories (see above) since an update will overwrite these directories.

You need to store your custom PDF templates in safe directories instead.

Examples of safe directories:

images/<MyPDFTemplates>
extensions/BlueSpiceFoundation/data/PDFTemplates

Editing the templates

The PDF templates for single pages and books are very similar.

Creating your own templates

The contents of the directories

extensions/BlueSpiceUEModulePDF/data/PDFTempates
extensions/BlueSpiceUEModuleBookPDF/data/PDFTempates

Copy to "extensions/BlueSpiceFoundation/data/PDFTemplates" and rename it

"common" => "common" (remains)
"BlueSpice" => "MyPageTemplate"
"BlueSpice Book" => "MyBookTemplate"

The template names must be changed later in the associated template.php.

Directory structure of the templates

data/PDFTemplates
    |_ common
    |     |_ stylesheets (page.css -> Settings for page margins)
    |
    |_ MyPageTemplate
    |     |_ template.php
    |     |_ template.html
    |     |_ images
    |     |_ stylesheets (styles.css -> Logo in Page Header)
    |
    |_ MyBookTemplate
          |_ template.php
          |_ template.html
          |_ images
          |_ stylesheets (styles.css -> Logo in Page Header)

Customization of the templates

template.php

The file template.php contains the description or definition of the template. All css files and, if applicable, fonts that are to be used in the template must be specified here.

The images must also be specified, for example the images that should be used in the header.

Special requirements for the book:

The PDF template for the book accesses the common directory of the single page template. For this reason, the template.php contains a variable $sCommonDir that points to the directory. If the templates are copied into their own directory, this path must be adjusted.

Important changes in the sections:

Section info:

name => name of the template (e.g. MyPageTemplate). MUST match the directory name

Section resources:

STYLESHEETS => if necessary, specify additional style sheets here. These must also be specified in the template.html. If you use other fonts, they must also be specified here.
IMAGES => enter the images you want to use here. Example 'images/bs-header.jpg'

Section messages:

Here, texts can be assigned to so-called msg keys. These msg keys can be used in the template.html, e.g. the disclaimer.
en, de, de-formal are the languages. Unlike texts written in template.html, these msg keys are used depending on the language.

template.html

Basic structure of the page. Here, the page number, for example, can be removed from the footer. If you want to include your own css files, they must be specified here in the <head>.

Example:

 <link href="stylesheets/styles.css" type="text/css" rel="stylesheet" />

Customization of the style sheets

The display can be changed in the style sheets. This concerns e.g.

Margins
Header with logo
Headings
Text colors
...

The most important examples:

Page margins:

File: common/stylesheets/page.css

The @page area is the normal page in portrait format. The page margins are set in the "margin" line (order: top right bottom left).

Background image:

File: common/stylesheets/page.css

The @page area is the normal page in portrait format. The background image is set in the “background” line.

The background image must be specified in the template.php. (Only used for the single page at BlueSpice.)

Header (logo):

File: MyPageTemplate/stylesheets/page.css

or

File: MyBookTemplate/stylesheets/page.css

With #bs-runningheaderfix, the logo for the header is set in the "background" line.

The logo must be specified in the template.php.

The size of the header and logo can be influenced with the parameters “margin”, “background-size” and “height”. The “width” line should remain at 21cm (entire page width).

Configuring the templates

PDF templates cannot be configured via the Wiki.

The following lines must be added to LocalSettings.php:

Example for single page:

 $GLOBALS['bsgUEModulePDFTemplatePath'] = 'extensions/BlueSpiceFoundation/data/PDFTemplates';
 $GLOBALS['bsgUEModulePDFDefaultTemplate'] = 'MyPageTemplate';

Example for book:

 $GLOBALS['bsgUEModuleBookPDFTemplatePath'] = 'extensions/BlueSpiceFoundation/data

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

@@ Line 11: / Line 11: @@
 === Safe directories for your own templates ===
-The PDF templates may not be customized in the directories mentioned above. <u>An update will overwrite the changes!</u>
+The PDF templates may not be customized in the standard template directories (see above) since an update will overwrite these directories.
+You need to store your custom PDF templates in safe directories instead.
 '''Examples of safe directories:'''