====== LibreOffice / OpenOffice Export ====== ---- plugin ---- description: Exports a page to the Open Document Format (ODF) used by LibreOffice and other word processors author : Andreas Gohr, Aurélien Bompard, Florian Lamml, Lars (LarsDW223) email : andi@splitbrain.org, aurelien@bompard.org, info@florian-lamml.de type : render, syntax lastupdate : 2023-03-03 compatible : Detritus, 2016-06-26 "Elenor Of Tsort", 2017-02-19a "Frusterick Manners", "Greebo", Hogfather, "Jack Jackrum" depends : conflicts : header2 similar : tags : export, odt, pdf downloadurl: https://github.com/lpaulsen93/dokuwiki-plugin-odt/archive/refs/tags/2023-03-03.zip sourcerepo : https://github.com/LarsGit223/dokuwiki-plugin-odt bugtracker : https://github.com/LarsGit223/dokuwiki-plugin-odt/issues donationurl: screenshot_img : https://github.com/LarsGit223/dokuwiki-plugin-odt/raw/master/odt.png ---- This plugin allows you to export a page to the [[wp>OpenDocument]] format used by [[http://www.libreoffice.org/|LibreOffice]], [[http://www.openoffice.org/|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 [[andi@splitbrain.org|Andreas Gohr]], and was then further developed and maintained by [[http://aurelien.bompard.org/|Aurelien Bompard]]. The older version of ODT plugin with default template support is from [[http://www.florian-lamml.de/|Florian Lamml]]. Currently, the ODT plugin is maintained by [[https://github.com/LarsGit223/dokuwiki-plugin-odt|LarsDW223]]. ===== Requirements ===== ==== PHP ==== PHP 5.5 (for PHP 5.3.3+ and PHP 5.4.X, see [[https://github.com/LarsGit223/dokuwiki-plugin-odt/issues/96|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 [[plugin:bookcreator|Bookcreator Plugin]] too. * Pagebreak: to be able to insert pagebreaks manually you need to install the [[plugin:pagebreak|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 template((In ''/lib/tpl/default/main.php'', there are two divs that contain some buttons: ''%%
%%'' and ''%%
%%''. Just insert the HTML code inside one of the two divs (left or right) ))
Or use this for a simple 16x16 icon somewhere in your template: ODT Export You can mix the 2 previous methods, and get a button with an image inside, with this code:
===== 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): - syntax tag - URL request parameter - ODT plugin configuration setting - 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 [[plugin:usecounter|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 [[plugin:wrap|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 ‘[[config: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 '''' in the wiki page. This feature requires the [[plugin:pagebreak|Pagebreak Plugin]]. > [[;plugin:pagebreak | The PageBreak plugin]] isn't maintained, and [[https://github.com/micgro42/dokuwiki-plugin-pagebreak/issues | bugs]] are ignored since 2018! Tag ''
'' is broken, ''
'' may be better? ''$renderer->doc .= "
";''. 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. ==== disablelinks/enablelinks ==== 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 ''...'' 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 [[plugin:odt:frames|details on using ODT frames]] for more information. FIXME: create page, describe frame usage in detail FIXME ===== Development ===== Changes: Latest Release: {{rss>https://github.com/LarsGit223/dokuwiki-plugin-odt/commits//2019-07-27.atom}} Development master branch: {{rss>https://github.com/LarsGit223/dokuwiki-plugin-odt/commits/master.atom}} Release 20101030 with Default Template Support: [[https://github.com/LarsGit223/dokuwiki-plugin-odt/archive/2014-02-10.zip|dokuwiki-odt-20140210]].\\ More older releases are available [[http://aurelien.bompard.org/projects/files/dokuwiki-odt/|on this webpage]]. If you are a developer which is interested in implementing ODT support for a plugin the following pages might be interesting for you: * [[plugin:odt:implementodtsupport|Implement ODT support]] * [[plugin:odt:csscolorshelper|CSSColorsHelper]] * [[plugin:odt:cssimporthelper|CSSImportHelper]] ==== Preview ==== To get some information about the current development release/master branch, have a look at the [[plugin:odt:development|development preview]] page. ===== Customizing ===== There are three ways of customizing how the output will look like : - Modify an export of the ''wiki:syntax'' page: * Export the [[wiki:syntax|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. - 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. - 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 **[[plugin:odt:rendersupport|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 [[http://translate.dokuwiki.org/plugin/odt|DokuWiki Localization Tool]]. ===== Bugs ===== To report bugs or suggest features, **please** use [[https://github.com/LarsGit223/dokuwiki-plugin-odt/issues|GitHub Issues]]. The author does not monitor this page. ===== Tutorials/more Documentation ===== For some more detailed examples and documentation have a look at the following pages: * [[plugin:odt:tutorials:toc|Table of Contents Tutorial]] * [[plugin:odt:tutorials:odttemplate:create|Create an ODT template file Tutorial]] * [[plugin:odt:tutorials:odttemplate:stylingnormaltext|ODT template: styling normal text Tutorial]] * [[plugin:odt:tutorials:odttemplate:stylingheadlines|ODT template: styling headlines Tutorial]] * [[plugin:odt:tutorials:odttemplate:stylingtextextended|ODT template: extended text styling Tutorial]] * [[plugin:odt:tutorials:odttemplate:stylinglists|ODT template: list styling Tutorial]] * [[plugin:odt:styleimportgeneral|A general description of ODT style import]] * [[plugin:odt:cssimportparagraphstyle|A description of CSS import for paragraph styles]] * [[plugin:odt:cssimportcharacterstyle|A description of CSS import for character styles]]