HOWTO - Sashipa development

Print reports.

You'll find here theorical notions for understanding print reports in Sashipa.

How to use a print report

Print reports are defined in the optional element printReportSet. The element printReportSet is between elements graphicalUserInterface.formSet and defaultParameterSet. Example :

...  </formSet>

<printReportSet>

  <printReport name='PRreport1'>
    <!-- ... -->
  </printReport>
  <printReport name='PRreport2'>
    <!-- ... -->
  </printReport>

</printReportSet>

<defaultParameterSet ...

Then print reports can be added in listForms. They will be available from listForms popup menu. Here is the code:

  <listForm db='dbContact' ='SCContactAdresse' delete='yes'>
    ...
    ... insertScreen ...
    <printReportList>
      <printReportRef printReport='PRreport1' />
    </printReportList>
  </listForm>

Print report skeleton: the printReport element

Here is the print report skeleton:

<printReport name='PRreportExample'>
  <pageFormat format='A4' orientation='portrait' />
  <pageImageableArea x='30' y='45' w='535' h='752'
                     relativeLocation='yes' />

  <caption>Example of print report</caption>

  <pageHeader height='20'>
    <xxxDrawFigure> ... </xxxDrawFigure>
  </pageHeader>

  <pageContent>
    <xxxDistribution>

      ... specific content for distribution ...

      <dataRecordPrinter>
        <xxxDrawFigure>
          ...
        </xxxDrawFigure>
        <printerDataSource>
          ...
        </printerDataSource>
      </dataRecordPrinter>
    </xxxDistribution>
  </pageContent>

  <pageFoot height='13'>
    <xxxDrawFigure> ... </xxxDrawFigure>
  </pageFoot>
</printReport>

First is the page format. Orientation ('portrait' or 'landscape') is specified. The format attribute can be replaced by manual size (w='XXX' h='XXX'). Using format='A4' (210mm * 297mm) is equivalent to specify w='595' h='842'. Be carefull: we have to use a strange american measure, and all coordinates must be in this measure.

The second element is the drawing area. The attribute relativeLocation='yes' means that the location (0; 0) is the top left corner of the drawing area (and not of the page).

For printing in landscape mode, just set orientation='landscape' in the pageFormat element. Be carefull: do not modify content of pageImageableArea or attributes (w, h) in the pageFormat element. Values x, y and width, height are automatically reversed.

The element caption contains the displayed label in listForm popup menus.

Elements pageHeader and pageFoot are optional.

The element pageContent contains a distribution element.

The distribution element often contains a dataRecordPrinter, which will create one instance of its drawFigure for each data row. So the drawFigure element contains all graphical components for drawing a data row. Data rows are selected in the printerDataSource element.

Three distribution elements are available. We can look at them now.

Distributions

The distribution element computes figure bounds. Figures are created for each data row. Three distributions are available:

listDistribution locates figures vertically one after others, from top to bottom.
mailingDistribution locates figures on mailing labels, from left to right and then from top to bottom.
singleRecordDistribution is used only when there is one single figure to draw (case of only one data row).

A distribution element locates figures. A figure is created from a data row, by a drawFigure element. We can look on available drawFigures now.

DrawFigures

A DrawFigure creates a figure from a data row (or a data value). Here is an exhaustive list:

textDrawFigure draws (in textual mode) the value for an instanceColumn in the current data row.
staticTextDrawFigure draws a hardcoded text.
predefinedDrawFigure draws an automatic value, like the numero of the page (type='pageNumero').
lineDrawFigure draws a segment.
gapDrawFigure draws nothing, but it's like if a rectangle has been drown.
serieDrawFigure contains a serie of sub-drawFigures. Sub-drawFigures can be vertically aligned (locations='relativeVertical'), or horizontally aligned (locations='relativeHorizontal'), or can have absolute locations (locations='absolute'). NB: when absolute locations are used, sub-drawFigures have to appear by ascendent 'y' values.
switchDrawFigure contains a s�rie of sub-drawFigure too, but displays only the first figure that displays anything.
listDistributionDrawFigure contains a listDistribution (cf pageContent element). The sub-listDistribution can contains its own data source, that uses as filter the primary key of the current row.
singleRecordDistributionDrawFigure contains a singleRecordDistribution (cf pageContent element). Same remarks that about the listDistributionDrawFigure, but the data source has to return only one single row.

All drawFigures have optional attributes 'x' et 'y'. Except for listDistributionDrawFigure and singleRecordDistributionDrawFigure, all drawFigures have optional attributes 'maxWidth' and 'maxHeight' too.

printerDataSource

The printerDataSource element is a data row provider for a distribution element.

A print report is built from a listForm. So it can work on the current select query using by the listForm. A print report has to work with the listForm select query, in order to display the same data.

A printerDataSource contains a selectQuery or a selectQueryBuilder or nothing:

A selectQuery is a static query. When a printerDataSource contains a selectQuery, the query can completly replace (mode='replace') the listForm query (so the listForm query will be ignored). Or the query can be merged (mode='merge', it's also the mode by default) with the listForm query: redefined statements replace those of the listForm query, and missing statements are taken in the listForm query. More often, WHERE and ORDER BY statements will be taken in the listForm query for displaying same data in the same order.
When a printerDataSource contains a selectQueryBuilder, mode is necessary 'replace'. A selectQueryBuilder builds a selectQuery from the current filter.
When a printerDataSource contains nothing, mode is necessary 'dispatchParentValues'. Here the printerDataSource returns data that it has received.

We can see an example with selectQuery:

  <printerDataSource mode='merge'>
    <selectQuery db='dbDemo' distinctRequired='no'>
      <selectStatement>
        <instancePk>
          <instanceTable schemaTable='tblContactaddress' />
        </instancePk>
        <instanceColumnList>
          <instanceColumn schemaColumn='tblContact_Contactname' />
          <instanceColumn schemaColumn='tblContact_Contactfirstname' />
          <instanceColumn schemaColumn='tblContactaddress_Addressrue' />
          <instanceColumn schemaColumn='tblContactaddress_Addresspostcode' />
          <instanceColumn schemaColumn='tblContactaddress_Addresscity' />
        </instanceColumnList>
      </selectStatement>
      <fromStatement>
        <mainInstanceTable schemaTable='tblContactaddress' />
        <fkJoin join='inner'>
          <instanceFk schemaFk='fk_tblContactaddress_tblContact' />
        </fkJoin>
      </fromStatement>
    </selectQuery>
  </printerDataSource>

Remark: the default mode for printerDataSource with selectQuery is 'merge'. So we write it here for the example, but it's not required.

Choosing a staticRecordPrinter

Come back on a sentence: "The distribution element often contains a dataRecordPrinter". Often but not always...

We can prefer an element staticRecordPrinter that draws a single figure, independent of the listForm data rows. It can be used for creating column titles that will be displayed only on the first page.

Example:

<printReport name='PRreportExample'>
  <pageFormat format='A4' orientation='portrait' />
  <pageImageableArea x='30' y='45' w='535' h='752' 
                     relativeLocation='yes' />

  <caption>Example of print report</caption>

  <pageContent>
    <singleRecordDistribution>

      <staticRecordPrinter>
        <serieDrawFigure locations='absolute' atomic='no'
                         visibleAsChild='drawData'>

          ... many elements 'staticTextDrawFigure' for drawing title columns ...

          <listDistributionDrawFigure name='drawData' y='26'>
            <listDistribution>
              ...
            </listDistribution>
          </listDistributionDrawFigure>

        </serieDrawFigure>

    </singleRecordDistribution>
  </pageContent>
</printReport>

Remarks:

The attribute visibleAsChild specifies when the serieDrawFigure has to be visible. If it wasn't specified, there will be always a page to print, even with an empty list.
The attribute (atomic='no') is important. It means a page break can happen between two child figures. Otherwise you will have an error when printing a list bigger than a page.

Top