Skip to content

Document Iterations

Overview

OpenReport enables batch document creation. To initiate a document loop a "document_loop" instance is required, which specifies the loop settings and creates similar document fixed number of times. Loop can be set manually or can be obtained using the "source" instance.

Back to homepage

Manual

This specification declares a document loop with iterator "country" using "iterator_name" property. The "iterator_type" property specifies the method the iterator is set: "manual" or "source". With "manual" the iterator is specified manually using "iterator_values" property.

document_loop:
  iterator_name: country
  iterator_type: manual
  iterator_values: [Germany, France]
  iterator_applicable: 
    - document:
      # ...
The "iterator_applicable" instance lists an OpenReport "document" instance with all its components. Current value of iterator is accessible with @iterator{iterator_name} format. With every next iteration the @iterator{country} value will change to the next item of "iterator_values" list and a new document will be created.

Document Iterator usage

This specification declares iterator (country) with manually specified values [Germany, France].

document_loop:
  iterator_name: country
  iterator_type: manual
  iterator_values: [Germany, France]
  iterator_applicable: 
    - document:
        name: @iterator{country}_sales_report.docx
        structure:
          - heading: 
              body: @iterator{country}
          - text: 
              body: "The figure below shows sales per month for @iterator{country}:"
          - figure:
              source:
                output: figure
                source_type: python
                python_executable: plot_sales_per_year
                country_name: @iterator{country}
The outcome of this specification are two documents (Germany_sales_report.docx and France_sales_report.docx). Each document has:

  • a heading specifying the country name
  • a text
  • a figure generated by user-defined function 'plot_sales_per_year' with input parameter 'country_name'.

The example of output for Germany is: Figure

The example of output for France is: Figure

Source

This specification declares a document loop with iterator "country" using "iterator_name" property. The "iterator_type" property specifies the method the iterator is set: "manual" or "source". With "source" the iterator values are an output of "source" instance.

document_loop:
  iterator_name: country
  iterator_type: source
  source:
      output: array
      source_type: python
      python_executable: list_of_countries 
  iterator_applicable: 
    - document:
      # ...
The "iterator_applicable" instance lists an OpenReport "document" instance with all its components. Current value of iterator is accessible with @iterator{iterator_name} format. With "source" the values of the iterator are an output of user-defined function 'list_of_countries'. With every next iteration the @iterator{country} value will change to the next item of "source" output and a new document will be created.

Document Iterator usage

This specification declares iterator (country) and uses "source" instance to obtain iterator values. 

document_loop:
  iterator_name: country
  iterator_type: source
  source:
      output: array
      source_type: python
      python_executable: list_of_countries 
  iterator_applicable: 
    - document:
        name: @iterator{country}_sales_report.docx
        structure:
          - heading: 
              body: @iterator{country}
          - text: 
              body: "The figure below shows sales per month for @iterator{country}:"
          - figure:
              source:
                output: figure
                source_type: python
                python_executable: plot_sales_per_year
                country_name: @iterator{country}
If list_of_countries outputs [Germany, France], the outcome of this specification are two documents (Germany_sales_report.docx and France_sales_report.docx). Each document has:

  • a heading specifying the country name
  • a text
  • a figure generated by user-defined function 'plot_sales_per_year' with input parameter 'country_name'.

The example of output for Germany is: Figure

The example of output for France is: Figure

Back to homepage

Required properties

Required properties for "loop" instance is "iterator_name", "iterator_type", "iterator_applicable" and depending on "iterator_type" value either "iterator_values": 

document_loop:
    iterator_name: 
    iterator_type: manual
    iterator_values:
    iterator_applicable: 
      - document:
        # ...

Or "source": 

document_loop:
    iterator_name: 
    iterator_type: source
    source:
      # ...
    iterator_applicable: 
      - document:
        # ...

Back to top

Back to homepage