How spance/tablegroup works
Project Type and Purpose
• This is a Java-based library designed for dynamically processing tabular data. It ingests 2D data (via a DataStore), applies various grouping rules (including cascaded and dependent grouping), builds an HTML element tree, and then renders a fully “merged” table complete with CSS-style modifications.
• The library is optimized for performance (see the CSS selector matching benchmarks) and aims to simplify the generation of complex tables—reducing the need for heavy, traditional reporting engines.
Main Components
• Data Input Module:
• DataStore implementations (e.g., SimpleDataStore) that abstract data ingestion. Indicate the “store” package (wong.spance.html.store) as the place where DataStore, RowIterator, and AbstractDataStore are implemented.
• Metadata and Configuration:
• TableMeta (invoked during TableGroup construction) where table columns and configuration are defined.
• This component is key for defining the blueprint that drives the grouping and rendering processes.
• Grouping Engine:
• Core grouping functionality provided by classes under the “merge” and “span” packages.
• The merge module (wong.spance.html.merge) encapsulates the logic for comparing individual cells (e.g., BasicCellComparator) and managing merge context.
• The span module (wong.spance.html.span) contains classes like RowSpan, CellSpan, SpanBy, etc. These classes capture grouping rules ranging from simple (on a single column) to cascaded (where grouping in subsequent columns is constrained by previous groups).
• HTML Element Tree Construction:
• Located in the “html/element” package, this part shows how the library builds a hierarchical structure of HtmlElement nodes (tables, rows, cells, header groups etc.).
• It forms the in-memory “DOM” that gets later rendered into the final HTML.
• Rendering and Modifier Engine:
• Found in the “html/render” package, where the RenderContext and multiple Modifier interfaces (BeforeRenderModifier, AfterRenderModifier, TextRenderModifier, DefaultModifiers, etc.) allow for customization of the HTML via CSS-like selectors.
• This module takes the HTML element tree and applies stylistic and attribute modifications according to parsed CSS selectors.
• CSS Selector Parsing and Matching:
• Within the “html/css” package, you have the CSS parsing and handling components (Selector, SelectorParser, Qualifier, IdQualifier, ClassNameQualifier, etc.) that are responsible for interpreting CSS strings and then matching them against the HTML element nodes.
• Even the performance metrics in the README illustrate that this matching system is high-performance.
• Statistics Module:
• Located under “html/stat”, this component (e.g., Statistics, StatisticsContext, StatisticsMatcher) focuses on computing summary statistics based on grouped data.
• It provides APIs to do simple aggregations (like sum) on the grouped results.
• Testing & Quality Assurance:
Relationships and Interaction Flows
• Data Flow:
• TableGroup uses the metadata (configured via TableMeta) to set up the table structure and grouping definitions.
• Grouping rules (from the merge and span modules) process this data to determine cells that can be merged (or grouped) based on specified columns.
• The outcome is a tree of HtmlElement objects (the DOM-like structure) built in the HTML Element Tree Construction module.
• Rendering Flow:
• Once the element tree is built, the rendering engine – which leverages the CSS Selector Parser/Matcher – applies modifiers. These modifiers (defined via different points of intervention like before or after rendering) adjust attributes, text, and styles as defined by the user (using a CSS selector syntax).
• Finally, the rendering layer produces the complete HTML output with all the grouping and styling results applied.
• Statistical Computation:
• Optionally, the Statistics Module is invoked to compute additional information (aggregations) from the grouped data, which could be delivered alongside the rendered table or to external components like charting libraries.