Welcome Guest to forager.com a foragers site.!

Theme System Documentation

Table of Contents

Overview

The Comserv Theme System provides a flexible and maintainable approach to styling the application. It allows for site-specific themes, custom color schemes, and centralized style management while maintaining backward compatibility with existing CSS.

This system replaces the previous approach of having separate CSS files for each site with a more structured theme-based approach that promotes consistency and reduces duplication.

Goals

The primary goals of the theme system are:

Implementation Plan

The theme system is being implemented in a progressive manner to ensure backward compatibility and minimize disruption:

  1. Phase 1: Fallback Theme Selection
    • Modify Header.tt to use fallback methods for theme selection
    • Implement name-based theme selection (e.g., 'apis' for Apis site)
    • Set up file-based theme preference storage in theme_mappings.json
    • Ensure the system works without requiring database changes
  2. Phase 2: Theme Administration
    • Create ThemeAdmin controller to work without requiring the theme column
    • Implement file-based theme preference storage (theme_mappings.json)
    • Add theme preview functionality in the admin interface
    • Add appropriate feedback for administrators about theme system status
  3. Phase 3: Database Migration
    • Add the theme column to the sites table
    • Run the add_theme_column.pl script
    • System will automatically start using the database column
  4. Phase 4: Testing
    • Test theme creation and application with both file-based and database approaches
    • Verify that themes are correctly applied to sites
    • Ensure backward compatibility with existing CSS files

This progressive approach allows for incremental implementation and testing, ensuring that each phase works correctly before proceeding to the next. The system will continue to function with the existing CSS configuration until fully migrated to the database-driven version.

Theme Structure

Each theme consists of a CSS file located in the /static/css/themes/ directory. The theme files use CSS variables (custom properties) to define colors, fonts, and other style elements that can be customized.

Base Theme

The base theme (default.css) defines the core styles and variables used by all themes. It includes:

:root {
  --primary-color: #ffffff;
  --secondary-color: #f9f9f9;
  --accent-color: #FF9900;
  --text-color: #000000;
  --link-color: #0000FF;
  --link-hover-color: #000099;
  --background-color: #ffffff;
  --border-color: #dddddd;
  --table-header-bg: #f2f2f2;
  --warning-color: #f39c12;
  --success-color: #27ae60;
  
  --button-bg: var(--primary-color);
  --button-text: #ffffff;
  --button-border: var(--primary-color);
  --button-hover-bg: var(--secondary-color);
}

Custom Themes

Custom themes override these variables to create different visual styles without changing the underlying HTML structure.

Theme File Organization

Theme files are organized in the following structure:

/static/css/themes/
├── default.css          # Base theme with core variables
├── apis.css             # Apis-specific theme
├── usbm.css             # USBM-specific theme
├── csc.css              # CSC-specific theme
└── site_name_custom.css # Custom themes for specific sites

Creating Custom Themes

Custom themes can be created in two ways:

1. Manual Creation

Create a new CSS file in the /static/css/themes/ directory that overrides the default variables:

/* custom_theme.css */
:root {
  --primary-color: #9b59b6;
  --secondary-color: #34495e;
  --accent-color: #f1c40f;
  /* Override other variables as needed */
}

2. Admin Interface

Use the theme management interface in the admin area to create a custom theme by selecting colors and other options. The system will generate the CSS file automatically.

Admin Interface

The theme system includes an admin interface for managing themes, accessible at /admin/theme.

Features

Access Requirements

To access the theme management interface, users must:

Migration Guide

To migrate an existing site to the theme system:

  1. Ensure the 'theme' column exists in the sites table
    • Run the add_theme_column.pl script to add it if needed
  2. Create a theme file for your site
    • Copy default.css to your_site_name.css
    • Modify the CSS variables to match your site's color scheme
  3. Set the theme for your site
    • Use the admin interface at /admin/theme to select your theme
    • Or update the database directly: UPDATE sites SET theme = 'your_theme_name' WHERE name = 'YOUR_SITE_NAME';
  4. Test your site to ensure styles are applied correctly

Troubleshooting

Common Issues

Theme not loading
  • Check theme_mappings.json if database column is not yet available
  • Verify file permissions on theme files and directories
  • Check that the theme file exists in /static/css/themes/
  • Verify that the site record has the correct theme name in the database
  • Clear your browser cache
Database errors about missing theme column
  • Run the add_theme_column.pl script
  • Or manually add the column: ALTER TABLE sites ADD COLUMN theme VARCHAR(50) DEFAULT 'default';
Custom theme not applying correctly
  • Check that your CSS variables are correctly defined
  • Ensure there are no syntax errors in your CSS file
  • Verify that the theme is correctly assigned to your site
cm