Show a summary

A Summary is used to store important parameters of an entity. This enables easy sorting and comparing of different entities in an overview. A Summary can be defined per entity type (controller), and is optional. A summary can have a maximum of 6 summary items.

Implementation: from parametrization

One source of summary items is the parametrization. You can point to a field in the parametrization and the value of this field will be shown in the summary.

The following fields can be used in a summary:

• NumberField
• IntegerField
• TextField

Adding a summary is done with the following steps:

1. Add a controller summary attribute:

   from viktor.views import Summary
   
   class Controller(ViktorController):
       summary = Summary()
       ...

2. Add a SummaryItem and link to the parametrization:

   from viktor.views import Summary, SummaryItem
   
   class Controller(ViktorController):
       summary = Summary(
           item_1=SummaryItem('Length', float, 'parametrization', 'geometry.input.length', prefix='m')
       )
       ...

Above example assumes the following parametrization:

from viktor.parametrization import ViktorParametrization, Tab, Section, NumberField

class Parametrization(ViktorParametrization):
    geometry = Tab(...)
    geometry.input = Section(...)
    geometry.input.length = NumberField(...)

Implementation: from results

When a view contains data (e.g. DataView, GeometryAndDataView, etc.), that data can be used in the summary.

note

SummaryItems can only be obtained from a "quick" view (i.e. without manual update button).

1. Add a controller summary attribute:

   from viktor.views import Summary
   
   class Controller(ViktorController):
       summary = Summary()
       ...

2. Create a DataView which returns the result(s) that should be shown on the summary:

   from viktor.views import DataView, DataResult, DataGroup, DataItem
   
   class Controller(ViktorController):
       ...
   
       @DataView("Cost", duration_guess=1)
       def calculate_cost(self, params, **kwargs):
           # app specific cost calculation
           material_cost = ...
           total_cost = material_cost + ...
   
           data = DataGroup(
               total_cost=DataItem('Total cost', total_cost, prefix='€', subgroup=DataGroup(
                   material_cost=DataItem('Material', material_cost, prefix='€')
               ))
           )
           return DataResult(data)

3. Add a SummaryItem and link to the DataItem (in this example the material cost):

   from viktor.views import Summary, SummaryItem
   
   class Controller(ViktorController):
       summary = Summary(item_1=SummaryItem('Materials', float, 'calculate_cost', 'total_cost.material_cost', prefix='€'))
       ...

Keep in mind that when creating a DataGroup you can pass a list or dict of data items. When you use a list however, the items can not be used in the Summary, because there is no keyword that functions as link between the result and the summary.

Prefix/suffix

The prefix/suffix that is defined on the SummaryItem is stored in the database and has to be static, such that it can be used to for example sort entities of a certain entity type. This means that there cannot be any inconsistency between prefix/suffix definitions of an entity type and they should not be changed.

The prefix/suffix of a DataItem however can in most cases be dynamic. A good example is when the result of an analysis is a reaction force in Newtons. Since this result is dynamic and can potentially be extremely large, a user could find it more convenient to show this result in kN. This unit can switch with every call and this dynamic behavior holds for all DataItems. However, when the result is used in the Summary, the prefix/suffix of the DataItem should be equal to the prefix/suffix of the SummaryItem and static as explained above.