Theme System

Theme System

Theme Overview

What are Themes?

Themes control the visual appearance and layout of your forum:

• Colors and Styles - Visual design
• Layout Structure - Page organization
• Typography - Fonts and text styling
• Components - UI elements styling

Theme Structure

themes/
└── my-theme/
    ├── theme.json           # Theme metadata
    ├── assets/              # CSS, JS, images
    │   ├── css/
    │   │   ├── frontend.css
    │   │   └── admin.css
    │   ├── js/
    │   │   └── main.js
    │   └── img/
    │       └── logo.png
    └── views/               # Template overrides (optional)
        └── layouts/

Theme Configuration

theme.json

Every theme requires a theme.json file:

{
  "name": "My Theme",
  "id": "my-theme",
  "version": "1.0.0",
  "description": "A custom theme for Flatboard 5",
  "author": "Your Name",
  "author_url": "https://example.com",
  "author_email": "author@example.com",
  "screenshot": "screenshot.png",
  "requires": {
    "flatboard": ">=5.0.0"
  },
  "styles": [
    "assets/css/frontend.css"
  ],
  "scripts": [
    "assets/js/main.js"
  ],
  "variables": {
    "primary_color": "#007bff",
    "secondary_color": "#6c757d"
  },
  "hide_color_settings": false,
  "theme_settings": {},
  "form_config": {}
}

Advanced Configuration Options

Hide Color Settings

If your theme manages colors differently (e.g., using CSS variables or external frameworks), you can hide the color customization panel:

{
  "hide_color_settings": true
}

When set to true, the color settings section will not appear in the admin panel. This is useful for themes like Bootswatch that manage colors through their own system.

Advanced Theme Settings

Add custom configuration options that appear in the admin panel:

{
  "theme_settings": {
    "layout_style": "default",
    "enable_animations": true,
    "custom_option": "value"
  }
}

Form Configuration (form_config)

Create advanced configuration forms with multiple field types:

{
  "form_config": {
    "form_id": "my_theme_config",
    "form_title": "Theme Configuration",
    "submit_text": "Save Settings",
    "fields": {
      "layout_style": {
        "type": "select",
        "label": "Layout Style",
        "description": "Choose the layout style",
        "default": "default",
        "category": "general",
        "options": {
          "default": "Default",
          "wide": "Wide",
          "compact": "Compact"
        }
      },
      "enable_animations": {
        "type": "checkbox",
        "label": "Enable Animations",
        "description": "Enable smooth animations",
        "default": true,
        "category": "general"
      },
      "custom_html": {
        "type": "textarea",
        "label": "Custom HTML",
        "description": "Add custom HTML content",
        "default": "",
        "category": "advanced"
      }
    },
    "categories": {
      "general": "General",
      "advanced": "Advanced"
    }
  }
}

Supported field types:

• select - Dropdown menu with options
• checkbox - Boolean checkbox
• textarea - Multi-line text input (supports HTML)
• text - Single-line text input

Creating a Theme

Step 1: Create Directory

mkdir -p themes/my-theme/assets/{css,js,img}

Step 2: Create theme.json

Create the theme configuration file with metadata.

Step 3: Create Stylesheet

assets/css/frontend.css:

/* Theme Variables */
:root {
  --primary-color: #007bff;
  --secondary-color: #6c757d;
  --background-color: #ffffff;
  --text-color: #212529;
  --border-color: #dee2e6;
}

/* Global Styles */
body {
  font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, sans-serif;
  background-color: var(--background-color);
  color: var(--text-color);
}

/* Header */
.header {
  background-color: var(--primary-color);
  color: white;
  padding: 1rem;
}

/* Navigation */
.nav {
  display: flex;
  gap: 1rem;
}

/* Buttons */
.btn {
  padding: 0.5rem 1rem;
  border: none;
  border-radius: 0.25rem;
  background-color: var(--primary-color);
  color: white;
  cursor: pointer;
}

.btn:hover {
  opacity: 0.9;
}

Step 4: Create JavaScript (Optional)

assets/js/main.js:

// Theme JavaScript
document.addEventListener('DOMContentLoaded', function() {
  // Your theme-specific JavaScript
  console.log('Theme loaded!');
});

Theme Customization

CSS Variables

Use CSS variables for easy customization:

:root {
  --theme-primary: #007bff;
  --theme-secondary: #6c757d;
  --theme-background: #ffffff;
  --theme-text: #212529;
}

Color Schemes

Support light/dark modes:

/* Light mode */
:root {
  --bg-color: #ffffff;
  --text-color: #000000;
}

/* Dark mode */
[data-theme="dark"] {
  --bg-color: #1a1a1a;
  --text-color: #ffffff;
}

Responsive Design

Use media queries for mobile support:

/* Desktop */
.container {
  max-width: 1200px;
  margin: 0 auto;
}

/* Tablet */
@media (max-width: 768px) {
  .container {
    max-width: 100%;
    padding: 0 1rem;
  }
}

/* Mobile */
@media (max-width: 480px) {
  .container {
    padding: 0 0.5rem;
  }
}

Installing a Theme

Method 1: From the Admin Panel (Recommended, since 5.2.2)

1. Download the theme .zip from the Flatboard Resource Center or from the theme author
2. Go to Admin → Themes
3. Click "Install a theme"
4. Select the .zip archive and confirm — the archive is validated, extracted, and the theme appears in the list automatically

The server validates the archive integrity, MIME type, size, and the presence of a valid theme.json before extracting.

Method 2: Manual Installation (FTP / SSH)

The manual workflow is: download → extract locally → upload the folder → activate.

Step 1: Download and Extract

1. Download the theme .zip from the Flatboard Resource Center or from the theme author
2. Extract the archive on your local machine — you should get a folder (e.g. my-theme/) with theme.json at its root

Step 2: Upload the Theme Folder

Via FTP

Connect to your server with an FTP client (FileZilla, Cyberduck, etc.) and upload the extracted theme folder into the themes/ directory of your Flatboard installation:

your-flatboard/
└── themes/
    └── my-theme/         ← upload this folder (not the .zip)
        ├── theme.json
        └── assets/

Via SSH

If you have shell access, extract directly on the server:

cd /path/to/your-flatboard/themes/
unzip my-theme.zip     # extracts to my-theme/

Step 3: Activate the Theme

Once the folder is uploaded, go to Admin → Themes, find your theme in the list, and click Activate. The theme is applied immediately.

Activating an Installed Theme

From Admin Panel

1. Go to Admin → Themes
2. Find your theme in the list
3. Click Activate
4. Theme is immediately active

Manual Activation

If needed, you can manually set the active theme by editing config.json:

{
  "theme": {
    "active": "my-theme"
  }
}

Template Overrides

Override Views

Create custom templates:

themes/my-theme/views/
├── layouts/
│   └── main.php
├── discussions/
│   └── list.php
└── posts/
    └── view.php

Template Hierarchy

Flatboard 5 checks in this order:

1. Theme views (if exists)
2. Default views

Theme Best Practices

Design Principles

• Consistency - Maintain consistent styling
• Accessibility - Ensure WCAG compliance
• Performance - Optimize CSS and JS
• Responsiveness - Support all screen sizes

Code Quality

• Organize CSS - Use logical structure
• Comment Code - Add helpful comments
• Minimize CSS - Remove unused styles
• Validate - Validate CSS/HTML

Testing

• Multiple Browsers - Test in Chrome, Firefox, Safari, Edge
• Mobile Devices - Test on phones and tablets
• Different Resolutions - Test various screen sizes
• Accessibility - Test with screen readers

Default Themes

Flatboard 5 includes several default themes:

Default Theme

• Name: Default
• Description: Thème par défaut de Flatboard 5 avec un design moderne et épuré, supportant les modes clair et sombre
• Version: 5.0.0
• Edition: Available in both Community and Pro editions
• Clean, modern design
• Responsive layout
• Light and dark mode support
• Customizable color variables
• Standard theme settings

Premium Theme

• Name: Premium
• Description: Thème premium sophistiqué démontrant toutes les possibilités avancées de personnalisation de Flatboard 5
• Version: 5.0.0
• Edition: Available in Pro edition only
• Advanced customization options
• Multiple layout options (default, centered, wide, compact)
• Animation support (none, subtle, normal, high)
• Parallax effects
• Customizable hero sections
• Advanced form configuration (form_config)
• Multiple navbar styles (default, glass, solid, transparent)
• Card styles (elevated, bordered, minimal)
• Extensive theme settings

Bootswatch Theme

• Name: Bootswatch
• Description: Thème intégrant tous les thèmes Bootswatch pour Bootstrap 5. Sélectionnez parmi 26 thèmes Bootswatch disponibles
• Version: 1.0.0
• Edition: Available in both Community and Pro editions
• Based on Bootstrap 5
• 26 color schemes available (Brite, Cerulean, Cosmo, Cyborg, Darkly, Flatly, Journal, Litera, Lumen, Lux, Materia, Minty, Morph, Pulse, Quartz, Sandstone, Simplex, Sketchy, Slate, Solar, Spacelab, Superhero, United, Vapor, Yeti, Zephyr)
• Professional appearance
• Theme selector in admin panel
• Color settings hidden (hide_color_settings: true) - colors managed by Bootswatch system

Futurist CyberNeon Theme

• Name: Futurist CyberNeon
• Description: Thème futuriste ultra-moderne avec des néons cyberpunk, des effets lumineux dynamiques et un design immersif
• Version: 5.1.0
• Cyberpunk aesthetic
• Neon glow effects
• Holographic effects
• Animated gradients
• Perfect for tech and gaming communities

Nord Theme

• Name: Nord
• Description: Thème arctique inspiré de Nord Theme avec une palette de couleurs polaire harmonieuse
• Version: 1.0.0
• Arctic color palette
• Polar-inspired design
• Clean and minimal

Christmas Theme

• Name: Christmas 2025
• Description: Thème festif de Noël avec animations de flocons de neige, couleurs chaleureuses et effets visuels magiques
• Version: 1.0.0
• Festive holiday design
• Snowflake animations
• Garland effects
• Warm color scheme

Theme Customization via Admin

Most themes support admin customization through the admin panel:

1. Go to Admin → Themes
2. Select active theme
3. Click "Customize" or "Configure"
4. Modify settings:
   • Color Variables - Customize primary, secondary, background, and text colors (unless hide_color_settings is enabled)
   • Theme Settings - Configure theme-specific options defined in theme_settings
   • Advanced Configuration - Use form_config for complex settings with multiple field types
   • Logo Configuration - Upload and configure theme logo
5. Preview changes
6. Save

Color Customization

By default, themes expose color variables that can be customized in the admin panel:

• Primary and secondary colors
• Success, danger, warning, info colors
• Background colors (light and dark modes)
• Text colors (light and dark modes)

Advanced Configuration

Themes can define advanced configuration forms using form_config:

• Select Fields - Dropdown menus with predefined options
• Checkboxes - Boolean toggles for features
• Text Areas - Multi-line inputs (supports HTML for custom content)
• Text Fields - Single-line inputs
• Categories - Organize settings into groups

These settings are automatically saved and can be accessed in your theme's PHP templates via the theme configuration system.

Troubleshooting

Theme Not Loading

Check:

1. Theme directory structure is correct
2. theme.json is valid
3. CSS/JS files exist
4. Check error logs

Styles Not Applying

Solution:

1. Clear browser cache
2. Clear Flatboard cache
3. Check CSS file paths
4. Verify file permissions

Theme Conflicts

Solution:

1. Deactivate other themes
2. Check for CSS conflicts
3. Review theme code
4. Test in isolation

Migration from Flatboard 4

Migration Steps

1. Analyze Old Theme - Review structure and styles
2. Create New Structure - Set up Flatboard 5 theme structure
3. Port Styles - Adapt CSS to new HTML
4. Update Templates - Recreate template overrides
5. Test - Test all pages and features

Publishing Your Theme

Once you've created your theme, you can share it with the Flatboard community by publishing it in the Flatboard Resource Center.

Publishing Requirements

Before submitting your theme, ensure:

• ✅ Theme follows Flatboard 5 structure
• ✅ theme.json is complete and valid
• ✅ Screenshot included (screenshot.png)
• ✅ Theme is tested and working
• ✅ Documentation included (README.md)
• ✅ No security vulnerabilities
• ✅ Compatible with latest Flatboard 5 version

Submit Your Theme

1. Visit the Flatboard Resource Center
2. Log in to your account
3. Select "Theme" as resource type
4. Fill in theme information:
   • Theme name and description
   • Version number
   • Compatibility (Community/Pro/Both)
   • Screenshot
   • Download link or file
5. Submit for review

Theme Distribution

After approval, your theme will be:

• Listed in the Resource Center
• Searchable by users
• Available for download
• Rated and reviewed by users
• Potentially featured if exceptional

Resources

• Plugin Guide - Plugin integration
• Developer Guide - Advanced development
• Troubleshooting - Common issues
• Flatboard Resource Center - Submit your theme

Last updated: March 12, 2026