Component generation

This page provides an overview of components generation functionality, including examples and details on required and optional properties.

Back to homepage

Overview

OpenReport allows to dynamically generate components using the "source" instance and incorporate any kind of user's own analysis directly in the desired place of the document. All the formatting is fixed and saved.

Additionally, "text" and "heading" components support AI-powered content generation using the "ai_prompt" property. The full AI content generation functionality is available at AI Content Generation.

Source

Each "source" instance can be listed under "sources" instance:

document:
  name: document.docx
  sources:
    - source:
      # ...
    - source:
      # ...

Or under its parent component:

- figure:
    source:
      # ...

Regardless of how many times within the OpenReport yaml file the "source" is specified, it will be generated only once, based on the "source" specifications (signature).

The "source" instance specifies the settings for generating "text", "table" and "figure" component within the "document".

- figure:
    source:
      output: figure
      source_type: local
      location: 'inputs/figure.jpg'

The "output" property indicates the type of component. The "source_type" specifies the component generation method: "local", "python" or "manual". Also, the "source" instance can specify the "parameter" and "loop" settings.

Required properties

Properties "output" and "source_type" are required regardless of "source_type" value.

Back to homepage

Local source

With "local" method the components is generated based on a locally stored file. On top of "source" required properties, property "location" is required.

Text

Text component can be generated based on a locally stored file:

- text:
    source:
      output: text
      source_type: local
      location: 'inputs/text.txt'

Figure

Figure component can be generated based on a locally stored file:

- figure:
    source:
      output: figure
      source_type: local
      location: 'inputs/figure.jpg'

Table

Table component can be generated based on a locally stored file:

- table:
    source:
      output: table
      source_type: local
      location: 'inputs/table.xlsx'

Parameter

Parameter values can be obtained from a locally stored file:

- parameter:
      parameter_name: city
      parameter_type: source
      source:
        output: text
        source_type: local
        location: 'inputs/parameter_values.txt'

The value of a parameter should be a string, therefore only locally stored text files are allowed. The full parameters functionality is available at Parameters.

Loop

The "source" instance can specify the settings for generating iterator values array for the "loop". The "source_type" specifies the array generation method: "local_table" or "local_text".

Local_text

With "local_text" method the array is generated based on a locally stored text file.

- loop:
    iterator_name: test
    iterator_type: source
    iterator_applicable:
      # ...
    source:
      output: array
      source_type: local_text
      location: 'inputs/iterator_values.txt'
      delimiter: ,

The "output" property specifies the type of instance to be generated: array. The "delimiter" property specifies the separator to use when splitting the string. Option 'next line' is applicable if delimiter is a new line.

Local_table

With "local_table" method the array is generated based on a "column_name" column of a locally stored table.

- loop:
    iterator_name: country
    iterator_type: source
    iterator_applicable:
      # ...
    source:
      output: array
      source_type: local_table
      location: 'inputs/table.xlsx'
      column_name: "Country"

The "output" property specifies the type of instance to be generated: array. The "column_name" property specifies a column name within a locally stored table. The "loop" iterator values are then all values of this column.

The full iterations functionality is available at Iterations.

Back to homepage

Python source

With "python" method the component is generated based on a python executable: function or class. With python mode any kind of user's own analysis can be incorporated directly in the desired place of the document. On top of "source" required properties, property "python_executable" is required.

To use python executables, the "imports" property must be specified at the document level pointing to a Python file that contains import statements of the user's functions. For the full setup guide, including schema generation and IDE autocomplete, see Import python executables.

Text

Text component can be generated using python executable: function or class.

- text: 
    source:
      output: text
      source_type: python
      python_executable: provide_sql_text
      review_source: Apple Store

The "output" property specifies the type of instance to be generated: text. The text is an output of user-defined function 'provide_sql_text' The inputs for the function can be specified directly under "source" instance: input parameter 'review_source' (Apple Store). This is equivalent to:

paragraph = provide_sql_text(review_source="Apple Store")

Figure

Figure component can be generated using python executable: function or class.

- figure:
    source:
      output: figure
      source_type: python
      python_executable: plot_signals
      timeframe: week

The "output" property specifies the type of instance to be generated: figure. The figure is an output of user-defined function 'plot_signals' The inputs for the function can be specified directly under "source" instance: input parameter 'timeframe' (week). This is equivalent to:

fig = plot_signals(timeframe="week")

Table

Table component can be generated using python executable: function or class.

- table:
    source:
      output: table
      source_type: python
      python_executable: table_of_squares
      number: 16

The "output" property specifies the type of instance to be generated: table. The table is an output of user-defined function 'table_of_squares' The inputs for the function can be specified directly under "source" instance: input parameter 'number' (16). This is equivalent to:

table = table_of_squares(number=16)

Parameter

The value of "parameter" can be generated based on "source" instance.

- document:
    name: document.docx
    parameters:
      - parameter:
          parameter_name: total_sales
          parameter_type: source
          source:
            output: text
            source_type: python
            python_executable: calculate_total_sales
            month: June
    structure:
        # ...

This specification declares parameter "total_sales" using "parameter_name" property. The "parameter_type" property specifies the method the parameter is set: "source". The value of parameter is an output of user-defined function 'calculate_total_sales' The inputs for the function can be specified directly under "source" instance: input parameter 'month' ("June"). This is equivalent to:

param = calculate_total_sales(month="June")

The full parameters functionality is available at Parameters.

Loop

The "source" instance can specify the settings for generating iterator values array for the "loop". The "source_type" specifies the array generation method: "python".

- loop:
    iterator_name: sales_month_i
    iterator_type: source
    source:
      output: array
      source_type: python
      python_executable: calculate_sales_per_month 
      segment: "retail"
    iterator_applicable:
      # ...

This specification declares a loop with iterator "sales_month_i" using "iterator_name" property. The "iterator_type" property specifies the method the parameter is set: "source". The iterator values are an output of user-defined function 'calculate_sales_per_month' The inputs for the function can be specified directly under "source" instance: input parameter 'segment' ("retail"). This is equivalent to:

values = calculate_sales_per_month(segment="retail")

The full iterations functionality is available at Iterations.

Back to homepage

Manual source

The "manual" method is applicable only for a "table" component and allows to specify each table's cell content individually. This feature is a convenient way to create custom tables filled with various pre-programmed output. On top of "source" required properties, property "table_size" is required.

- table:
    source:
      output: table
      source_type: manual
      table_size: [2,4]

The "table_size" property specifies the number of rows and columns of the "table" instance in format '[number of rows, number of columns]'. This specification creates an empty table with 2 rows and 4 columns.

Cells and Cell

OpenReport allows to modify table's content. The "cells" instance lists all "cell" instances of the "table". The "cell" instance specifies the cell's content. The "cell" can be filled with OpenReport components: "text", "figure", "math_expression" or "table".

- table:
    source:
      output: table
      source_type: manual
      table_size: [2,4]
    cells:
      - cell:
          position: [1,0]
          figure:
            source:
              output: figure
              source_type: local
              location: "input/apple.png"
      - cell:
        # ...

The "position" property specifies the position of cell within the "table" in format '[row number, column number]'. The position counting starts with 0, i.e. the top left most cell is addressed by '[0, 0]'. If certain cell's content is not specified it is left empty.
The specification above creates an empty table with 2 rows and 4 columns. The cell in the second row and first column is filled with locally stored figure.

Source and Cells

Once the "table" content is set by other than "manual" "source_type", the "cells" instance allows to address specific cell within the "table" and replace its content.

- table:
    source:
      output: table
      source_type: local
      location: 'input/price_data.xlsx'
    cells:
      - cell:
          position: [1,0]
          text:
            body: I am the new text

Required properties

Properties "position" and one of "text", "figure", "math_expression" or "table" are required.

cells:
  - cell:
      position:
      text:
        # ...

Optional properties

vertical_alignment

Type: string
Default: N/A
Description: Specifies the vertical alignment of text in the cell of a table.
Available options:

["top", "center", "bottom", "both"]

Example:

 vertical_alignment: center

horizontal_alignment

Type: string
Default: N/A
Description: Specifies the justification setting of text in the cell of a table.
Available options:

["left", "center", "right", "justify", "both", "distribute", "mediumKashida", "highKashida", "lowKashida", "thaiDistribute"]

Example:

 horizontal_alignment: right

AI source

"Text" and "heading" components can also be generated using AI. The "ai_prompt" property specifies a prompt that is sent to a configured AI provider, and the generated text is used as the component's body content. This requires "ai_config" to be defined at the document level. For the full setup guide, configuration and examples, see AI Content Generation.

Continue to Parameters

Back to top

Back to homepage