DokuWiki

It's better when it's simple

User Tools

Site Tools


plugin:odt

LibreOffice / OpenOffice Export

Compatible with DokuWiki

  • 2024-02-06 "Kaos" unknown
  • 2023-04-04 "Jack Jackrum" yes
  • 2022-07-31 "Igor" unknown
  • 2020-07-29 "Hogfather" yes

plugin Exports a page to the Open Document Format (ODF) used by LibreOffice and other word processors

Last updated on
2023-03-03
Provides
Syntax, Render
Repository
Source
Conflicts with
header2, inlineeditor, quickedit

This plugin allows you to export a page to the OpenDocument format used by LibreOffice, OpenOffice and other word processors. This is especially useful when you need to print or to give a single page to a customer (Hint: LibreOffice can also export to PDF). Since release version 2016-04-23 a page can also directly be exported to and downloaded as PDF. See section PDF conversion for details.

This plugin was initialized by Andreas Gohr, and was then further developed and maintained by Aurelien Bompard. The older version of ODT plugin with default template support is from Florian Lamml. Currently, the ODT plugin is maintained by LarsDW223.

Requirements

PHP

PHP 5.5 (for PHP 5.3.3+ and PHP 5.4.X, see this workaround).

Users of PHP 7 might consider updating to release 2016-04-23 or newer to prevent that their logfiles run full with meaningless errors (PHP 7 signature errors).

DokuWiki

The current release of this plugin is backwards compatible up to/including DokuWiki release 2015-08-10 “Detritus”.

:!: All releases starting with 2016-09-10 and older are incompatible with the next DokuWiki release “Frusterick Manners” (file inc/ZipLib.class.php is missing).

Plugins

There are no requirements in general but some features have requirements:

  • Bookcreator: for bookcreator support you need to install the Bookcreator Plugin too.
  • Pagebreak: to be able to insert pagebreaks manually you need to install the Pagebreak Plugin too.

Usage

To make a single page exportable you can add the following macro to the page:

~~ODT~~

A better way is to integrate an export button into your template.

If you use the default template just switch the button on in the configuration menu.

Otherwise use the following to add another button in the upper or bottom button row of the template1)

<form class="button" method="get" action="<?php wl($ID)?>">
    <div class="no">
        <input type="submit" value="Export to ODT" class="button" />
        <input type="hidden" name="do" value="export_odt" />
        <input type="hidden" name="id" value="<?php echo $ID?>" />
    </div>
</form>

Or use this for a simple 16×16 icon somewhere in your template:

<a href="<?php echo exportlink($ID, 'odt')?>"><img src="<?php echo DOKU_BASE?>lib/images/fileicons/odt.png" alt="ODT Export" /></a>

You can mix the 2 previous methods, and get a button with an image inside, with this code:

<form class="button" method="get" action="<?php wl($ID)?>">
    <div class="no">
        <button type="submit" class="button">
            <img src="<?php echo DOKU_BASE?>lib/images/fileicons/odt.png" alt="ODT Export" />
           Export to ODT
        </button>
        <input type="hidden" name="do" value="export_odt" />
        <input type="hidden" name="rev" value="<?php global $REV; echo $REV?>" />
        <input type="hidden" name="id" value="<?php echo $ID?>" />
    </div>
</form>

Settings

Most settings or configuration options in the ODT plugin can be set in the ODT plugin configuration, by passing the setting as a URL request parameter or by using the syntax tag.

The precedence is like this (first entry has highest precedence, last entry has lowest):

  1. syntax tag
  2. URL request parameter
  3. ODT plugin configuration setting
  4. DokuWiki configuration setting
    (only relevant for 'toc_maxlevel', see Configuration section below)

This is an example for passing the setting orientation as a URL request parameter:

https://www.dokuwiki.org/plugin:odt?orientation=landscape&do=export_odt

The same works for syntax tags. The syntax tags for settings always have the same format:

{{odt>setting:value}}

Here again the example for the setting orientation:

{{odt>orientation:landscape}}

Configuration

The current release has the following configuration options:

Config option name Function
tpl_dir Sub-directory for the templates in the media manager. Upload your ODT template files to this directory.
firsttemplatedefinitionwins In case of multiple definitions of template, templatepage, css_template, or odt_template, the first will be used. (The value false will apply the last definition, instead.) Needs the usecounter plugin!
odt_template ODT file which shall be used as a template. Per default this field is empty. In that case default styles are used.

Since version 2016-02-13 the template can also be a CSS file. Make sure to use the correct file extensions (.odt or .css) so that the plugin can differ between the file types. See section Templates support for details.
showexportbutton Display the ODT Export Button?
showpdfexportbutton Display the PDF Export Button? (export to ODT and conversion to PDF)
css_usage This setting specifies in which way the imported CSS code from the 'css_template' is used. If set to off (plugins only) (default) then the CSS code will only influence the ODT output of plugins. If set to basic style import then the ODT plugin will additionally apply the imported CSS code on the basic styles like basic text formatting, headers, lists and tables.
media_sel Which @media selector shall be used to query CSS properties? For example 'print' or 'screen'. Currently this only affects the ODT export of plugins, e.g. the Wrap Plugin.
css_font_size Specifies the basic font-size for CSS import/handling. This is the initial value representing 1em.
css_template The DokuWiki template to use for CSS import. This only affects the CSS content given to plugins. It does not affect the look of the DokuWiki basic syntax.
apply_fs_to_non_css If set to true then the css_font_size will also be applied if an ODT template is used or if no template is used at all (no CSS and no ODT template [default]).
usestyles You can give a comma separated list of plugins of which the style.css or screen.css should be used for ODT generation. By default only print.css and odt.css are used. This setting is missing since release 2017-02-11. From that release on the ODT plugin always imports screen and print CSS from each plugin.
twips_per_pixel_x Twips per pixel on the X axis.
twips_per_pixel_y Twips per pixel on the Y axis.
format The page format of the exported document. The current formats are currently supported:
A6, A5, A4, A3, B6 (ISO), B5 (ISO), B4 (ISO), Letter, Legal, Long Bond, Tabloid, B6 (JIS), B5 (JIS), B4 (JIS), 16 Kai, 32 Kai, Big 32 Kai, DL Envelope, C6 Envelope, C6/5 Envelope, C5 Envelope, C4 Envelope, #6 3/4 Envelope, #7 3/4 (Monarch) Envelope, #9 Envelope, #10 Envelope, #11 Envelope, #12 Envelope, Japanese Postcard.
orientation Orientation of the exported document. This allows the option 'portrait' or 'landscape'.
margin Top, Right, Bottom, Left Margins for the exported document in centimeters.
disable_links If set to 'Yes', links will not be encoded as links but just as plain text.
toc_maxlevel Maximum depth for the table of contents. If empty, the value of the global DokuWiki option ‘maxtoclevel’ is used.
toc_leader_sign The leader sign to be inserted in the table of contents.
toc_indents The indentation for the table of contents per level. The values are absolute values in centimeters, not relative to the previous level. E.g. the setting '0, 0.5, 1, 1.5, 2, 2.5, 3, 3.5, 4, 4.5' leads to a indentation of 0.5 centimeters more per level. While '0, 1, 1, 1, 1, 1, 1, 1, 1, 1' keeps level 1 not indented and all other levels have the same 1 centimeter indentation.
toc_pagebreak Insert a pagebreak after the table of contents?
toc_style Style to be used for the table of contents in CSS format, e.g.: 'color:red;'. Each level uses the same style per default. You can assign specific styles using the syntax tag.
index_in_browser If set to hide then the syntax tag toc and chapter-index will create no visible output in the browser. If it is set to display placeholder then a little placeholder paragraph will be shown in the browser showing the user that the syntax tag is there and a table of contents or chapter-index will be inserted on export to ODT.
outline_list_style If set to Normal then headings will have no list style after export.

If it is set to Numbers then all headings will be numbered after exporting to ODT.

Please notice: the numbers of the headings will only appear in the table of contents or chapter index after updating them (which is required anyway).
olist_label_align The setting specifies how to align the numbers in front of list items in an ordered list (left, center, right [default]).
convert_to_pdf The command line to execute for ODT to PDF conversion. The default specifies the command line for PDF conversion using LibreOffice. For details see section PDF conversion.

Additional syntax tags

There are some syntax tags for additional features which can not be set in the configuration alone because e.g. the position matters or to provide more flexibility. These tags are described in this section.

pagebreak

A manual pagebreak can be inserted by adding the syntax tag <pagebreak> in the wiki page. This feature requires the Pagebreak Plugin.

The PageBreak plugin isn't maintained, and bugs are ignored since 2018! Tag <br style=\“page-break-after:always;\”> is broken, <div></div> may be better? $renderer→doc .= “<div style=\”page-break-after:always;\“></div>”;. This seems simple enough that it may be good to add it in dokuwiki core as ~~pagebreak~~ or similar? Andreas G,, can you quickly look at it please?

page

The syntax tag page can be used to set the page format, orientation and margins with one single command. The format is the following:

{{odt>page:format,orientation,margin_top,margin_right,margin_bottom,margin_left}}

The following example sets the page format A3, orientation landscape and all margins to 1 centimeter.

{{odt>page:A3,landscape,1,1,1,1}}

You can also omit parameters that you do not want to change, e.g.:

{{odt>page:A3,landscape}}

That changes the page format and orientation but not the margins.

If you want to alter a single page property only, then you can use the settings tags for format, orientation or the margins alone. See some examples below:

{{odt>format:A3}}
{{odt>format:A4}}

{{odt>orientation:portrait}}
{{odt>orientation:landscape}}

{{odt>margin_top:1}}
{{odt>margin_right:2}}
{{odt>margin_left:3}}
{{odt>margin_bottom:4}}

A change of the page format will finish the current page, cause a pagebreak and the next page will then use the newly set page format.

toc

The toc syntax tag can be used to insert a table of contents at the position of the tag. Without inserting the toc syntax tag, no table of contents will be created at all. The minimum syntax is:

{{odt>toc}}

This will create a table of contents with all relevant settings taken from the ODT plugin configuration. The title will be 'Table of Contents' (depending on the language set).

The following options for the toc syntax tag do exist:

  • maxlevel: this overwrites toc_maxlevel
  • title: this overwrites the language specific default title 'Table Of Contents'
  • leader_sign: this overwrites toc_leader_sign
  • indents: this overwrites toc_indents
  • pagebreak: this overwrites toc_pagebreak
  • styleH: this overwrites the Contents Heading style in the styles.xml file
  • styleL1 … styleLN: N = maxlevel, overwrites toc_style

These have all the same meaning as the corresponding configuration settings. Only exception is styleL1 … styleLN. The configuration setting toc_style sets the style for the whole table of contents. styleL1 only sets the style for toc level 1, styleL2 only sets the style for toc level 2…

The option syntaxH works the same way as the styleL option above but sets the style for the table of contents heading.

All these options are optional. If you omit one, then the corresponding setting of the configuration (or URL request parameter) will be used. Every option needs to be finished with a ; .

Here are some examples (all one line):

{{odt>toc:title=Content;leader_sign=.;indents=0,0.5,1;pagebreak=true;
styleL1="font-weight:bold;";styleL2="font-style:italic;";
styleL3="font-style:normal;";}}
{{odt>toc:title=Content;leader_sign=_;indents=0,2,2;pagebreak=false;
styleL1="font-weight:bold;";styleL2="font-style:normal;";
styleL3="font-style:normal;";}}

chapter-index

The chapter-index syntax tag can be used to insert a chapter-index at the position of the tag. Without inserting the chapter-index syntax tag, no chapter indexes will be created at all. The minimum syntax is:

{{odt>chapter-index}}

This will create a chapter-index with all relevant settings taken from the ODT plugin configuration for the table of contents. By default the chapter-index will have no title.

The options for the chapter-index syntax tag are the same as for the toc syntax tag.

These tags enable or disable link creation just like the configuration setting. Here is the syntax:

{{odt>disablelinks}}
{{odt>enablelinks}}

templatepage

This tag can be used to specify a wiki page as a CSS template. That means all content from the page is imported as CSS code. Example:

{{odt>templatepage:mycsspage}}

It is totally fine if the CSS code in the templatepage is surrounded by <code css>…</code> tags to improve readability.

This feature enables the user to use a CSS template without the need of uploading any files. ATTENTION: using a template page may overwrite already imported style settings from an ODT or CSS template file.

frame-open/frame-close

These tags insert the content between them inside an ODT frame on export to ODT. The HTML view is not changed. Here is the syntax:

{{odt>frame-open:...options...}}
{{odt>frame-close}}

Putting content in a frame can e.g be used to position that content on a fixed point of the page. This e.g. can be useful for writing letters.

See details on using ODT frames for more information.

FIXME: create page, describe frame usage in detail FIXME

Development

Preview

To get some information about the current development release/master branch, have a look at the development preview page.

Customizing

There are three ways of customizing how the output will look like :

  1. Modify an export of the wiki:syntax page:
    • Export the wiki:syntax page
    • Open the result with a ZIP-Archive tool and replace the provided styles.xml with the one from your document.
      Be careful, DokuWiki's caching system may get in the way when you do that. Remember to clean up your cache.
  2. Use the OpenOffice feature to load the styles from an existing file or template :
    • export your page in ODT, and open it in OpenOffice,
    • bring up the styles panel (F11),
    • click on the top-right icon,
    • choose “Load styles…” in the menu,
    • select all the checkboxes on the bottom (including “overwrite”),
    • click “From file…” on the bottom right and select your customized file, or select an existing template in the list.
  3. Use a pre-made template, see the following section for details on this feature.

Templates support

ODT template support

You may use templates to export your document. A template is a regular ODT file, as produced by OpenOffice (for example, not tested with other ODT-supporting applications).

In your wiki page, add the following code:

  {{odt>template:your template file name.odt}}

and upload your template to the wiki using the media manager. By default, you must put it in an :odt namespace (Meaning an “odt” directory right below the root in your wiki). The folder name can be configured using the admin page.

The exported page will be added after the content of your template. If you include the string DOKUWIKI-ODT-INSERT in the template, the wiki page will be inserted there (replacing the string).

:!: Warning : the DOKUWIKI-ODT-INSERT string must not be formatted in any way. To do that, select the line with this string, go to the “Format” menu, and click on the “Default Format” option (the first one).

There are two additional tags you may use in your template : DOKUWIKI-ODT-CUT-START and DOKUWIKI-ODT-CUT-STOP. All the text between these tags will be removed on export. There's a good reason for this feature : in an ODT file, the only styles that will be saved are the styles which are applied to some content in the document. If you want to create an empty ODT document for this plugin, and still want to define styles which will be applied to the wiki content, you have to write some dummy text, apply the styles to this text, and surround the text in the DOKUWIKI-ODT-CUT-START and DOKUWIKI-ODT-CUT-STOP tags. This way, the styles will be retained in the ODT file, but the dummy text will be removed on export.

CSS template support

You may use templates to export your document. A CSS template is a regular CSS text file. In your wiki page, add the following code:

  {{odt>template:your template file name.css}}

and upload your template to the wiki using the media manager. This usually requires to configure the mime types allowed for upload, see mime. By default, you must put it in an :odt namespace (Meaning an “odt” directory right below the root in your wiki). The folder name can be configured using the admin page.

Unlike an ODT template a CSS template does not create any content in the exported document. It “only” controls the styles for the DokuWiki basic syntax.

Check out the example.css file from the ODT plugin directory to get an overview of the currently supported options for changing the look of the exported ODT document.

Since release version 2016-04-23 a CSS template can also consist of a wiki page. See section templatepage for details.

PDF conversion

Since release version 2016-04-23 there is support for optional PDF conversion. The exported ODT file can be converted to PDF by using do=export_odt_pdf instead of do=export_odt. The feature requires installation of an external program to do the conversion e.g. LibreOffice. The command line executed for conversion can be configured. An error page is send to the user if conversion fails.

Since release 2017-02-11 there is a button for PDF conversion which is labelled with ODT⇒PDF export. It is only visible if the config option showpdfexportbutton is on.

Installation hints for LibreOffice

When using LibreOffice for PDF conversion the following error message might be reported on trying to download a ODT document as PDF:

[Java framework] Error in function createSettingsDocument (elements.cxx). javaldx failed! Warning: failed to read path from javaldx

In that case LibreOffice fails because it has not got or can not read from it's configuration directory belonging to the webserver/PHP user.

On my Ubuntu machine the webserver user was www-data, his home directory was /var/www and the configuration directory for LibreOffice was .config/libreoffice. So I needed to create the directory /var/www/.config/libreoffice and set the owner to www-data to make it work.

ODT support for plugins

If you use other syntax plugins, their output may not appear in the exported ODT document: those plugins must be modified to support the ODT output format. However, some plugins already support it.

See ODT render support for the list of plugins which already support export to ODT. On that page you can also add plugins to the list of plugins for which you wish ODT export to be supported.

Translations

The plugin is translated into English, German, Danish, French, Korean, Dutch and Japanese. Thanks a lot to the translators, new languages are very welcome!

Please use the DokuWiki Localization Tool.

Bugs

To report bugs or suggest features, please use GitHub Issues. The author does not monitor this page.

Tutorials/more Documentation

1)
In /lib/tpl/default/main.php, there are two divs that contain some buttons: <div class="bar" id="bar__top"> and <div class="bar" id="bar__bottom">. Just insert the HTML code inside one of the two divs (left or right)
plugin/odt.txt · Last modified: 2024-03-06 12:22 by thomas-schaefer-nh

Except where otherwise noted, content on this wiki is licensed under the following license: CC Attribution-Share Alike 4.0 International
CC Attribution-Share Alike 4.0 International Donate Powered by PHP Valid HTML5 Valid CSS Driven by DokuWiki