Custom Theme Support for Embedded Analytics

Follow

Overview

DataClarity's embedded analytics platform now supports custom themes, allowing customers to apply user-specific and role-specific CSS styling to white-label their analytics dashboards and maintain brand consistency.

What are Custom Themes?

Custom themes let you:

• Brand your analytics with your company's colors and styling
• Apply different themes to different users or roles
• Create multiple theme variations for different audiences
• Customize the look and feel without modifying code

How Custom Themes Work

Custom themes use CSS classes that are automatically applied based on user settings in User Access Management. When you set a customTheme attribute for a user or role, the system adds a CSS class called theme-[your-theme-name] to the page, which you can then style with your custom CSS.

Setup Guide

Step 1: Set Custom Theme in User Access Management

1. Navigate to User Access Management
2. Choose User-Level or Role-Level Configuration:
   • For individual users: Edit user attributes
   • For all Storyboards Consumer users: Edit the licensed role attributes

3. Add the customTheme attribute:

   Attribute Name: customTheme

   Value: corporate

Step 2: Create Your Theme CSS

Create a CSS file with your brand styling. The theme name you set becomes a CSS class with the prefix theme-:

/* Example: Corporate Theme (customTheme: corporate) */

.theme-corporate {

    /* Your brand colors */

    --brand-primary: #1e40af;

    --brand-secondary: #3b82f6;

}

.theme-corporate .storyboard-header {

    background-color: var(--brand-primary);

    color: white;

}

.theme-corporate .dashboard-panel {

    border-left: 4px solid var(--brand-secondary);

}

/* Example: Dark Theme (customTheme: dark) */

.theme-dark {

    --bg-color: #1f2937;

    --text-color: #f9fafb;

}

.theme-dark body {

    background-color: var(--bg-color);

    color: var(--text-color);

}

Step 3: Apply Your CSS

Include your custom theme CSS file in your Storyboards deployment or embed it in your application that hosts the embedded analytics.

Step 4: Test Your Theme

1. Login with a user that has the customTheme attribute set
2. Verify your styling is applied to the Storyboards interface
3. Check that the CSS class appears in the page's HTML (e.g., theme-corporate)

Usage Examples

Single Theme

Set a user's customTheme attribute to apply one theme:

customTheme: corporate

This creates the CSS class: theme-corporate

Multiple Themes

You can apply multiple themes by separating them with spaces:

customTheme: corporate dark

This creates two CSS classes: theme-corporate theme-dark

Role-Based Themes

Apply themes to entire licensed roles:

• Storyboards Consumer role: brand-theme for all consumer users
• Admin users: admin-theme for administrative styling
• Executive users: executive-theme for executive dashboards

Theme Configuration Options

Theme Name Requirements

Theme names must follow CSS class naming rules:

• Valid characters: Letters, numbers, hyphens, underscores
• Cannot start with: Numbers
• Examples: corporate, dark-mode, brand_2024

Multiple Theme Combinations

You can combine multiple themes for complex styling:

customTheme: brand-colors dark-mode high-contrast

This applies three CSS classes that work together:

• theme-brand-colors
• theme-dark-mode
• theme-high-contrast

CSS Best Practices

Use CSS Custom Properties

.theme-corporate {

    --brand-primary: #2563eb;

    --brand-secondary: #7c3aed;

    --brand-accent: #059669;

}

.theme-corporate .button {

    background-color: var(--brand-primary);

}

Theme-Specific Overrides

/* Default styling */

.dashboard-header {

    background: #ffffff;

    color: #000000;

}

/* Corporate theme override */

.theme-corporate .dashboard-header {

    background: var(--corporate-blue);

    color: white;

}

Responsive Theme Support

.theme-mobile {

    /* Mobile-specific theme adjustments */

}

@media (max-width: 768px) {

    .theme-corporate .sidebar {

        background: var(--mobile-bg);

    }

}

Troubleshooting

Common Issues

1. Themes Not Applied

• Check JWT token contains customTheme attribute
• Verify CSS files are loaded
• Confirm theme names are valid (no spaces, special characters)

2. Multiple Themes Conflict

• Check CSS specificity and order
• Use more specific selectors for conflicting rules
• Test theme combinations thoroughly

3. JavaScript Errors

• Check browser console for errors
• Verify userAccessService is loaded before theme application
• Ensure proper error handling in custom code

Debug Steps

1. Check JWT Token:

   console.log(userAccessService.getCustomTheme());

2. Verify CSS Classes:

   console.log(document.body.className);

3. Test Theme Detection:

   // Add to browser console

   userAccessService.getCustomTheme();

Security Considerations

• Theme validation: All theme names are validated for CSS safety
• XSS prevention: No user input directly inserted into DOM
• Access control: Themes controlled through authenticated JWT tokens
• Sanitization: Theme names are sanitized before CSS class application

Performance Impact

• Minimal overhead: Theme detection runs once on page load
• CSS-only styling: No JavaScript performance impact during usage
• Efficient selectors: Uses fast CSS class selectors
• Caching: Theme CSS files can be cached by browsers

Browser Compatibility

Custom theme support works with:

• Chrome: 60+
• Firefox: 55+
• Safari: 12+
• Edge: 79+
• Internet Explorer: Not supported

Migration Guide

From Static Themes

If you're currently using static theme switching:

1. Extract theme CSS into separate files
2. Convert theme switches to use CSS classes
3. Update selectors to use .theme-* prefixes
4. Configure user attributes in User Access Management
5. Test theme combinations

From Custom Implementations

If you have custom theme implementations:

1. Review existing theme structure
2. Map themes to new CSS class system
3. Update theme assignment logic
4. Migrate to JWT-based theme detection
5. Test backward compatibility

Support and Maintenance

Monitoring Themes

• Monitor browser console for theme-related warnings
• Track theme usage through analytics
• Test new themes across different browsers
• Validate theme performance impact

Updating Themes

• Version your CSS theme files
• Test theme updates in staging environment
• Provide fallback themes for deprecated designs
• Document theme changes for users

Conclusion

Custom theme support provides a powerful, flexible way to brand embedded analytics dashboards. By leveraging JWT tokens, CSS classes, and frontend automation, customers can achieve sophisticated theming without code changes.

The system is designed for:

• Easy implementation with minimal setup
• Robust error handling for production environments
• Flexible theming options for diverse branding needs
• Performance optimization for large-scale deployments

For technical support or advanced customization requirements, contact the DataClarity development team.