The 3DL Parser

The 3DL Parser#

At the core of DUFT UI is the 3DL Parser, an advanced mechanism that dynamically interprets 3DL files and transforms them into fully interactive dashboards—without requiring any precompiled UI components or manual frontend updates. The parser is designed to read declarative 3DL syntax (which resembles XML) and seamlessly convert it into a structured React component tree at runtime.

Engineering the 3DL Parser#

The 3DL Parser was built with several key engineering considerations in mind:

  • DUFT UI must be able to dynamically generate dashboards from configuration alone, eliminating the need for hardcoded UI definitions. Instead of relying on pre-built React component trees, the parser constructs them dynamically, ensuring complete flexibility.

  • The parser must transform XML-like 3DL structures directly into React components without intermediate steps. Many templating systems translate structured definitions into JavaScript objects, which are then mapped to components. Instead, DUFT’s parser instantiates the React tree directly, ensuring optimal performance and real-time rendering

  • The system must be state-driven. Because dashboards require real-time interactivity—such as data filtering, dynamic queries, and drill-down navigation—the parser must preserve and propagate application state across the dynamically generated components.

  • The parser must leverage context-aware execution. Instead of treating each component as an isolated unit, the parser understands component hierarchies and dynamically injects context where needed. This ensures that child components automatically inherit relevant parameters, datasets, or filtering options without requiring explicit wiring in 3DL.

  • The approach must be agnostic to data sources. Whether a component relies on SQL queries, API calls, OpenMRS endpoints, or static datasets, the parser ensures that data flows seamlessly into UI elements without the developer needing to define specific binding logic manually.

How the Parser Works#

DUFT’s 3DL Parser follows a multi-step process to interpret, validate, and render dashboards in real-time. This process occurs entirely at runtime, enabling a highly flexible, configuration-driven UI:

1. Parsing the 3DL Definition#

The 3DL file is loaded from DUFT Config. It is initially interpreted as a structured document—similar to how an XML or JSX file would be parsed. This step identifies component boundaries, extracts attributes, and normalises the structure for processing.

2. Component Resolution#

Each 3DL tag corresponds to a React component (e.g., <PieChart>, <DataProvider>, <Filters>). The parser maps each tag to its corresponding React implementation, ensuring that every UI element is properly instantiated.

3. Building the React Component Tree#

The parser dynamically assembles a virtual component tree, resolving component nesting and injecting props where necessary.

  • Containers like <Dashboard>, <Grid>, and <Row> provide structure.

  • Data-bound elements such as <QueryData> and <StaticData> retrieve datasets.

  • Visual components like <LineChart> and <Table> render data

  • Each component is instantiated dynamically, meaning that no pre-defined component trees exist—everything is composed on demand.

4. Context Injection & Propagation#

Because dashboards are interactive, the parser injects application state and context into relevant components.

  • Filters propagate their values to child queries.

  • Data providers ensure their outputs are accessible to dependent visualisations.

  • Tab-based layouts maintain UI state and prevent unnecessary re-renders.

This approach allows different dashboard elements to remain loosely coupled but functionally aware of each other.

5. Query Execution & Data Fetching#

Once the component tree is built, the Query Engine kicks in. Any <QueryData> components are executed, and data is fetched asynchronously. The parser ensures that:

  • Queries execute only when their dependencies (e.g., filters) are resolved.

  • API-based data sources are handled the same way as SQL queries, making integration seamless.

  • UI elements remain responsive, with loading states applied where necessary.

6. Live Rendering & State Updates#

With the React tree fully assembled and data injected, the dashboard is immediately rendered. Because the parser relies on React’s declarative rendering model, any state change—whether from filters, query results, or UI interactions—automatically triggers re-renders without requiring additional logic.

Why This Parser is Incredibly Smart#

The brilliance of the DUFT 3DL Parser isn’t just that it enables dynamic dashboards—it’s how seamlessly it does it. Instead of relying on static UI definitions or manually mapped templates, the parser takes structured XML-like input, processes it as JSX, and directly constructs a fully interactive React component tree at runtime. There’s no intermediate step, no separate templating language, just pure JSX flowing into React’s rendering engine.

Parsing and Instantiating a Live Component Tree#

Most configuration-driven dashboards require layers of mapping, where structured definitions are converted into JSON, then passed through a rendering pipeline. DUFT bypasses all of that. The parser directly interprets 3DL as JSX, meaning React simply sees it as another component tree. Every tag in 3DL corresponds to an actual React component, instantiated dynamically without needing any prewritten UI definitions. This is what makes it so efficient: the entire dashboard UI emerges naturally from configuration alone.

Leveraging JSX as JavaScript#

While many XML parsers treat markup as static, DUFT’s parser takes advantage of JSX’s true nature—it’s not just XML, it’s JavaScript. This means it doesn’t need to “convert” anything. Instead, it executes 3DL as a structured JSX document, allowing React to handle rendering, props, and updates natively. There’s no need for custom templating logic or manual component composition—React does all of that automatically, because the parser feeds it JSX exactly as if it were handwritten code.

A UI That Builds Itself#

What sets this apart from traditional dashboard implementations is the complete absence of predefined UI layouts. Instead of designing screens manually, developers describe dashboards in 3DL, and the parser figures out everything else. It resolves component references, constructs layouts, injects data from queries, and ensures state flows correctly—all at runtime. The UI effectively builds itself, adapting instantly when configurations change, without requiring any updates to the frontend code.

Context and State Awareness#

Rather than manually wiring components together, DUFT’s parser leverages React’s Context API to handle dependencies invisibly. Filters, user selections, and data queries automatically propagate through the component tree, ensuring that visuals stay in sync without explicit state management. If a filter changes, relevant components re-render naturally. This makes it easy to maintain reactivity across dashboards without needing custom event handling or complex data flow logic.

The Bottom Line#

The DUFT 3DL Parser isn’t just an XML interpreter—it’s a self-assembling UI engine. By transforming declarative dashboard definitions directly into React components, it eliminates unnecessary complexity while maintaining full interactivity. Instead of rethinking how dashboards should be built, it lets React do what it does best—constructing and managing UI dynamically. The result is a fully configurable, highly flexible dashboard system that behaves as if it were manually coded, but without the overhead of writing UI components by hand.

How the DUFT 3DL Parser Works#

At its core, the DUFT 3DL Parser transforms structured dashboard definitions into a live, fully interactive React component tree. This allows UI elements, queries, and state to remain synchronised dynamically—without requiring developers to explicitly wire up every component. Converting 3DL to JSX

Since 3DL resembles XML, it can be parsed directly into JSX using react-jsx-parser, removing the need for additional processing. A 3DL snippet like this:

// 3DL

<Dashboard>
  <Row>
    <Tile title="New Cases">
      <QueryData>SELECT COUNT(*) FROM cases WHERE year = '$year'</QueryData>
    </Tile>
  </Row>
</Dashboard>

Becomes real JSX at runtime, dynamically converted into React components:

<Dashboard>
  <Row>
    <DuftTile title="New Cases">
      <QueryData useQuery={useQueryData} client={client}>
        SELECT COUNT(*) FROM cases WHERE year = '$year'
      </QueryData>
    </DuftTile>
  </Row>
</Dashboard>

Here’s where it gets really smart: this JSX is not just a parsed string—it’s real, functioning React that React itself processes as a component tree.

React Components Rendering Real HTML#

Each parsed component eventually renders real HTML, maintaining full interactivity and styling. Take the <Row> component as an example:

const Row: React.FC<RowProps> = ({ children, style = {}, ...props }) => {
  const childrenCount = React.Children.count(children);

  const rowStyle = {
    display: "grid",
    gridTemplateColumns: `repeat(${childrenCount}, 1fr)`,
    gap: "1.5rem",
    padding: "1rem",
    ...style,
  };

  return (
    <div style={rowStyle} {...props}>
      {children}
    </div>
  );
};

The DUFT 3DL Parser doesn’t just create JSX—it builds real React components that in turn generate HTML. In this case, <Row> becomes a <div> styled as a responsive grid, automatically adjusting its columns based on the number of children.

Automatic Context and Query Injection#

Since everything is parsed dynamically, the UI and data remain tightly coupled without extra logic. The JSXParser handles this mapping automatically:

<JSXParser
  components={{
    Dashboard,
    DuftTile,
    Row,
    QueryData: (props) => (
      <QueryData {...props} useQuery={useQueryData} client={client} />
    ),
  }}
  jsx={dashboardData}
/>

React processes these parsed components like any other JSX, ensuring that queries fetch live data, tiles display dynamic values, and dashboards remain fully interactive.

Why This is Brilliant#

  1. No Static UI Definitions – Dashboards are fully generated at runtime, eliminating manual layout coding.

  2. Live Component Instantiation – Components are created dynamically, ensuring adaptability.

  3. React Takes Over from There – Once parsed, React handles state, rendering, and updates automatically.

  4. HTML Output is Seamless – Every component eventually renders clean, structured HTML while preserving interactivity.

The beauty of this system is that DUFT never manually controls component rendering—it lets React do what React does best. The result? A truly declarative, dynamic, and configuration-driven dashboard engine.

Contents