SpreadsheetTile Documentation

Overview

The SpreadsheetTile component is designed to display spreadsheet-like data, allowing for multi-sheet support and various interactive features like sorting, filtering, and lazy loading of data. It facilitates effective data interaction, making it suitable for users handling large datasets.

Key Features

• Multi-Sheet Support: Ability to manage and display multiple spreadsheet sheets within one tile.
• Column Sorting: Users can sort data columns in ascending or descending order.
• Column Visibility Toggle: Toggle the visibility of individual columns based on user preference.
• Data Pagination: Optimized for large datasets with lazy loading techniques, using dataRef for efficient rendering.
• Persistent State Management: Saves user customizations in local storage for a consistent user experience across sessions.

Settings

The following settings can be configured for the SpreadsheetTile component:

1. id

   • Input Type: String
   • Description: Unique identifier for the tile, used to store and retrieve its state in local storage. This is critical for preserving user settings across page refreshes.
   • Default Value: None (must be provided).

2. height

   • Input Type: Numeric
   • Description: Determines the height of the tile in pixels.
   • Default Value: 400 (if unspecified).

3. width

   • Input Type: Numeric
   • Description: Controls the width of the tile in pixels.
   • Default Value: 600 (if unspecified).

4. data

   • Input Type: Array of Objects
   • Description: An array of data objects to be displayed in the spreadsheet. This takes precedence when dataRefIds is not used.
   • Default Value: An empty array [].

5. dataRefIds

   • Input Type: Array of Strings
   • Description: An array of data reference IDs used to fetch data for the tile. It allows for the lazy loading of data, reducing initial load time for large datasets.
   • Default Value: An empty array [].

6. config

   • Input Type: Object
   • Description: Configuration settings for the tile's functionality and appearance, which includes:
     • spreadsheetConfig (nested config): Specific configurations for the spreadsheet behavior and layout.
     • visibleColumns: An array of strings representing columns that should be visible upon loading. This setting should not include special identifiers like _rowIndex.
   • Default Value: An empty object {}, or configuration defaults if provided.

7. isLoading

   • Input Type: Boolean
   • Description: Indicates if the parent component is still loading data. This can help handle loading states and effect UI changes accordingly.
   • Default Value: false.

8. title

   • Input Type: String
   • Description: The title text displayed at the top of the tile.
   • Default Value: "Spreadsheet" if not provided.

9. subtitle

   • Input Type: String
   • Description: Subtext displayed below the title for more contextual information.
   • Default Value: None.

10. footerText

    • Input Type: String
    • Description: Text displayed in the footer of the tile.
    • Default Value: None.

11. footerColor

    • Input Type: String
    • Description: The color code (e.g., hex, rgb) to customize the footer's background.
    • Default Value: None.

How It Works

The SpreadsheetTile component initializes with props that include settings for its height, width, data source, and configuration. It leverages a pagination hook, useDataRefPagination, to manage large datasets efficiently through lazy loading. This hook fetches and manages the required data, which can be displayed in a tabular format corresponding to the defined settings.

The component also utilizes internal state for:

• Managing sort properties (active column and direction).
• Tracking hidden columns and sheets.
• Storing active filters, allowing users to filter data based on specific criteria.

User interactivity is enhanced through:

• Dynamic column visibility settings.
• On-the-fly sorting based on user clicks.
• Persistence of user-specific settings (like hidden columns and active filters) through local storage.

Use Cases & Examples

Use Cases

1. Sales Data Analysis: A business analyst can utilize the SpreadsheetTile to analyze sales data across multiple regions, comparing metrics while toggling visibility for non-essential columns.

2. Project Management: A project manager can employ this tile to monitor projects’ progress by setting up a multi-sheet overview, where each sheet represents a different project phase, and filters for status can be applied.

3. Research Data Presentation: Researchers can leverage the component to present experimental data, allowing peers to sort and filter results to find relevant information effortlessly.

Example Configuration for Sales Data Analysis

To configure the SpreadsheetTile for analyzing sales data, you can use the following sample code:

<SpreadsheetTile
    id="sales-data"
    height={500}
    width={800}
    dataRefIds={["salesDataRefId"]}
    config={{
        visibleColumns: ["Region", "Sales", "Date", "Representative"],
    }}
    title="Sales Data Overview"
    subtitle="Monthly Sales Performance Analysis"
    footerText="Data sourced from the primary sales database."
    footerColor="#f0f0f0"
/>

In this configuration:

• The tile is set to a height of 500 pixels and a width of 800 pixels.
• It utilizes a data reference ID salesDataRefId to load data dynamically.
• The visible columns include Region, Sales, Date, and Representative, optimizing for relevant metrics for sales analysis.
• A title and subtitle enhance the context of the data presented, while a footer is included for additional notes.