Value

This is the official documentation of the @forestadmin/agent Node.js agent.

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

// Add a chart to the Dashboard page
agent.addChart('monthlyRecuringRevenue', async (context, resultBuilder) => {
  // Request the sum of the "amount" field of all the records in "payments"
  const aggregation = { operation: 'Sum', field: 'amount' };
  const filter = {
    conditionTree: { field: 'status', operator: 'equal', value: 'paid' },
  };

  const rows = await context.dataSource
    .getCollection('payments')
    .aggregate(filter, aggregation);

  // Return the result
  return resultBuilder.value(rows[0].value);
});

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

// Add a chart to the Analytics page of the "customers" Collection
agent.customizeCollection('customers', collection => {
  collection.addChart('monthlyRecuringRevenue', async (context, resultBuilder) => {
    // Request the sum of the "amount" field of records in "payments" matching
    // current customer
    const aggregation = { operation: 'Sum', field: 'amount' };
    const filter = {
      conditionTree: {
        aggregator: 'And',
        conditions: [
          { field: 'status', operator: 'equal', value: 'paid' },
          { field: 'customer:id', operator: 'equal', value: context.recordId },
        ],
      },
    };

    const rows = await context.dataSource
      .getCollection('payments')
      .aggregate(filter, aggregation);

    // Return the result
    return resultBuilder.value(rows[0].value);
  });
});

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

agent.addChart('appointments', async (context, resultBuilder) => {
  // [...]

  return resultBuilder.value(784, 760);
});