Value

This is the official documentation of the forestadmin-agent-django and forestadmin-agent-flask Python agents.

Value Chart example

Value Charts display a single numerical value.

They can be added to a Dashboard using the addChart method on the agent object

from forestadmin.datasource_toolkit.context.agent_context import AgentCustomizationContext
from forestadmin.datasource_toolkit.decorators.chart.result_builder import ResultBuilder
from forestadmin.datasource_toolkit.interfaces.chart import Chart
from forestadmin.datasource_toolkit.interfaces.query.aggregation import Aggregation
from forestadmin.datasource_toolkit.interfaces.query.filter.unpaginated import Filter
from forestadmin.datasource_toolkit.interfaces.query.condition_tree.nodes.leaf import ConditionTreeLeaf

async def monthly_recuring_revenue_chart_fn(
    context: AgentCustomizationContext, result_builder: ResultBuilder
) -> Chart:
    aggregation = Aggregation({"field": "amount", "operation": "Count"})
    filter_ = Filter(
        {"condition_tree": ConditionTreeLeaf("status", "equal", "paid")}
    )
    rows = await context.datasource.get_collection("Payment").aggregate(
        context.caller, filter_, aggregation
    )
    return result_builder.value(rows[0]["value"])

agent.add_chart("monthlyRecuringRevenue", monthly_recuring_revenue_chart_fn)

Or to the "Analytics" Tab of a Collection using the addChart method on the collection object

from forestadmin.datasource_toolkit.decorators.chart.collection_chart_context import CollectionChartContext
from forestadmin.datasource_toolkit.decorators.chart.result_builder import ResultBuilder
from forestadmin.datasource_toolkit.interfaces.chart import Chart
from forestadmin.datasource_toolkit.interfaces.query.aggregation import Aggregation
from forestadmin.datasource_toolkit.interfaces.query.filter.unpaginated import Filter
from forestadmin.datasource_toolkit.interfaces.query.condition_tree.nodes.leaf import ConditionTreeLeaf
from forestadmin.datasource_toolkit.interfaces.query.condition_tree.nodes.branch import ConditionTreeBranch

async def monthly_recuring_revenue_chart_fn(
    context: CollectionChartContext, result_builder: ResultBuilder
) -> Chart:
    aggregation = Aggregation({"field": "amount", "operation": "Sum"})
    filter_ = Filter(
        {
            "condition_tree": ConditionTreeBranch(
                "and",[
                    ConditionTreeLeaf(
                        "customer:id", "equal", await context.get_record_id()
                    ),
                    ConditionTreeLeaf("status", "equal", "paid"),
                ]
            )
        }
    )
    rows = await context.datasource.get_collection("Payment").aggregate(
        context.caller, filter_, aggregation
    )
    return result_builder.value(rows[0]["value"])

agent.customize_collection("Customer").add_chart(
    "monthlyRecuringRevenue", monthly_recuring_revenue_chart_fn
)

Optionally, an older value can be provided to the resultBuilder to display a growth percentage on the top right of the widget as in the following Chart display:

Value chart with percentage example

from forestadmin.datasource_toolkit.context.agent_context import AgentCustomizationContext
from forestadmin.datasource_toolkit.decorators.chart.result_builder import ResultBuilder
from forestadmin.datasource_toolkit.interfaces.chart import Chart

async def appointments_chart_fn(
    context: AgentCustomizationContext, result_builder: ResultBuilder
) -> Chart:
    # ...
    return result_builder.value(784, 760)

agent.add_chart("appointments", appointments_chart_fn)