.. _doc-reports:

#######################
 Documents and Reports
#######################

Generate documents
==================

Generating reports and documents is an important part of any application.
Python and Qt provide various ways to generate documents.  Each of them
with its own advantages and disadvantages.  

  +-----------------------+-------------------------+--------------------------+
  | Method                | Advantages              | Disadvantages            |
  +-----------------------+-------------------------+--------------------------+
  | PDF documents through | * Perfect control over  | * Relatively steep       |
  | reportlab             |   layout                |   learning curve         |
  |                       | * Excellent for mass    | * User cannot edit       |
  |                       |   creation of documents |   document               |
  +-----------------------+-------------------------+--------------------------+
  | HTML                  | * Easy to get started   | * Not much layout control|
  |                       | * Print preview within  | * User cannot edit       |
  |                       |   Camelot               |   document               |
  |                       | * No dependencies       |                          |
  +-----------------------+-------------------------+--------------------------+
  | Docx Word documents   | * User can edit         | * Proprietary format     |
  |                       |   document              | * Word processor needed  |
  +-----------------------+-------------------------+--------------------------+
  
Camelot leaves all options open to the developer.

Please have a look at :ref:`tutorial-reporting` to get started with generating
documents.

Generating a document or report is nothing more than yielding the appropriate
action step during the :meth:`model_run` method of an :class:`Action`.

Action steps usable for reporting are :

  * :class:`camelot.view.action_steps.print_preview.PrintPreview`
  * :class:`camelot.view.action_steps.print_preview.PrintHtml`
  * :class:`camelot.view.action_steps.print_preview.PrintJinjaTemplate`
  * :class:`camelot.view.action_steps.open_file.OpenFile`
  * :class:`camelot.view.action_steps.open_file.OpenStream`
  * :class:`camelot.view.action_steps.open_file.OpenJinjaTemplate`

HTML based documents
====================

.. literalinclude:: ../../../../test/test_action.py
   :start-after: begin html print
   :end-before: end html print
   
The supported html subset is documented here :

http://doc.qt.nokia.com/stable/richtext-html-subset.html

Alternative rendering
---------------------

Instead of :class:`QtGui.QTextDocument` another html renderer such as 
:class:`QtWebKit.QWebView` can be used in combination with the 
:class:`camelot.view.action_steps.print_preview.PrintPreview` action step.  The
:class:`QWebView` class has complete support for html and css.

.. literalinclude:: ../../../../test/test_action.py
   :start-after: begin webkit print
   :end-before: end webkit print

Docx based documents
====================

Create a template document with MS Office
-----------------------------------------

Create a document using MS Office and with some placeholder text
on places where you want to insert data.

.. image:: /_static/template_document_word.png
   
And save it as an xml file :

.. image:: /_static/template_document_word_save_as.png

Clean the XML generated by MS Office
------------------------------------

The XML file generated by MS Office can be cleaned using **xmllint**::

	xmllint --format template.xml > template_clean.xml
	
Replace the placeholders
------------------------

The template will be merged with the objects in the selection using jinja,
where the object in the selection will be available as a variable named
**obj** and the time of merging the document is available as **now**: