Difference between revisions of "Manual:Extension/BlueSpiceUniversalExport"

<bs:bookshelf src="Book:User manual" />
            
            
            
            __TOC__
            
            
            
            ==What is UniversalExport?==
            
            '''UniversalExport''' enables the single page export to PDF.
            
            
            
            ==Where to find UniversalExport?==
            
            UniversalExport provides also a widget (<code>UNIVERSALEXPORT</code>
            
            ) called "Export" for the [[Archive:Widgetbar|Widgetbar]]. This includes links to various export modules. Which modules are displayed depends on the settings of the respective modules and on the permissions of
            
            
            <code>universalexport-export</code>. Access to an export module can also be granted and withheld depending on namespaces.
            
            
            
            ::: [[File:UniEx1.jpg|500x306px]]
            
            ==The functionality of UniversalExport==
            
            ===Information on the special page===
            
            The export modules installed and their status can be viewed at <code>Special:UniversalExport</code>. The information displayed depends on the individual modules.
            
            
            
            ::: [[File:UniEx2.jpg|500x300px]]
            
            ===Settings===
            
            UniversalExport and the individual modules can be configured under "WikiAdmi > Preferences".
            
            
            
            ::: [[File:UniEx3.jpg|500x286px]]
            
            ::: [[File:UniEx4.jpg|500x132px]]
            
            ::: [[File:UniEx5.jpg|500x295px]]
            
            
            
            
            
            ===Configuration variables===
            
            Following settings can be configured for UniversalExport and its submodules
            
            
            
            ===='''Universal Export'''====
            
            {| class="contenttable"
            
            |-
            
            !|'''Setting'''
            
            !|'''Description'''
            
            |-
            
            ||
            
            Metadata (standard, JSON format)
            
            
            
            ||Additional metadata to include in the template in JSON format, for example:
            
            {"creator":"Hallo Welt! Medienwerkstatt GmbH"}
            
            
            
            |-
            
            ||
            
            Metadaten (overriding, JSON format)
            
            
            
            ||
            
            Metadata values to override existing metadata keys
            
            
            
            |}
            
            
            
            ====UniversalExport PDF module====
            
            {| class="contenttable"
            
            |-
            
            !|'''Setting'''
            
            !|'''Description'''
            
            
            
            |-
            
            ||
            
            Standard template
            
            
            
            ||Default template to use for exporting to PDF
            
            |-
            
            ||
            
            Backend URL
            
            
            
            ||URL to bshtml2pdf service
            
            |-
            
            ||
            
            Hide namespace prefix in PDF
            
            
            
            ||Whether to hide namespace part of page name when exporting to PDF
            
            |-
            
            ||
            
            Template directory:
            
            
            
            ||Directory path to where PDF templates are located
            
            |}
            
            
            
            ====UniversalExport Book PDF Module====
            
            {| class="contenttable"
            
            |-
            
            !|'''Setting'''
            
            !|'''Description'''
            
            
            
            |-
            
            ||
            
            Table of Contents
            
            
            
            ||
            
            |-
            
            ||
            
            Standard template:
            
            
            
            ||
            
            |-
            
            ||
            
            Template directory:
            
            
            
            ||
            
            |}
            
            
            
            ====UniversalExport HTML Module====
            
            {| class="contenttable"
            
            |-
            
            !|'''Setting'''
            
            !|'''Description'''
            
            |-
            
            ||
            
            
            
            ||
            
            |-
            
            ||
            
            Path to templates
            
            
            
            ||
            
            
            
            |}
            
            
            
            ==Tips for working with UniversalExport==
            
            * [[Shoutbox]] comments are not included when a page is exported.
            
            
            
            ==Classical export with MediaWiki==
            
            MediaWiki itself only offers the export of content pages in a proprietary XML format. There are, however, extensions which make the creation of ODF, PDF or DocBook files possible.
            
            
            
            ==See also==
            
            Our [[UniversalExport|reference page.]]
            
            
            
            
            <div id="box-info" style="width: 98%; margin: 20px 0; border: solid 2px #99bbe8; padding: 8px; background-color: #d6e3f2;">
            
            [[Image:Icon-link.png|left]]<div style="text-transform: uppercase; color: #99bbe8; font-size: 16px; font-weight: bold; margin: 0;">Related topics</div>
            
            
            <div color:="" 000="">
            
            * [[Bookshelf|PDF book of several articles]]
            
            * [[RSSStandards|RSS Export]]
            
            * [[Preferences|Admin Preferences]]
            
            
            
            
            </div>
            
            
            </div>{{DISPLAYTITLE:Export options}}
            
            
            
            '''BlueSpiceUniversalExport''' allows exporting wiki pages to various formats. It incorporates various modules, each serving as exporter for a particular export type.
            
            
            
            ==The export menu==
            
            Every content page on the wiki can be exported. Export fuctions are located in the general [[Manual:BlueSpice Layout#Page tools|page tools]] under the menu item ''Export''. The available export options depend on your wiki configuration. Clicking one of the links downloads the page content in the selected format.
            
            
            
            
            <br />
            
            
            
            [[File:UniversalExport1a.png|Export options|alt=Export options|center|650x650px|link=https://en.wiki.bluespice.com/wiki/File:UniversalExport1a.png|thumb]]
            
            ==Modules==
            
            The extension ''BlueSpiceUniversalExport'' contains several modules:
            
            
            
            *'''BlueSpiceUEModulePDF:''' module for exporting pages in PDF (.pdf) format. It downloads the current page (PDF single page), the current page including all its subpages (PDF page with subpages), or the current page and the pages that are linked from that page (PDF page with linked pages).
            
            *'''BlueSpiceUEModuleHTML:''' module for exporting pages as an html zip-archive (option HTML single page).
            
            *'''BlueSpiceUEModuleBookPDF:''' module for exporting books. This module is only availble if [[Manual:Extension/BlueSpiceBookmaker|BlueSpiceBookmaker]] is installed. It exports entire books in PDF format (available in the Book Manager).
            
            
            
            ==Configuration==
            
            
            
            Configuration of UniversalExport (and its modules) can be done in the [[Manual:Extension/BlueSpiceConfigManager|Config manager]] in the ''Export'' section. Available settings include:
            
            
            
            *'''Table of contents:'''  only applies to exporting books. Select how the ToC should be constructed (as a ToC for the entire book or for each page individually).
            
            *'''Hide namespace prefix in HTML:''' removes namespace prefixes when displaying page titles in HTML exports.
            
            *'''Hide namespace prefix in PDF:''' removes namespace prefixes when displaying page titles in PDF exports.
            
            *'''Metadata (standard, JSON)''' : additional data to be passed to the rendering template in JSON format. This data will be avalible for usage in the template (advanced users).
            
            *'''Metadata (override, JSON)''': offers overriding standard data sent to the rendering template. Values that are set by default can be overriden by using this option (JSON format) (advanced users).<br />
            
            
            
            [[File:UniversalExport2a.png|Configuration options|alt=Configuration options|center|650x650px|link=https://en.wiki.bluespice.com/wiki/File:UniversalExport2a.png|thumb]]<br />
            
            
            
            ==Tags==
            
            If the following tags are included in a page, they are usually applied both to the PDF book export and to the PDF single page export unless otherwise noted.
            
            
            
            === Manual page brea ===
            
            You can insert the following tag on a wiki page anywhere you want to force a manual page break in the PDF:<syntaxhighlight lang="text">
            
            
            <bs:uepagebreak></div>
            
            
            </syntaxhighlight>In visual editing mode, a marker is displayed where the page breaks have been inserted.
            
            
            <br />
            
            [[File:Manual:pdf-pagebreak-marker.png|alt=Marker for page breaks in visual editing mode|center|thumb|750x750px|Marker for page breaks in visual editing mode]]
            
            
            <br />
            
            ===Landscape printing===
            
            To print a PDF page in landscape format, the following tag can be inserted in the wiki page in source editing mode at any position:
            
             <nowiki><bs:ueparams template="BlueSpice_Landscape" /></nowiki>
            
            To make it easier for the user to add this tag with the visual editor, this tag can be added to a wikitext-template, for example, <code><nowiki>{{LandscapeFormatExport}}</nowiki></code>. The element can be inserted anywhere on the page.{{Box Note|boxtype=note|Note text=This tag only works for the PDF single page export.}}Within a wiki page, individual areas can be marked separately (e.g. wide tables). This way, the output in the export can be landscape or extra-wide. This is possible using the following css classes:
            
            
            
            *"bs-rotated" -> landscape format
            
            *"bs-narrow" -> 0,33 x A4 portrait
            
            *"bs-ultrawide" -> 2 x A4 landscape
            
            
            
            These classes can also be combined. Example:
            
             <nowiki><div class="bs-rotated bs-ultrawide">...</div></nowiki>
            
            The start and end div tags can also be added to templates (e.g., <code><nowiki>{{LandscapeStart}}</nowiki></code> and <code><nowiki>{{LandscapeEnd}}</nowiki></code>) to allow users to insert the tags using the visual editor.{{Box Note|boxtype=note|Note text=Display of header and footer areas could be problematic when using these tags.}}These css classes also work for the book export.
            
            
            
            ===PDF-specific styling===
            
            {{Box Note|boxtype=important|Note text=The tag is only taken applied in the single page export (including linked pages and subpages). The tag from individual pages is ignored in the book export. The tag can, however, be inserted on the corresponding book page in the ''Book:'' namespace and is then applied to all pages in the book.}}
            
            To style classes or IDs only in the PDF output, you can include the following tag at the beginning of a page:<syntaxhighlight lang="text">
            
            
            <bs:uemeta body-class=class-name-here/>
            
            
            </syntaxhighlight>
            
            
            
            
            
            Example''': Changing background, header, and footer settings'''
            
            
            
            #Insert the tag  <code><nowiki><bs:uemeta body-class=bg-grey bg-yellow no-header-image no-footer-text/></nowiki></code> at the top of your wiki page.
            
            #To define the page background, add the following CSS to  <code>MediaWiki:Common.css</code> ein (admin rights needed):<syntaxhighlight lang="css">
            
            /*PDF output*/
            
            .bg-grey { background-color:#EDEDED !important;} /*sets the page background. There will be a white margin around it.*/
            
            .bg-yellow .bs-page-content { background-color:#F7F0C6; padding:10px;}  /*sets the background color for the content and adds padding*/
            
            .no-header-image #bs-runningheaderfix { background:none;} /*removes the PDF header*/
            
            .no-footer-text #bs-runningfooterleft, .no-footer-text #bs-runningfootercenter, .no-footer-text #bs-runningfooterright  { display:none;} /*removes the text from the PDF footer*/
            
            
            </syntaxhighlight>Compare the page before inserting the tag and after inserting the tag: <br />
            
            
            <gallery widths="250px" heights="400px">
            
            File:pdf-class-output-vorher.png
            
            File:pdf-class-output-nachher.png
            
            
            </gallery>
            
            
            
            ===Exclude content from PDF export===
            
            To exclude the content of a page from the PDF export, it can be inserted via the visual editor under ''Insert> No PDF''. The text is then marked accordingly in the source text:
            
             <nowiki><bs:uenoexport>Dieser Text wird nicht ins PDF exportiert.</bs:uenoexport></nowiki>
            
            
            
            ==Show content in PDF only==
            
            If content should only be displayed in the PDF, but not on the wiki page, this content can be marked manually via the source text. First, a wiki administrator needs to add the following code to the page ''MediaWiki: Common.css'':<syntaxhighlight lang="css">
            
             .bs-page-content .no-pdf {
            
                 display: none;
            
             }
            
             .bs-page-content div.only-pdf {
            
                 display:block;
            
             }
            
             .bs-page-content span.only-pdf {
            
                 display:inline;
            
             }
            
             
            
             .only-pdf {
            
                 display: none;
            
             }
            
            
            </syntaxhighlight>
            
            
            
            
            
            A block element or an inline element can now be created for the PDF export. This content is not rendered on the wiki page in display mode. Source code examples:
            
             <span class="p" style="box-sizing: inherit;"><</span><span class="nt" style="color: rgb(0, 128, 0)">div</span> <span class="na" style="color: rgb(125, 144, 41)">class</span><span class="o" style="color: rgb(102, 102, 102)">=</span><span class="s" style="color: rgb(186, 33, 33)">"only-pdf"</span><span class="p" style="box-sizing: inherit;">></span>This block is only shown in the PDF.<span class="p" style="box-sizing: inherit;"></</span><span class="nt" style="color: rgb(0, 128, 0)">div</span><span class="p" style="box-sizing: inherit;">></span>
            
             The adjective <span class="p" style="box-sizing: inherit;"><</span><span class="nt" style="color: rgb(0, 128, 0)">span</span> <span class="na" style="color: rgb(125, 144, 41)">class</span><span class="o" style="color: rgb(102, 102, 102)">=</span><span class="s" style="color: rgb(186, 33, 33)">"no-pdf"</span><span class="p" style="box-sizing: inherit;">></span>beautiful<span class="p" style="box-sizing: inherit;"></</span><span class="nt" style="color: rgb(0, 128, 0)">span</span><span class="p" style="box-sizing: inherit;">><</span><span class="nt" style="color: rgb(0, 128, 0)">span</span> <span class="na" style="color: rgb(125, 144, 41)">class</span><span class="o" style="color: rgb(102, 102, 102)">=</span><span class="s" style="color: rgb(186, 33, 33)">"only-pdf"</span><span class="p" style="box-sizing: inherit;">>small</</span><span class="nt" style="color: rgb(0, 128, 0)">span</span><span class="p" style="box-sizing: inherit;">></span> is shown differently on the page and in the PDF.
            
            
            <br />
            
            ==<span class="mw-headline" id="Darstellung_von_Email-Adressen">Display of email addresses</span>==
            
            If an email link has an additional label on a wiki page, the email address will be listed separately in the PDF after the link label.
            
            
            <br />
            
            [[File:Manual:pdf-email-wikipage-EN.png|alt=Email link on wiki page|center|thumb|750x750px|Email link on wiki page]]
            
            
            <br />
            
            [[File:Manual:pdf-email-output-EN.png|alt=PDF link in PDF output|center|thumb|750x750px|PDF link in PDF output]]
            
            
            <br />
            
            ==Printing==
            
            MediaWiki, by default, provides a print view for the pages. This command is also available in the ''Export'' menu (option ''Print'').
            
            
            
            {{#dpl:title=Manual:Extension/BlueSpiceConfigManager|include=#BlueSpiceUniversalExport}}
            
            
            
            {{Box Links-en|Topic1=[[Reference:BlueSpiceUniversalExport]]
            
            |Topic2=[[Reference:BlueSpiceUEModulePDF]]
            
            |Topic3=[[Reference:BlueSpiceUEModuleBookPDF]]
            
            |Topic4=[[Reference:BlueSpiceUEModuleHTML]]
            
            |Topic5=[[Manual:Extension/BlueSpiceBookshelf|Creating books]]
            
            }}
            
            
            
            {{Translation}}
            
            
            
            [[Category:Page tools]]