Kexi/Plugins/Reports/Fileformat

Types

• pt: double value in points (pt), example: "12.5pt
• string, eg. "foo"
• int: eg. 7
• double: eg. 1.23
• color: eg. "#fab019"

Structure of KOReport XML

KOReport provides an XML string which can be embedded inside another file. This is to allow the parent application to supply the data for the report separately from KOReport itself.

The Kexi report plugin embeds the KOReport XML inside its own format, consisting of a root <kexireport> element, a <report:content> element from koreport and a <connection> element that describes the data for the report.

<report:content>

Contains top level parameters for the report describing the page setup, title and scripting. It also contains a <report:body> which describes the actual report structure.

<report:title>

Contains the human readable title for the report as a text node.

Attributes

• None

<report:script>

Contains the name of a script file that the parent program supplies. The script is executed whren the report is rendered.

Attributes

• report:script-interpreter : the interpreter used to execute the script, comes from Kross.

<report:grid>

Contains attributes describing how the grid is rendered in the report designer

Attributes

• report:grid-visible: boolean describing whether or not the grid is displayed.
• report:grid-divisions: integer number of minor divisions displayed in the grid.
• report:grid-snap: boolean describing whether or not thegrid snapping is enabled.
• report:page-units: 2 character string of the unit used (cm/pt/mm/in...) from kounit.

<report:page-style>

Denotes type of page used for the rendered report, options are predefined, custom or label and depending on the option used, certain attributes are used.

label is currently not handled and is undefined.

Legacy: text node child of the report:page-style element should be either:

• empty if fo:page-size == "Custom" or "Label"
• else, "predefined", in this case fo:page-size specifies name of page size such as "A4"

While reading, any other values of the text node should be ignored.

Attributes

Modeled after style:page-layout-properties 17.2 (ODF 1.2).

• report:
• fo:margin-top: top margin, type: pt
• fo:margin-bottom: bottom margin, type: pt
• fo:margin-left: left margin, type: pt
• fo:margin-right: right margin, type: pt
• report:print-orientation: either "portrait" or "landscape", type: string
• report:page-size: value of a predefined page size such as A4/Letter, or special value "custom". fo:page-width and fo:page-height should be referred for size when fo:page-size is "custom".
• fo:page-width, fo:page-height: width/height of the page, type: pt. Even if fo:page-size is predefined (eg "A4"), fo:page-width should be specified to make the format easier to convert to other formats. However, this property is not presented to the user in such cases.

<report:body>

Contains the actual report structure, split into sections, and a detail. There can be between 0 and 12 sections, and a single detail.

<report:section>

Is a container for report elements (labels/fields etc).

Attributes

• report:section type: describes where the sections appears on a report, possible values are:
  • header-page-first The header which would appear on the first page of the report. Overides any other **page header defined on the first page.
  • header-page-last The header which would appear on the last page of the report. Overides any other page **header defined on the last page.
  • header-page-odd The page header used on odd pages
  • header-page-even The page header used on even pages
  • header-page-any If no other header is defined then the 'any' header is used
  • footer-page-first As above for the page footer
  • footer-page-last As above for the page footer
  • footer-page-odd As above for the page footer
  • footer-page-even As above for the page footer
  • footer-page-any As above for the page footer
  • header-report Appears once at the beginning of the report, after the page header
  • footer-report Appears once at the end of the report, after any data, before the page footer.
  • header-group Appears at the beginning of a group section
  • footer-group Appears after a group section
  • detail Represents the detail of the report
• report:height Double value of the section height in points
• fo:background-color: Color of the section background, type: color

<report:detail>

Contains a single <report:section> of type 'detail', and 0 or many <report:group> sections.

Example file from kexi

<kexireport>                                                                                                                                                                    
<report:content xmlns:report="http://kexi-project.org/report/2.0" xmlns:fo="urn:oasis:names:tc:opendocument:xmlns:xsl-fo-compatible:1.0" xmlns:svg="urn:oasis:names:tc:opendocument:xmlns:svg-compatible:1.0">                                                                                                                                                 
 <report:title>Report</report:title>                                                                                                                                           
 <report:script report:script-interpreter="javascript"/>                                                                                                                       
 <report:grid report:grid-divisions="4" report:grid-snap="1" report:page-unit="cm" report:grid-visible="1"/>                                                                   
 <report:page-style report:print-orientation="portrait" fo:margin-bottom="1.00cm" fo:margin-top="1.00cm" fo:margin-left="1.00cm" fo:margin-right="1.00cm" report:page-size="A4">predefined</report:page-style>                                                                                                                                                 
 <report:body>                                                                                                                                                                 
  <report:section svg:height="1.00cm" fo:background-color="#ffffff" report:section-type="header-page-first"/>                                                                  
  <report:section svg:height="1.00cm" fo:background-color="#ffffff" report:section-type="header-page-odd"/>                                                                    
  <report:section svg:height="1.00cm" fo:background-color="#ffffff" report:section-type="header-page-even"/>                                                                   
  <report:section svg:height="1.00cm" fo:background-color="#ffffff" report:section-type="header-page-last"/>                                                                   
  <report:section svg:height="1.00cm" fo:background-color="#ffffff" report:section-type="header-page-any"/>                                                                    
  <report:section svg:height="1.00cm" fo:background-color="#ffffff" report:section-type="header-report"/>                                                                      
  <report:section svg:height="1.00cm" fo:background-color="#ffffff" report:section-type="footer-report"/>                                                                      
  <report:section svg:height="1.00cm" fo:background-color="#ffffff" report:section-type="footer-page-first"/>                                                                  
  <report:section svg:height="1.00cm" fo:background-color="#ffffff" report:section-type="footer-page-odd"/>                                                                    
  <report:section svg:height="1.00cm" fo:background-color="#ffffff" report:section-type="footer-page-even"/>                                                                   
  <report:section svg:height="1.00cm" fo:background-color="#ffffff" report:section-type="footer-page-last"/>                                                                   
  <report:section svg:height="1.00cm" fo:background-color="#ffffff" report:section-type="footer-page-any"/>                                                                    
  <report:detail>                                                                                                                                                              
   <report:group report:group-sort="ascending" report:group-page-break="after-footer" report:group-column="id">                                                                
    <report:section svg:height="1.00cm" fo:background-color="#ffffff" report:section-type="group-header"/>                                                                     
    <report:section svg:height="1.00cm" fo:background-color="#ffffff" report:section-type="group-footer"/>                                                                     
   </report:group>                                                                                                                                                             
   <report:section svg:height="2.50cm" fo:background-color="#ffffff" report:section-type="detail">                                                                             
    <report:label report:name="label1" report:horizontal-align="left" svg:x="16cm" svg:width="1cm" svg:y="1cm" report:caption="Label" report:vertical-align="center" svg:height="1cm" report:z-index="0">                                                                                                                                                      
     <report:text-style fo:letter-spacing="0%" style:letter-kerning="true" fo:font-size="8" fo:foreground-color="#000000" fo:font-family="Bitstream Vera Sans" fo:background-color="#ffffff" fo:background-opacity="100%"/>                                                                                                                                    
     <report:line-style report:line-style="nopen" report:line-weight="1" report:line-color="#000000"/>                                                                         
    </report:label>                                                                                                                                                            
    <report:field report:name="field2" report:horizontal-align="left" report:item-data-source="" svg:x="14cm" svg:width="1cm" svg:y="1cm" report:vertical-align="center" svg:height="1cm" report:z-index="0">                                                                                                                                                    
     <report:text-style fo:letter-spacing="0%" style:letter-kerning="true" fo:font-size="8" fo:foreground-color="#000000" fo:font-family="Bitstream Vera Sans" fo:background-color="#ffffff" fo:background-opacity="100%"/>                                                                                                                                    
     <report:line-style report:line-style="nopen" report:line-weight="1" report:line-color="#000000"/>                                                                         
    </report:field>                                                                                                                                                            
    <report:text report:name="text3" report:horizontal-align="left" report:item-data-source="" svg:x="12cm" svg:width="1cm" svg:y="1cm" report:bottom-padding="0" report:vertical-align="center" svg:height="1cm" report:z-index="0">                                                                                                                            
     <report:text-style fo:letter-spacing="0%" style:letter-kerning="true" fo:font-size="8" fo:foreground-color="#000000" fo:font-family="Bitstream Vera Sans" fo:background-color="#ffffff" fo:background-opacity="100%"/>                                                                                                                                    
     <report:line-style report:line-style="nopen" report:line-weight="1" report:line-color="#000000"/>                                                                         
    </report:text>                                                                                                                                                             
    <report:line report:name="line4" svg:y1="0.9789cm" svg:x1="6.9849cm" svg:y2="1.9843cm" svg:x2="7.9904cm" report:z-index="0">                                               
     <report:line-style report:line-style="solid" report:line-weight="1" report:line-color="#000000"/>                                                                         
    </report:line>                                                                                                                                                             
    <report:barcode report:name="barcode5" report:horizontal-align="left" report:barcode-format="3of9" report:item-data-source="" svg:x="8.75cm" svg:width="2.75cm" svg:y="1cm" svg:height="1cm" report:barcode-max-length="5" report:z-index="0"/>                                                                                                              
    <report:image report:name="image6" report:item-data-source="" svg:x="5.5cm" svg:width="1cm" svg:y="1cm" report:resize-mode="clip" svg:height="1cm" report:z-index="0"/>      
    <report:chart report:title-x-axis="" report:antialiased="Antialiased" report:chart-color-scheme="default" svg:height="1cm" report:chart-sub-type="0" report:link-child="" report:three-dimensions="3D" report:chart-type="1" report:name="chart7" report:z-index="0" report:title-y-axis="" report:background-color="#ffffff" report:link-master="" report:data-source="" svg:x="3.5cm" svg:y="1cm" report:display-legend="1" svg:width="1cm"/>                                                                                            
    <report:check report:name="check8" report:item-data-source="" report:check-style="Cross" fo:foreground-color="#000000" svg:x="1cm" svg:width="1cm" svg:y="1cm" svg:height="1cm">                                                                                                                                                                             
     <report:line-style report:line-style="solid" report:line-weight="1" report:line-color="#000000"/>                                                                         
    </report:check>                                                                                                                                                            
   </report:section>                                                                                                                                                           
  </report:detail>                                                                                                                                                             
 </report:body>                                                                                                                                                                
</report:content>                                                                                                                                                              
<connection type="internal" source="addresses"/>                                                                                                                               
</kexireport>

TODOs

Based on Talk:Kexi/Plugins/Reports jstaniek 12:00, 18 December 2009 (PST)

Benefits

These have been proposed for to harmonize the format as much as possible with the ODF without doing any harm to readability.

Additional benefits:

• potentially easier compu/paste operations
• easier to write XSLTs or other conversions
• easier to promote the format since the known ans standarized naming and concepts are reused

Simple

• add xmlns:fo="urn:oasis:names:tc:opendocument:xmlns:xsl-fo-compatible:1.0" and xmlns:svg="urn:oasis:names:tc:opendocument:xmlns:svg-compatible:1.0" attrs to report:content
• report:foreground-color -> fo:foreground-color
• report:background-color -> fo:background-color
• report:background-opacity -> fo:background-opacity
  • make fo:background-opacity use format "0%".."100%" instead of 0..255
• report:vertical-alignment -> report:vertical-align
• report:horizontal-alignemnt -> report:horizontal-align
• do not add attributes if the value is empty (e.g. report:horizontal-alignment="" shouldn't be present) was a bug..it should always be present
• report:control-source -> report:data-source
  • (piggz) I disagree...data-source means the table/query/external data for the report, control source is the specific field for the control
  • so: report:column-name attr for table/query columns (harmonized, in ODF it is "text:column-name")
  • and for static text, skip the attr and use text data directly in the element, e.g. <report:label>foo</report:label>
  • and for builtin functions, use specific tags, eg. <report:label><report:row-number></report:label> displays row number in a label
  • and for script report, idea of element harmonized with ODF: use report:formula="..." and skip report:column-name
• report:margin-* -> fo:margin-top
• report:height -> svg:height; the same for width, x, y
  • express the values in cm and append "cm" to the values
• report:zvalue -> report:z-index
• report:name: for autogenerated names, use lower case, i.e. not "Field4" but "field4" for easier referencing from scripts in the future (and harmonized e.g. with the style of autogenerated names in Kexi forms)
• for <connection type="internal" source="addresses"/>
  • <report:data-source report:data-source-type="..." report:data-source-name="..."/>
• make items human-readable :
  • we already have report:label element, ok
  • replace field with report:text-box el. (similar to ODF)
  • use report:image el. for images, either static or with data source
    • TODO: later maybe draw:image from ODF?
  • use report:frame for static frames
  • use report:line for lines
  • use report:object for embedded objects (e.g. coming from plugins); enables extensibility
• Split qtFont to ODF-like font attributes; DONE (jstaniek 12 February 2010)

Complex

ODF-like automatic styles

• use ODF-like automatic styles and replace report:qtfont by referencing a style
  • probably for Kexi 3???

Current:

<report:field report:name="Field3" report:horizontal-align="left" report:control-source="town" report:vertical-align="center" report:z-index="0">                                                                                                      
    <report:rect svg:x="4.75cm" svg:width="1.75cm" svg:y="0.25cm" svg:height="0.4232cm"/>                                   
    <report:text-style fo:foreground-color="#000000" fo:background-color="#ffffff" report:qtfont="DejaVu Sans,9,-1,5,50,0,0,0,0,0" fo:background-opacity="100%"/>                                                                                         
    <report:line-style report:line-style="solid" report:line-weight="1" report:line-color="#000000"/>                       
   </report:field>   

New (harmonized):

<report:automatic-styles>
 <style:style style:name="S1" style:family="element">
   <style:graphic-properties report:fill="solid" report:fill-color="#ffffff" fo:opacity="100%" report:line-style="solid" 
    report:line-weight="1" report:line-color="#000000" report:horizontal-align="left" report:vertical-align="center" />
   <style:text-properties fo:color="#000000" fo:font-family="DejaVu" fo:font-size="9pt" fo:font-weight="bold"/>
 </style:style>
...
</report:automatic-styles>
<report:content> 
 <report:text-box report:name="Field3" report:control-source="town" report:z-index="0"
  svg:x="4.75cm" svg:width="1.75cm" svg:y="0.25cm" svg:height="0.4232cm" report:style-name="S1" />
...
</report:content> 

• What we did above:
  • report:rect is removed and its attrs are merged with the parent element
  • we created S1 style are references it in the box, thus making it possible to reuse the style
  • we created graphic-properties section of the style, reusing attrs from "15.14.1 Fill Style" and lines and alignment
  • we created text-properties section of the style to collect text-related attrivutes like color, font family, size, weight

• harmonize line styles with ODF; possible values:

<value>none</value>
<value>solid</value>
<value>dotted</value>
<value>dashed</value>
<value>dot-dashed</value>

Harmonization with ODF's text:database-display element

• Example: in order to display dynamic text "Page N of M", instead of writing scripting expressions, xml can be used:

<report:label>Page <text:report-page-number/> of <text:report-page-count/></report:label>

• we'll provide this capatibility anyway for ODF report type