expandable_box_drawing_table #

expandable_box_drawing_table provides a Flutter widget called ExpandableBoxDrawingTable. This widget allows users to create a table with expandable sections, where each section can contain multiple subsections. The widget uses box drawing characters to visually represent the structure and hierarchy of the table, making it easier for developers to create and manage complex, nested layouts. Both entries and sections can be checked. When entries are checked, the updated list of selected values can be handled in a callback. Checking sections will either select or unselect all descendent sections and entries, providing a comprehensive way to manage hierarchical data.

Features #

• Recursively display hierarchical data in easy-to-understand tables
• Add callbacks to handle when data changes
• Provide a custom configuration for more control over table appearance and behavior

Usage #

For working examples, please refer to the example project included in this repository

Definitions

As the usage of this package is explained, you will encounter some words that have specific meanings within the context of using this package:

• value: A value is any piece of data. They are associated with an Entry that will appear at the lowest-level of a hierarchy. Your ExpandableBoxDrawingTable is generic and can be passed a type. This type determines the type of the List of newly-selected values returned when any data in your table changes.
• Entry: An Entry appears at the lowest-level of a hierarchy in ExpandableBoxDrawingTable. They contain an associated value that can be handled when their associated EntryCell is "selected" (via tapping its Checkbox).
• Section: Sections are classes that contain either a list of more Sections (Section.subSections) or a list of Entrys (Section.entries), but not both. There can be any number of recursively nested subSections within a Section. All Section hierarchies will, in theory, end with a list of Entrys (can be an empty list) to be displayed to the user.

Basic Setup

Creating your Expandable Box Drawing Table is as simple as creating an ExpandableBoxDrawingTable with initialValues and Sections:

ExpandableBoxDrawingTable<String>( 
  initialValues:  
    sharedPreferences.getStringList('selected_values') ?? [],
  sections: [
    Section<String>(
      title: '1',
      entries: [
        Entry<String>(title: '1', value: '1.1'),
        Entry<String>(title: '2', value: '1.2'),
      ],
    ),
    Section<String>(
      title: '2',
      entries: [
        Entry<String>(title: '1', value: '2.1'),
        Entry<String>(title: '2', value: '2.2'),
      ],
    ),
  ],
);

Let's assume that, in the above example, sharedPreferences.getStringList('selected_values') returned ['1.2', '2.1']. In this case, the EntryCells associated with the Entrys with these '1.1' and '2.1' values would be initially "selected", i.e. their checkbox will initially be checked.

Handling selected data

This interface would be mostly useless if we didn't provide a means of handling newly-selected data. Luckily, ExpandableBoxDrawingTable comes with an onValuesChanged callback so that you can handle changes to selected data:

ExpandableBoxDrawingTable<String>( 
  initialValues:  
    sharedPreferences.getStringList('selected_values') ?? [],
  onValuesChanged: (newValues) {
    sharedPreferences.setStringList('selected_values', newValues);
  },
  ...
);

You'll notice that ExpandableBoxDrawingTable is generic. This is done in order to avoid needing to type cast handled data. For this reason, whichever values are provided to initialValues must be a List<T> , where T is the same type passed to ExpandableBoxDrawingTable<T>. You could omit typing ExpandableBoxDrawingTable, but any new values handled in onValuesChanged would likely end up needing to be type casted at some point.

Customization

The appearance and behavior of your ExpandableBoxDrawingTable can be customized to fit your specific needs. This is done through the use of ExpandableBoxDrawingTableConfigurationData:

ExpandableBoxDrawingTable(  
  configuration: 
    ExpandableBoxDrawingTableConfigurationData(  
      sectionsHaveCheckBoxes: false,  
      entriesHaveCheckBoxes: false,  
      expandedIcon: Icons.catching_pokemon,  
      collapsedIcon: Icons.bubble_chart_outlined,  
    ),
  ...
);

This configuration data class currently only supports very basic configuration, i.e. whether Sections and Entrys should display Checkboxes, or which IconData to use for icons on expanded or collapsed sections. In theory, this class could be expanded to support a much broader range of configuration options, such as paddings, indentation, colors, custom box drawing "characters", and adding "builders" to allow sections to only display their Checkboxes if certain criteria are met (such as how "deep" the Section is within the main Section).

Additional information #

Feel free to file issues and/or make pull requests if you have any bug reports/feature requests! PRs that are written without test coverage will not be merged until adequate coverage is added (either by the requester or a maintainer).