diff --git a/docs/themes/index.md b/docs/themes/index.md index 58e4edaaa..3555ee052 100644 --- a/docs/themes/index.md +++ b/docs/themes/index.md @@ -1,4 +1,72 @@ -# Theme Support in SageWorks +# Theming Strategy for SageWorks Dashboard + +## **Phase 1: Application Start-Up Theming** +This focuses on setting a polished, cohesive interface at startup. It ensures: + +1. **CSS and Plotly Templates at Start-Up**: + - The current system handles global styles via CSS (including Flask-served `custom.css`) and Plotly templates (via `pio.templates.default`) during app initialization. +2. **Highly Customizable Interface**: + - By leveraging both custom CSS and Plotly templates, you can style everything to match branding and preferences. + +### **Why Phase 1 Works Well** +- **Plotly Templates**: Figures are automatically styled if `pio.templates.default` is set before app initialization. +- **CSS**: Dynamically affects the entire app without additional callbacks. +- **Scalability**: Suitable for large apps since styles and templates are applied globally. + +

+ +## **Phase 2: Dynamic Theme Switching** +Dynamic theme switching allows users to toggle between themes (e.g., light and dark) at runtime. This is more complex, and splitting it into its own phase will reduce the complexity of each Phase. + +### **Challenges with Dynamic Switching** +1. **Encapsulation Barriers**: + - A centralized callback for theme switching needs to know about every figure or component in the app, which is not scalable. +2. **Dynamic Content/Plugins**: + - We have plugin pages, views, and components. A Typical app has 20 figures dynamically created, adding complexity to centralized callbacks. + + + +### **Proposed Solution: `set_theme()` Method** +Introduce a `set_theme()` method in each component to manage its own updates: + +- **Figures**: Update their `layout.template` or regenerate themselves. +- **HTML/CSS Components**: Dynamically update styles or toggle CSS classes. + +### **Advantages of `set_theme()`** +1. **Encapsulation**: + - Each component knows how to update itself based on the theme. +2. **Simple Callback**: + - The theme switch callback iterates through all registered components and calls their `set_theme()` method. +3. **Scalable**: + - Suitable for multi-page apps with many dynamic components. + + + +## **How the Two Phases Work Together** +### Phase 1: +- **Focus**: Global theming at app start-up. +- **What Works**: + - Plotly templates are applied to all figures by default. + - CSS styles are applied across the app. + +### Phase 2: +- **Focus**: Extend components to dynamically update their theme. +- **What to Add**: + - Extend components with a `set_theme(theme_name: str)` method. + - The callback triggers `set_theme()` for each registered component. + + + +## **Next Steps** +- **Phase 1**: Finalize CSS and Plotly template integration for start-up theming. +- **Phase 2**: Begin implementing a `set_theme()` system for individual components. + +


+


+ + +## Storage +### Theme Support in SageWorks For a Dash/Plotly web applications there are two main concepts that fall under the general umbrella of 'theme support'. ### CSS for High-Level Theming @@ -16,7 +84,6 @@ For a Dash/Plotly web applications there are two main concepts that fall under t - Apply globally or on a per-figure basis. - **Great Resource**: [dash-bootstrap-templates](https://github.com/AnnMarieW/dash-bootstrap-templates) - ### How They Complement Each Other 1. **CSS handles the web app’s overall look**: