Dashboard Builder

Interface Overview

The Dashboard Editor is organized into three main areas that provide a complete editing experience:

1. Toolbar

The top toolbar provides essential controls for managing your dashboard.

• Back Button - Returns to the previous screen (view mode if editing an existing dashboard, or closes the editor for new dashboards)
• Dashboard Name - Editable text field with a distinct background indicating it can be modified. Set or change the dashboard name here
• Export JSON - Downloads the dashboard configuration as a JSON file for backup or sharing
• Add Widget - Opens the widget creation dialog to add new charts or text widgets to your dashboard
• Save - Saves the current dashboard configuration and returns to view mode (shows "Saving..." when in progress)

2. Dashboard Settings Panel

Below the toolbar, the settings panel lets you configure dashboard-wide properties.

• Description - Multi-line text area with a distinct background indicating it can be modified. Add notes about the dashboard's purpose or content here

3. Grid Preview Area

The main area displays a live preview of your dashboard layout with all widgets positioned on a responsive grid.

• Widget Counter - Shows the total number of widgets currently on the dashboard
• Grid Canvas - Interactive area where widgets can be dragged, dropped, and resized
• Empty State - When no widgets exist, displays a helpful message with a button to add your first widget

Adding Widgets

Widgets are the building blocks of your dashboard. Each widget displays a chart or text content in a resizable, draggable container.

Opening the Add Widget Dialog

Click the "Add Widget" button in the toolbar to open the widget creation dialog. The dialog features a compact, streamlined design with toggle buttons for widget type selection.

Widget Types

Use the toggle buttons at the top of the dialog to select the widget type:

• Chart - Toggle this option to add a chart widget. Displays a saved chart from your chart library with live data updates
• Text - Toggle this option to add a text widget. Shows custom text content for labels, notes, or documentation

Adding Chart Widgets

When you select the Chart widget type, you'll see a list of all your saved charts:

• Chart Selection List - Browse all available charts with checkboxes for multi-selection
• Chart Information - Each chart shows its name, chart type, and source collection
• Multi-Select Controls - Use "Select All" to choose every chart or "Clear All" to deselect everything
• Selection Counter - Displays how many charts are currently selected

Adding Text Widgets

Text widgets let you add context, titles, or instructions directly on your dashboard:

• Text Content Field - Multi-line text area where you enter your content
• Plain Text Format - Content displays exactly as typed with preserved line breaks

Widget Configuration Options

Both chart and text widgets share these configuration options:

Grid Layout System

The dashboard uses a responsive grid system that makes it easy to arrange multiple visualizations. Understanding the grid helps you create organized, professional-looking dashboards.

Grid Structure

• 12 Columns - The grid is divided into 12 equal columns that widgets can span across
• Flexible Rows - Rows expand automatically based on widget placement (up to 100 rows)
• Minimum 10 Rows - The grid always shows at least 10 rows so you have space to drag new widgets
• Free Positioning - Widgets can be placed anywhere on the grid with vertical gaps between them

Dragging Widgets

Every widget has a drag handle at the top that lets you reposition it on the grid:

• Drag Handle - The header bar with a grip icon on the left side is the drag handle
• Drag Anywhere - Click and hold the drag handle, then move your mouse to reposition the widget
• Visual Placeholder - A placeholder outline shows where the widget will be dropped
• Auto-Scroll - The canvas automatically scrolls when you drag near the edges
• Snap to Grid - Widgets automatically align to the grid columns and rows

Resizing Widgets

Widgets can be resized by dragging their edges or corners to span more columns or rows:

• Resize Handles - Hover over widget edges to reveal resize handles on the east, west, south, southeast, and southwest edges
• Proportional Sizing - Widgets resize in grid units (columns and rows) as you drag
• Minimum Size - Widgets cannot be smaller than 1 column by 1 row
• Size Display - The widget header shows current dimensions (e.g., "4x3" for 4 columns by 3 rows)
• Live Chart Resizing - Charts automatically redraw to fit the new widget dimensions

Layout Behavior

The grid system provides flexible positioning while maintaining visual organization:

• No Auto-Compacting - Widgets stay exactly where you place them, allowing intentional vertical spacing
• Overlap Prevention - The grid prevents widgets from overlapping each other
• Push/Shift - Moving a widget into an occupied space pushes other widgets out of the way
• Responsive Charts - Chart visualizations automatically adapt to their container size

Managing Widgets

Each widget provides controls for customization and removal directly in its header.

Widget Header Elements

• Drag Handle Icon - Grip icon on the left side for repositioning
• Widget Title - Shows the custom title or chart name (or "Widget" if no title is set)
• Size Indicator - Small label showing current dimensions (e.g., "4x3")
• Edit Button - Pencil icon that opens the widget editor
• Delete Button - Trash icon that removes the widget after confirmation

Editing Widgets

Click the edit button on any widget to open the edit dialog and modify its configuration:

• Change Widget Type - Switch between chart and text widgets
• Update Chart Selection - Choose a different chart to display (for chart widgets)
• Modify Title - Change the widget title or toggle title visibility
• Adjust Position - Fine-tune column and row coordinates
• Resize Precisely - Set exact width and height values
• Customize Background - Change the background color using the color picker

Deleting Widgets

Removing widgets is straightforward but includes a safety confirmation:

• Click Delete Button - Click the trash icon in the widget header
• Confirm Removal - A confirmation dialog appears asking "Are you sure you want to remove this widget?"
• Immediate Removal - Confirming removes the widget from the dashboard instantly
• Save Required - Remember to save the dashboard to persist the deletion

Dashboard Settings

Configure dashboard-wide settings that affect all widgets and the overall dashboard behavior.

Basic Settings

Saving and Exporting

VisualLeaf provides flexible options for saving and backing up your dashboard configurations.

Saving Dashboards

Click the "Save" button in the toolbar to store your dashboard configuration:

• First Save (New Dashboard) - Creates a new dashboard in your workspace and assigns it a unique ID
• Subsequent Saves (Updates) - Updates the existing dashboard with your latest changes
• Save Feedback - The button shows "Saving..." during the save operation and displays a success message when complete
• Validation - The dashboard name is required before saving - you'll be prompted if it's missing
• Chart Data Reload - After saving, chart data is automatically reloaded to ensure all visualizations are current
• Return to View Mode - After a successful save, you are automatically returned to view mode to see your dashboard with live data

What Gets Saved

When you save a dashboard, VisualLeaf stores the complete configuration:

• Dashboard Properties - Name, description, and grid settings
• Widget Configurations - All widgets with their type, position, size, and content
• Chart References - Links to the saved charts used in chart widgets (not the chart data itself)
• Layout Information - Exact grid positions and dimensions for every widget
• Styling Options - Custom colors, title visibility, and other visual preferences

Exporting Dashboards

Click "Export JSON" to download a complete backup of your dashboard configuration:

• JSON Format - Downloads a JSON file containing the entire dashboard structure
• Backup and Sharing - Use exported files as backups or share dashboard configurations with team members
• Version Control - Store dashboard JSON files in version control systems to track changes over time
• Migration - Export from one VisualLeaf instance and import into another

Chart Widget Behavior

Chart widgets display saved charts from your chart library and handle data loading intelligently based on connection status.

Data Loading

Chart widgets automatically load and display data from your MongoDB connections:

• Automatic Query Execution - When a chart widget is added, VisualLeaf automatically executes the chart's query or aggregation pipeline
• Connection Status Check - Before querying, the widget verifies that the required database connection is active
• Query Type Support - Handles both find queries and aggregation pipelines based on the chart configuration
• Data Transformation - Raw MongoDB data is automatically transformed into chart-ready format
• Live Rendering - Charts render in real-time as data is loaded and transformed

Connection States

Chart widgets behave differently based on the database connection status:

• Connected - Widget executes the query and displays current data from the database
• Disconnected - Widget shows the last saved chart data (if available) or a placeholder message
• No Saved Data - If disconnected and no cached data exists, displays "Loading chart..." message

Chart Types Supported

Dashboard chart widgets support all VisualLeaf chart types:

• Basic Charts - Bar, Line, Area, Pie, Donut
• Statistical Charts - Scatter, Bubble, Radar, Heatmap
• Geographic Charts - Geo Map, Geo Scatter, Geo Heatmap
• Hierarchical Charts - Treemap, Sunburst, Sankey
• Specialized Charts - Funnel, Gauge, Timeline, Calendar, Candlestick

Chart Responsiveness

Charts automatically adapt to widget size changes:

• Auto-Resize - Charts redraw when you resize their widget container
• Aspect Ratio - Visualizations maintain proper proportions regardless of widget dimensions
• Text Scaling - Labels, legends, and axes adjust to fit the available space
• Performance Optimization - Charts use efficient rendering techniques even in small widget sizes

Common Actions

• Add Widget - Opens the widget creation dialog where you can select chart or text widgets to add to your dashboard. You can select multiple charts at once to add them all in a single operation with automatic layout.
• Drag Widget - Click and hold the widget's drag handle (header bar with grip icon), then move your mouse to reposition the widget anywhere on the grid. The widget snaps to grid columns and rows for clean alignment.
• Resize Widget - Hover over any edge or corner of a widget to reveal resize handles. Click and drag to make the widget span more or fewer columns and rows. Charts automatically redraw to fit the new size.
• Edit Widget - Click the edit (pencil) icon in a widget's header to open the edit dialog. Modify the widget's chart selection, title, position, dimensions, or background color, then click "Update Widget" to apply changes.
• Delete Widget - Click the delete (trash) icon in a widget's header. Confirm the removal in the dialog that appears. The widget is immediately removed from the dashboard (remember to save the dashboard to persist the deletion).
• Save Dashboard - Click "Save" in the toolbar to store your dashboard configuration. For new dashboards, this creates a new saved dashboard. For existing dashboards, this updates the saved configuration with your latest changes.
• Export JSON - Click "Export JSON" to download the complete dashboard configuration as a JSON file. Use this for backups, sharing dashboard layouts with colleagues, or migrating dashboards between VisualLeaf instances.
• Close Editor - Click the back arrow button in the top-left corner to close the dashboard editor and return to the previous screen. Any unsaved changes will be lost, so save first if you want to keep your modifications.

Dashboard Design Best Practices

Follow these guidelines to create effective, professional dashboards that communicate insights clearly.

Layout and Organization

• Group Related Metrics - Place charts that show related information near each other for easy comparison
• Use Consistent Sizes - Similar types of charts should generally be the same size for visual harmony
• Prioritize Important Data - Place the most critical charts in the top-left area where eyes naturally look first
• Leave White Space - Don't fill every grid cell - strategic spacing makes dashboards easier to scan
• Align Widgets - Line up widget edges horizontally and vertically for a clean, professional appearance

Chart Selection

• Choose Appropriate Types - Use bar charts for comparisons, line charts for trends, pie charts for proportions
• Limit Chart Count - 4-8 charts is usually optimal - too many creates information overload
• Mix Chart Types - Variety makes dashboards more engaging and helps communicate different data aspects
• Consider Update Frequency - Place frequently-changing data in prominent positions

Titles and Labels

• Use Descriptive Titles - Widget titles should clearly explain what the chart shows
• Be Consistent - Use similar title styles across all widgets for cohesion
• Show Titles Selectively - Hide titles for obvious charts to reduce clutter, show them for complex visualizations
• Name Dashboards Clearly - Use names that indicate the dashboard's purpose (e.g., "Sales Overview", "Server Monitoring")

Performance Considerations

• Optimize Chart Queries - Use efficient queries with appropriate limits to ensure fast dashboard loading
• Use Aggregation - Pre-aggregate data in MongoDB rather than loading raw documents when possible
• Limit Data Points - Charts with thousands of data points can be slow to render - aggregate or sample when needed
• Connection Management - Ensure database connections are active before opening dashboards

Pro Tips

• Add multiple charts at once - Select multiple charts when adding widgets to quickly populate a new dashboard with an automatic grid layout. You can rearrange them afterward.
• Use text widgets for context - Use text widgets to add section headers or explanatory notes directly on your dashboard. This provides context for viewers who may not be familiar with the data.
• Size indicator for consistency - The size indicator in each widget header (e.g., "4x3") helps you create consistent layouts by ensuring similar widgets use the same dimensions.
• Export JSON before changes - Export your dashboards as JSON files before making major changes. This creates a backup you can reference or restore if needed.
• Keep dashboards focused - Create separate dashboards for different audiences or purposes rather than cramming everything into one. Keep each dashboard focused on a specific story or use case.
• Design for display size - When designing dashboards, consider how they'll be viewed. A dashboard for a large monitor can be more detailed than one intended for smaller screens.
• Automatic theme adaptation - Chart widgets automatically adapt to dark/light mode based on your theme settings - no need to configure colors separately for each theme.
• Smart grid repositioning - The grid prevents overlapping, but widgets will push others out of the way if you drag them into occupied space. Use this to quickly rearrange multiple widgets.
• Offline data display - When a database connection is disconnected, chart widgets show their last saved data rather than failing. This means dashboards remain viewable even offline.

Troubleshooting

Charts Not Displaying

If a chart widget shows a placeholder instead of data:

• Check Connection Status - Ensure the database connection for the chart is active
• Verify Chart Configuration - Open the chart in the chart editor to confirm it has valid query and data mapping settings
• Review Query Results - The chart query may be returning no data - test it in the chart editor
• Reload Widget Data - Save the dashboard to trigger a data reload for all widgets

Can't Resize or Drag Widgets

If widgets seem stuck in place:

• Use the Drag Handle - Dragging only works when you grab the header bar with the grip icon
• Hover for Resize Handles - Resize handles appear on hover - ensure your mouse is over an edge or corner
• Check for Dialogs - Close any open dialogs (like the add/edit widget dialog) before manipulating widgets
• Refresh the Grid - Save and reload the dashboard to reset the grid state

Dashboard Won't Save

If the save operation fails:

• Add a Name - Dashboard names are required - ensure you've entered one in the toolbar
• Check Error Messages - Look for validation error messages in the interface
• Verify Permissions - Ensure you have permission to save dashboards in your VisualLeaf instance
• Try Again - Network issues can cause save failures - wait a moment and retry

Multiple Widget Selection Issues

If adding multiple charts doesn't work as expected:

• Verify Chart Selection - Check the selection counter to ensure charts are actually selected
• Use Checkboxes - Click directly on the checkboxes rather than the chart name labels
• Clear and Retry - Use "Clear All" then manually select the charts you want
• Add Individually - As a fallback, add charts one at a time if bulk addition fails

Related Features

• Chart Builder - Create and configure the charts that power your dashboard widgets
• Aggregation Pipeline - Build advanced data transformations to feed your dashboard charts
• Connection Manager - Manage the database connections that provide data to your charts
• Dashboard Viewer - View saved dashboards in presentation mode with auto-refresh capabilities
• VisuaLeaf Config - Configure dark/light mode that automatically applies to dashboard charts