Overview

SmartChart eliminates the gap between your Mendix data and a meaningful chart. Instead of writing OQL queries, creating non-persistable entities, and building aggregation microflows, you drop SmartChart on a page, point it at any data source, pick two attributes — and it handles the rest automatically.

What it does

SmartChart runs a full GROUP BY aggregation engine in the browser, directly on the object list Mendix already delivers to every widget. It groups rows by any category attribute, applies your chosen aggregation function (Sum, Count, Average, Min, Max, or Count Distinct), sorts and filters the results, and renders an interactive chart — all without a single line of OQL or Java.

It also recommends the best chart type for your data automatically. Time-series data becomes a Line chart. A handful of categories becomes a Pie. One aggregated total becomes a large KPI Card. Everything else becomes a Bar. You can override the recommendation at any time.

Key capabilities

• OQL replacement — GROUP BY, SUM, COUNT, AVG, MIN, MAX, COUNT DISTINCT, TopN, and ORDER BY, all configured through dropdowns. No query editor, no non-persistable entity, no microflow.
• Date binning — group DateTime attributes by Day, ISO Week, Month, Quarter, Year, or Day of Week. Equivalent to OQL MONTH() / YEAR() / QUARTER(), normalised across all database vendors.
• Pivot series — turn a second categorical attribute into coloured series dynamically. One bar per Product inside each Region cluster, one line per Department across months — the OQL PIVOT that doesn't exist in OQL.
• Additional series — plot multiple numeric measures side by side on the same chart (e.g. Revenue and Units Sold per Region).
• Association traversal — any attribute picker accepts a Mendix association path. Use SalesData_Product / Product / Product.Name as a pivot dimension without any extra retrieval.
• Stacked mode — stack bar or area series for part-of-whole composition views.
• KPI Card — auto-selected or forced, displays a single aggregated metric as a large formatted number with K/M abbreviations. Perfect for dashboard summary tiles.

Typical use cases

• Sales dashboards — revenue by region, product, or sales rep; trend over time; top 10 customers
• HR reporting — headcount by department, leave requests by month, turnover rate by quarter
• Operations — order volume by status, average fulfilment time by warehouse, defect count by category
• Finance — expense breakdown by cost centre, monthly budget vs actuals, year-over-year comparison
• Any situation where you previously reached for OQL + a custom microflow just to draw a bar chart

How it connects to Mendix

SmartChart uses the standard Mendix Pluggable Widget API. It receives a typed ListValue from the runtime — the same object list any DataGrid or other widget receives. Mendix enforces all entity access rules and XPath constraints before the data reaches the widget. SmartChart never bypasses security and requires no additional server configuration.

Documentation

SmartChart is a zero-configuration data visualisation widget for Mendix. It replaces the need for OQL queries, custom microflows, or third-party chart libraries by performing GROUP BY aggregation, date binning, pivot series, and intelligent chart-type recommendation — all in the browser, directly from any Mendix data source.

1.1  The Mendix Pluggable Widget Contract

Mendix pluggable widgets are React components that receive typed props injected by the Mendix Client runtime. SmartChart declares its data contract in SmartChart.xml, which Studio Pro compiles into strongly-typed TypeScript definitions (SmartChartProps.d.ts). No manual HTTP calls, no REST APIs, no custom Java actions are required.

1.2  Data Flow — Step by Step

1.3  Key Mendix API Types Used

1.4  Association / Reference Traversal

SmartChart's attribute pickers declare <associationTypes> in the widget XML, which tells Studio Pro to allow association-path expressions like:

MyFirstModule.SalesData_Product / MyFirstModule.Product / MyFirstModule.Product.Name

Mendix resolves the join server-side and delivers the associated attribute value pre-fetched on each ObjectItem — the widget calls .get(item).value and receives the Product Name string directly, with no extra retrieval needed.

1.5  Security

SmartChart receives only the data Mendix decides to send. All entity-access rules, XPath constraints, and row-level security are enforced by the Mendix runtime before the object list reaches the widget. The widget cannot bypass or escalate beyond what the current user session is authorised to see.

2.1  Why OQL Exists — and Why It Is Hard

Mendix OQL (Object Query Language) lets developers write SQL-like queries to aggregate data — SUM, COUNT, GROUP BY, HAVING, JOIN. It is powerful but has friction:

• Needs a non-persistable entity: you must create a separate entity to hold the query results.
• Needs a Java action or microflow: to execute the OQL and map results to the NP entity.
• No live interactivity: filters require wiring up microflow parameters and re-querying.
• Pivot tables require custom code: OQL has no PIVOT operator; developers must write loops.
• Date truncation functions vary: MONTH(), YEAR(), QUARTER() syntax differs across DB vendors.

SmartChart moves all of this to the client side, using the same data source Mendix already provides to every widget.

2.2  OQL Equivalency Table

2.3  The Aggregation Engine

The aggregator (src/utils/aggregator.ts) runs entirely in the browser after Mendix delivers the object list. Its pipeline is:

1. Iterate items: read each row's categoryAttr and bin into a category key (with optional date truncation via binDate()).
2. Collect buckets: for each (category, series) cell, accumulate raw numeric values in an array.
3. Apply aggregation: call applyAgg(values[], fn) — SUM / COUNT / AVG / MIN / MAX / COUNT DISTINCT.
4. Sort: chronological for dates, DOW order for day-of-week, total-descending for sortByValue.
5. TopN: slice categories to the first N after sorting.
6. Return AggregatedResult: { categories[], series[{ name, values[] }], isDateCategory, rawCount }.

2.4  Pivot Mode

When "Pivot series by" is set, the engine switches from STANDARD to PIVOT mode. Instead of using fixed measure attributes as series, it dynamically discovers all unique values of the pivot attribute and creates one series per value:

SELECT Region, Product.Name, SUM(Revenue)

FROM SalesData

GROUP BY Region, Product.Name

→ Pivot Product.Name into columns

This is equivalent to a SQL PIVOT or a spreadsheet PivotTable. Each unique Product Name becomes one coloured bar or line in the chart.

3.1  Data Tab — All Properties

3.2  Filtering & Sorting Tab

3.3  Appearance Tab

3.4  Auto Chart-Type Recommender

When Chart type = Auto, the recommender (src/utils/chartRecommender.ts) inspects the aggregated result and picks the best visualisation:

The following scenarios demonstrate SmartChart's key capabilities in a live Mendix environment. Each builds on the same SalesData → Product domain model used in development.

4.1  Pre-Requisites

• Domain model: Entity SalesData { Region (String), Revenue (Decimal) } with a *–1 reference SalesData_Product to Product { Name (String), QTY (Integer) }.
• Sample data: At least 5–6 SalesData rows across 3 regions, each linked to a Product (use a Reference Selector on the edit form to set the link).
• Data grid: Optional — a DataGrid 2 on the same page showing Region, Revenue, Product/Name helps confirm the data before the chart renders.
• SmartChart widget: deployed and visible in the Studio Pro toolbox under Visualization.

4.2  Demo 1 — Revenue by Region (Bar)

Goal: show how SmartChart replaces a manual OQL GROUP BY in 30 seconds.

1. Data source: SalesData, by Database (XPath — no constraint).
2. Category: SalesData.Region (String).
3. Primary measure: SalesData.Revenue (Decimal).
4. Aggregation: Sum.
5. Chart type: Auto (will auto-select Bar).

Expected result: a bar chart with one bar per region, height = sum of Revenue. Say: "This is the equivalent of SELECT Region, SUM(Revenue) FROM SalesData GROUP BY Region — without writing a single line of OQL or creating a non-persistable entity."

4.3  Demo 2 — Top 3 Regions (TopN + Sort)

Goal: demonstrate ORDER BY + FETCH FIRST without microflows.

Starting from Demo 1, open the widget configuration:

1. Sort by value: Enable (Sort by value descending = Yes).
2. Top N: Set to 3.
3. Save and run. The chart now shows only the 3 highest-revenue regions, highest first.

Say: "OQL equivalent: ORDER BY SUM(Revenue) DESC FETCH FIRST 3 ROWS ONLY — configured in two clicks."

4.4  Demo 3 — Revenue by Product per Region (Pivot)

Goal: show OQL-style two-dimension pivot without any query.

1. Reset Top N to 0 and Sort by value to No.
2. Pivot series by: Select SalesData_Product / Product / Product.Name.
3. Chart type: Bar (or Auto — recommender will choose Bar for multi-series).
4. Stacked series: Try both off (grouped) and on (stacked).

Expected result: clustered bars — one cluster per Region on the X-axis, one coloured bar per Product inside each cluster. Say: "This is PIVOT Product.Name INTO series — something OQL cannot do natively at all."

4.5  Demo 4 — Monthly Revenue Trend (Date Binning + Line)

Goal: show MONTH() / YEAR() date truncation that varies across OQL database vendors.

Add a SaleDate (DateTime) attribute to SalesData and populate a year's worth of rows, then:

1. Category: SalesData.SaleDate.
2. Date grouping: Month.
3. Aggregation: Sum.
4. Chart type: Auto (recommender picks Line for date axis).

Expected result: a smooth line chart with X-axis labels YYYY-MM, plotted in chronological order. Switch Date grouping to Quarter or Year to collapse the bins. Say: "This replaces OQL MONTH() / YEAR() / QUARTER() — which behave differently on PostgreSQL, HSQLDB, and SQL Server. SmartChart normalises it all client-side."

4.6  Demo 5 — KPI Card (Single Metric)

Goal: show auto-KPI for an executive summary number.

1. Data source: SalesData.
2. Category: Region — but add an XPath constraint [Region = 'North'].
3. Aggregation: Sum. Chart type: Auto.

Expected result: a large formatted KPI number (e.g. "100" or "1.2K"). The recommender detects 1 category → 1 number → KPI Card. Say: "Perfect for dashboard summary tiles — no separate widget needed."

4.7  Demo 6 — Additional Series (Multi-Measure Bar)

Goal: show multiple measure attributes side-by-side (no pivot — fixed series).

1. Data source: SalesData.
2. Category: Region.
3. Primary measure: Revenue. Label: "Revenue".
4. Additional series: Add one entry — Measure = SalesData_Product/Product.QTY, Label = "Units Sold".
5. Chart type: Bar.

Expected result: two bars per region — one for Revenue, one for Units Sold. Say: "Two SELECT columns in one chart — SELECT Region, SUM(Revenue), SUM(QTY) FROM ... GROUP BY Region."

5.1  File Structure

5.2  SmartChart.xml — Key Declarations

Three XML patterns are essential for Mendix pluggable widget attribute pickers:

Association traversal

Adding <associationTypes> allows the attribute picker to accept paths that cross a reference:

<property key="seriesByAttr" type="attribute" dataSource="dataSource" required="false">

<caption>Pivot series by (optional)</caption>

<description>...</description>

<attributeTypes>

<attributeType name="String"/>

<attributeType name="Enum"/>

</attributeTypes>

<associationTypes>

<associationType name="Reference"/>

</associationTypes>

</property>

Nested object list (Additional series)

Properties inside an isList="true" object block must be wrapped in a <propertyGroup> and must reference the parent data source with ../dataSource:

<property key="series" type="object" isList="true" required="false">

<caption>Additional series</caption>

<description>...</description>

<properties>

<propertyGroup caption="Series">

<property key="measureAttr" type="attribute"

dataSource="../dataSource" required="true">

...

</property>

</propertyGroup>

</properties>

</property>

XSD element order

Studio Pro validates against custom_widget.xsd which requires this order inside <property>: caption → category (optional) → description → attributeTypes → associationTypes → properties. Violating the order produces "invalid child element" XSD errors.

5.3  Aggregator Type Signatures

export type AggregateFunction =

"auto" | "sum" | "count" | "avg" | "min" | "max" | "countDistinct";

export type DateGrouping =

"none" | "day" | "week" | "month" | "quarter" | "year" | "dayOfWeek";

export interface AggregatedResult {

categories: string[]; // X-axis labels

series: SeriesData[]; // one per measure / pivot value

isDateCategory: boolean; // true when category is DateTime

rawCount: number; // total rows processed

}

export function aggregateData(

items: ObjectItem[],

categoryAttr: ListAttributeValue<string | Date | Big>,

primaryMeasure:ListAttributeValue<Big>,

primaryLabel: string,

extraSeries: ExtraSeries[],

aggFn: AggregateFunction,

topN: number,

sortByValue: boolean,

dateGrouping: DateGrouping,

seriesByAttr?: ListAttributeValue<string | Big | boolean>

): AggregatedResult

5.4  Rendering — Apache ECharts

ChartRenderer.tsx uses ECharts 5.x via the echarts npm package (tree-shaken — only the components needed are imported). The chart option object is rebuilt on every React render cycle — no imperative setOption diffing is needed because ECharts handles the transition animation automatically.

• Stacked mode: each SeriesData entry includes stack: "total" when props.stacked = true.
• KPI card: rendered as a plain <div> — ECharts is not used. The value is formatted with K / M abbreviations (formatKPI).
• Colour palette: ECharts default — 10 colours cycling. Consistent across series because series order in the output array is deterministic (insertion order of first-seen pivot values).
• Tooltip: axis-type tooltip on hover — shows all series values for the hovered category.

5.5  Known Constraints and Workarounds

Tear off and keep on your desk during demos.

6.1  Troubleshooting