wiki:TracWikiPrintPlugin

Version 5 (modified by airadier, 6 years ago) (diff)

--

WikiPrint Trac Plugin

Description

Make wiki pages easily printable, exporting to PDF (book or article format) or printable HTML format (page contents without trac headers/footers).

PDF export is based on xhtml2pdf/PISA pure python libraries, instead of depending on an external application.

WikiPrint features:

  • Fully customizable header/footers for PDF
  • Syntax highlighting in exported format, using pygments
  • Customizable front page for PDF book format
  • Automatic creation of Table of Contents if [[PageOutline]] Macro is used

The style of the resulting PDF or HTML can be fully customized using CSS files.

Usage instructions

First, install the plugin as usual.

Enable the plugin by adding wikiprint.* = enabled in the components section of the trac.ini file:

[components]
...
wikiprint.* = enabled

Additional options can be set by creating a wikiprint section:

[wikiprint]
toc_title = Table of Contents
#CSS and content files (or URLS, using http://...)
css_url = c:/path/to/file.css
article_css_url = c:/path/to/article.css
book_css_url = c:/path/to/book.css
frontpage_url = c:/path/to/frontpage.html
extracontent_url = c:/path/to/extracontent.html

Most of these options can be also set from the web administrative interface.

WikiPrint works by converting one or some Wiki pages to HTML, adding some CSS styles and replacing special tags, and then passing the output to the xhtml2pdf library, so in order to understand how to customize the output using CSS, and to use some special html tags used by xhtml2pdf, you'll have to check the xhtml2pdf manual.

Export formats

WikiPrint adds several download formats to the bottom of the wiki page. Following is the description of the available formats.

PDF Article

PDF article creates a PDF file out of the wiki page, with no front page. Additional styles will be used from the CSS file defined in article_css option.

If the page uses the [[PageOutline]] macro, it will be replaced by a Table of Contents.

PDF article can be used to combine several wiki pages too, from the administrative interface.

PDF Book

This format will create a book-like PDF document. A front page that can show title, subject, date and version is inserted at the beginning of the document. A 'Table of Contents' is also inserted after the front page. Any further ocurrences of [[PageOutline]] will be removed. Different wiki pages will be separated by a page break.

This is specially useful for combining several wiki pages from the administrative interface.

Printable HTML

This option will just convert to wiki text to HTML, and display it in the browser with some styles, so it can be printed directly from the browser.

Combining pages

When enabling the plugin, a new WikiPrint panel will be available in administration. From this panel, you can select a set of pages, and export them to any of the supported formats.

You can specify a Title, Subject, Date and Version for the exported document.

Tag replacement

When defining the contents of the front page file (using HTML), or the extra contents file (HTML for header, footer or other frames), some special tags can be used, and they will be replaced before exporting the document.

The following tags are supported:

  • #TITLE: Replaced with the Title field when combining pages from the administrative interface, or replaced with the Page Name when exporting from the wiki.
  • #SUBJECT: Replaced with the Subject field when combining pages from the administrative interface, or blank when exporting from the wiki.
  • #DATE: Replaced with the Date field when combining pages from the administrative interface, or the current time when exporting from the wiki.
  • #VERSION: Replaced with the Version field when combining pages from the administrative interface, or the current page version when exporting from the wiki.

Customizing styles

WikiPrint allows customization of documents by three different options:

  • css_url: A path or URL to a file with CSS styles that will be applied to the exported output. If left blank, a default CSS is used. If you are creating a custom CSS, use the default CSS as start, and change as needed. Some tweaking is needed in order to make xhtml2pdf/PISA library generate PDF correctly.
  • article_css_url: A path or URL to a file with CSS styles that will be used only when exporting to PDF Article format. The default one defines the page margins, and creates header and footer frames, which contents will be defined in the extracontent_url file.
  • book_css_url: A path or URL to a file with CSS styles that will be used only when exporting to PDF Book format. The default one defines the default page with no header or footer, which will be used for the front page, and a standard templage page, which will be used for successive pages, with header and footer.

For more information about the styles that affect the PDF output, see the xhtml2pdf manual.

Customizing front page, header, footer, contents

  • frontpage_url: A path or URL to a file with HTML (It doesn't have to be a well formed xhtml document, so don't include begin/end tags, body, etc., see the default one), that will be used as the front page when exporting to PDF Book. Some special tags can be used to insert the title, version, date, etc. See Tag Replacement
  • extracontent_url: A path or URL to a file with HTML that will be inserted at the beginning of the document before passing it to to xhtml2pdf. This should be used to define the contents of the header and footer. See xhtml2html documentation, and the default article CSS contents and default extra contents for an example.

Bugs/Feature Requests

Existing bugs and feature requests for TracWikiPrintPlugin are here.

If you have any issues, create a new ticket.

Download

Download the zipped source from here.

Source

You can check out TracWikiPrintPlugin from here using Subversion, or browse the source with Trac.

Recent Changes

[13287] by rjollos on 2013-06-14 23:33:20
Refs #10797: Bumped version to 1.9.3dev.
[13286] by rjollos on 2013-06-14 23:29:05
Fixes #10797: Update import of pisa to account for new module name. Thanks to charlie@… for the patch.
[13285] by rjollos on 2013-06-14 23:28:49
Refs #10797: Code cleanup: PEP-0008 changes, removed unused imports including unused import of pisa in web_ui.py. Removed Trac from install_requires, as this has been shown to cause problems (see #10607).

Author/Contributors

Author: airadier
Contributors:

Attachments (4)

Download all attachments as: .zip