Difference between revisions of "Report API"

From Gramps
Jump to: navigation, search
m
(Text document API)
(23 intermediate revisions by 8 users not shown)
Line 1: Line 1:
{|style="width:90%;margin-top:+.7em;margin-bottom:+.7em;background-color: #c0f0ff;border:1px solid #ccc; padding: 5px" align="center"
+
{{Out of date}}
|-
 
|[[Image:Gnome-important.png]]
 
| align="left" style="font-size:150%" |
 
This is still a draft. Please don't link to it yet!
 
|}
 
  
In GRAMPS there are six different types of reports.
+
In Gramps there are five different types of reports.
 
* Text report
 
* Text report
 
* Graphical report
 
* Graphical report
* Book report
+
* Graph
* Code generators
+
* Book
* Web page generator
+
* Web pages
* View only report
+
Only Text reports, Graphical reports and Graphs use the Report (Document) API, since Web reports write their output directly into files, while Book reports are simply combination of Text reports and Graphical reports.
Only Text reports and Graphical reports use the Report (Document) API, since the latter three directly write their output into file(s) or onto the screen, while Book reports are simply combination of Text reports and Graphical reports.
 
  
 
==Common API==
 
==Common API==
At the moment the combination of textual and graphical elements within one document is not supported (for future plans refer to [[Report API redesign]]), thus Text and Graphical reports are implemented via separate APIs, though they have a common part.
+
At the moment the combination of textual and graphical elements within one document is not supported (for future plans refer to Report API redesign), thus Text and Graphical reports are implemented via separate APIs, though they have a common part.
This common part is implemented in the [http://www.gramps-project.org/api3/BaseDoc.BaseDoc-class.html BaseDoc class], which contains among others basic document opening, closing, and stylesheet handling methods. It also stores the physical description of a page (sheet of paper in print).
+
This common part is implemented in the [http://www.gramps-project.org/docs/gen/gen_plug.html#gen.plug.docgen.basedoc.BaseDoc BaseDoc class], which contains among others basic document opening, closing, and stylesheet handling methods. It also stores the physical description of a page (sheet of paper in print).
  
 
'''Note!''' The <tt>BaseDoc.open</tt> and the <tt>BaseDoc.close</tt> methods have to be implemented by the subclassed document generators.
 
'''Note!''' The <tt>BaseDoc.open</tt> and the <tt>BaseDoc.close</tt> methods have to be implemented by the subclassed document generators.
  
 
===Page===
 
===Page===
Description of the paper, which every report will be rendered on, is stored by an instance of the [http://www.gramps-project.org/api3/BaseDoc.PaperStyle-class.html PaperStyle class]. This instance is available via the <tt>BaseDoc.paper_style</tt> class attribute. The chosen PaperStyle is given to the document generator at initialization, and is handled by the reporting framework.
+
[[Image:Doc_paper.png|right|thumb|400px]] Description of the paper, which every report will be rendered on, is stored by an instance of the [http://www.gramps-project.org/docs/gen/gen_plug.html#gen.plug.docgen.paperstyle.PaperStyle PaperStyle class]. This instance is available via the <tt>BaseDoc.paper_style</tt> class attribute. The chosen PaperStyle is given to the document generator at initialization, and is handled by the reporting framework.
  
Text reports do not need to care about paper properties, as the document generator (or the external viewer) paginates the report according to those properties. While, on the other hand, graphical reports do need to take paper properties into account when creating graphical elements.
+
The <tt>PaperStyle</tt> holds information on the size of the paper ([http://www.gramps-project.org/docs/gen/gen_plug.html#gen.plug.docgen.paperstyle.PaperStyle PaperSize class] instance), the size of the margins, and the orientation of the paper. Use the proper accessor methods to get the values. To get the metrics of the usable area of a paper (page without the margins) one can also use the [http://www.gramps-project.org/docs/gen/gen_plug.html#gen.plug.docgen.paperstyle.PaperStyle.get_usable_width PaperStyle.get_usable_width] and [http://www.gramps-project.org/docs/gen/gen_plug.html#gen.plug.docgen.paperstyle.PaperStyle.get_usable_height PaperStyle.get_usable_height] convenience methods. Width and height are always given according to the orientation of the paper, thus width is always the horizontal, and height is always the vertical dimension.
[[Image:gramps-devel.png|left|22px]] ''document generator should hide paper properies for graphical reports too'' <br/>
+
 
 +
Text reports do not need to care about paper properties, as the document generator (or the external viewer) paginates the report according to those properties. While, on the other hand, graphical reports do need to take paper properties into account when creating graphical elements, i.e. they should not draw on the margins.
 +
<!--[[Image:gramps-devel.png|left|22px]] ''document generator should hide paper properies for graphical reports too''-->
 +
 
 +
The origin of the coordinate system is the top left corner of the usable area.
 +
 
 +
{{-}}
  
 
==Text document API==
 
==Text document API==
  
==Graphical document API==
+
The specification of the Textdoc API is [https://pythonhosted.org/Gramps/gen/gen_plug.html#gramps.gen.plug.docgen.textdoc.TextDoc here]
 +
 
 +
The interface for adding media objects is as follows:
 +
 
 +
<pre>
 +
add_media_object(name, align, w_cm, h_cm, alt='', style_name=None, crop=None)[source]
 +
 
 +
    Add a photo of the specified width (in centimeters).
 +
    Parameters:
 +
 
 +
        name – filename of the image to add
 +
        align – alignment of the image. Valid values are ‘left’, ‘right’, ‘center’, and ‘single’
 +
        w_cm – width in centimeters
 +
        h_cm – height in centimeters
 +
        alt – an alternative text to use. Useful for eg html reports
 +
        style_name – style to use for captions
 +
        crop – image cropping parameters
 +
</pre>
 +
 
 +
Note that because of the structure of these documents, Images are only allowed as children (i.e. following) Document or Cell.
 +
 
 +
This interface is used in the following reports:
 +
 
 +
{| {{Prettytable}}
 +
|-
 +
! Report
 +
! Built-in
 +
! align
 +
! style_name
 +
! how called
 +
|-
 +
| Detailed Ancestral Report
 +
| Built-in
 +
| right
 +
| DDR-Caption
 +
| via gen/plug/report/utils.py
 +
|-
 +
| Detailed Descendant Report
 +
| Built-in
 +
| right
 +
| DDR-Caption
 +
| via gen/plug/report/utils.py
 +
|-
 +
| Individual Complete Report
 +
| Built-in
 +
| right
 +
| None
 +
| direct
 +
|-
 +
| Book (Title Page)
 +
| Built-in
 +
| center
 +
| None
 +
| direct
 +
|-
 +
| Person Everything
 +
| Addon
 +
| single
 +
| PE-Level%d
 +
| direct
 +
|-
 +
|}
 +
 
 +
None of the reports use 'alt'. It is understood (from looking at the code in odfdoc.py) that '''left''' and '''right''' alignment should cause the text to wrap around the media object, while for '''single''' alignment, there should be no text on either side of the media object.
 +
 
 +
Since style_name should be used as the style for the caption (i.e. the '''alt''' string) it should also be used for the image itself. Otherwise the caption would not be below the picture.
 +
 
 +
As at December 2014, output appears as follows:
 +
 
 +
{| {{Prettytable}}
 +
|-
 +
! Format
 +
! right
 +
! center
 +
! single
 +
|-
 +
| HTML
 +
| '''OK''' Picture on right, text wrapped round it
 +
| ?
 +
| Picture on left margin, text not wrapped
 +
|-
 +
| RTF
 +
| Picture on left margin, text not wrapped
 +
| ?
 +
| '''OK''' Picture aligned with previous paragraph, text not wrapped
 +
|-
 +
| ODF
 +
| '''OK''' Picture on right, text wrapped round it
 +
| ?
 +
|  Picture centred, text not wrapped
 +
|-
 +
| PDF
 +
| Picture on right, text not wrapped
 +
| ?
 +
| Picture on left margin, text not wrapped
 +
|-
 +
|}
 +
 
 +
==Draw document API==
 +
 
 +
==Graph document API==
 +
 
 +
[[Category:Developers/Reference]]
 +
[[Category:GEPS|R]]
 +
[[Category:Plugins]]
 +
[[Category:Reports|A]]

Revision as of 03:42, 6 August 2015

Gramps-notes.png This page's factual accuracy may be compromised due to out-of-date information. Please help improve the Gramps Wiki as a useful resource by updating it.

In Gramps there are five different types of reports.

  • Text report
  • Graphical report
  • Graph
  • Book
  • Web pages

Only Text reports, Graphical reports and Graphs use the Report (Document) API, since Web reports write their output directly into files, while Book reports are simply combination of Text reports and Graphical reports.

Common API

At the moment the combination of textual and graphical elements within one document is not supported (for future plans refer to Report API redesign), thus Text and Graphical reports are implemented via separate APIs, though they have a common part. This common part is implemented in the BaseDoc class, which contains among others basic document opening, closing, and stylesheet handling methods. It also stores the physical description of a page (sheet of paper in print).

Note! The BaseDoc.open and the BaseDoc.close methods have to be implemented by the subclassed document generators.

Page

Doc paper.png

Description of the paper, which every report will be rendered on, is stored by an instance of the PaperStyle class. This instance is available via the BaseDoc.paper_style class attribute. The chosen PaperStyle is given to the document generator at initialization, and is handled by the reporting framework.

The PaperStyle holds information on the size of the paper (PaperSize class instance), the size of the margins, and the orientation of the paper. Use the proper accessor methods to get the values. To get the metrics of the usable area of a paper (page without the margins) one can also use the PaperStyle.get_usable_width and PaperStyle.get_usable_height convenience methods. Width and height are always given according to the orientation of the paper, thus width is always the horizontal, and height is always the vertical dimension.

Text reports do not need to care about paper properties, as the document generator (or the external viewer) paginates the report according to those properties. While, on the other hand, graphical reports do need to take paper properties into account when creating graphical elements, i.e. they should not draw on the margins.

The origin of the coordinate system is the top left corner of the usable area.


Text document API

The specification of the Textdoc API is here

The interface for adding media objects is as follows:

 add_media_object(name, align, w_cm, h_cm, alt='', style_name=None, crop=None)[source]

    Add a photo of the specified width (in centimeters).
    Parameters:	

        name – filename of the image to add
        align – alignment of the image. Valid values are ‘left’, ‘right’, ‘center’, and ‘single’
        w_cm – width in centimeters
        h_cm – height in centimeters
        alt – an alternative text to use. Useful for eg html reports
        style_name – style to use for captions
        crop – image cropping parameters

Note that because of the structure of these documents, Images are only allowed as children (i.e. following) Document or Cell.

This interface is used in the following reports:

Report Built-in align style_name how called
Detailed Ancestral Report Built-in right DDR-Caption via gen/plug/report/utils.py
Detailed Descendant Report Built-in right DDR-Caption via gen/plug/report/utils.py
Individual Complete Report Built-in right None direct
Book (Title Page) Built-in center None direct
Person Everything Addon single PE-Level%d direct

None of the reports use 'alt'. It is understood (from looking at the code in odfdoc.py) that left and right alignment should cause the text to wrap around the media object, while for single alignment, there should be no text on either side of the media object.

Since style_name should be used as the style for the caption (i.e. the alt string) it should also be used for the image itself. Otherwise the caption would not be below the picture.

As at December 2014, output appears as follows:

Format right center single
HTML OK Picture on right, text wrapped round it ? Picture on left margin, text not wrapped
RTF Picture on left margin, text not wrapped ? OK Picture aligned with previous paragraph, text not wrapped
ODF OK Picture on right, text wrapped round it ? Picture centred, text not wrapped
PDF Picture on right, text not wrapped ? Picture on left margin, text not wrapped

Draw document API

Graph document API