Theme Overview

Complete guide to installing, managing, and customizing themes in PteroCA

Overview

Themes allow you to customize the visual appearance and user interface of your PteroCA panel. Introduced in v0.4, the theme system provides a flexible way to change colors, layouts, and the overall look of your installation without modifying core code.

What Themes Can Change

Themes control the appearance of:

• Admin Panel Interface: Colors, layouts, and styling of the administrative interface

• Client Area: Dashboard, server management, shop appearance

• Authentication Pages: Login, registration, password reset pages

• Email Templates: Branded email notifications

• Error Pages: Custom 404, 500, and other error pages

• Forms and Components: Input fields, buttons, and UI elements

Benefits of Using Themes

• Consistent Branding: Match your panel to your company's visual identity

• User Experience: Provide a unique and polished interface for your customers

• Dark Mode Support: Many themes offer automatic light/dark mode switching

• Easy Updates: Themes are isolated from core code, making PteroCA updates safer

• No Code Required: Install and configure themes through the Admin Panel

Theme System Available in v0.4+

The theme system was introduced in PteroCA v0.4. If you're running an earlier version, please upgrade to access theme functionality.

---

Theme Contexts

New in v0.6.3: PteroCA supports multiple theme contexts, allowing you to use different themes for different parts of your panel.

Available Contexts

PteroCA supports three distinct contexts:

Context	Description	Setting	Use Case
panel	Admin panel and client area	PANEL_THEME	Main panel interface, dashboard, server management
landing	Public landing page	LANDING_THEME	Marketing site, homepage, public-facing pages
email	Email templates	EMAIL_THEME	Transactional emails, notifications

How Context Works

Each theme declares which contexts it supports in its template.json file:

{
  "template": {
    "name": "my-theme",
    "contexts": ["panel", "email"]
  }
}

This theme can be activated for panel and email contexts, but not for landing pages.

Configuring Context-Specific Themes

You can set different themes for each context:

1. Navigate to Settings → Theme

2. Configure each context independently:

   • Panel Theme (PANEL_THEME) - Used for admin and client interfaces

   • Landing Theme (LANDING_THEME) - Used for public landing pages

   • Email Theme (EMAIL_THEME) - Used for email templates

3. Only themes supporting the specific context appear in each dropdown

Example configuration:

• Panel: "dark-professional" theme

• Landing: "marketing-bright" theme

• Email: "simple-email" theme

Single Theme for All Contexts

If a theme supports all three contexts, you can use the same theme everywhere for consistent branding. Simply select it for all three settings.

---

Default Theme

PteroCA comes with a built-in default theme that provides a modern, professional interface.

Default Theme Features

• Name: Default Theme

• Version: 1.1.1

• Author: PteroCA.com

• License: MIT

Capabilities:

• ✅ Full dark mode support (automatic light/dark switching)

• ✅ Custom color configuration (primary colors for light and dark modes)

• ✅ Bootstrap 5 based design

• ✅ Responsive layout (mobile-friendly)

• ✅ EasyAdmin integration (admin panel interface)

• ✅ Custom error pages (404, 500)

• ✅ Email template styling

Default Colors:

• Light mode primary: #4e73df (Blue)

• Dark mode background: #2e59d9 (Darker Blue)

The default theme is always available as a fallback if another theme fails to load.

---

Finding Themes

PteroCA Marketplace

PteroCA Marketplace - Official Theme Repository

The PteroCA Marketplace is the primary source for verified, curated themes. Browse professional themes, read reviews, and download securely.

Features:

• ✅ Security-reviewed themes

• ✅ Community reviews and ratings

• ✅ Verified developers

• ✅ Version compatibility checking

• ✅ Official and community themes

• ✅ Free and premium themes

Visit: marketplace.pteroca.com

Benefits of using the marketplace:

• Quality Assurance: Themes are reviewed for quality and compatibility

• Security: Themes undergo security checks before listing

• Support: Direct contact with theme developers

• Updates: Easy access to theme updates and new versions

• Reviews: Read real user experiences before downloading

Other Theme Sources

Community Resources:

• PteroCA Discord Server - Community theme sharing

• GitHub - Open-source themes

Third-Party Sources:

• Developer portfolios and personal websites

• Custom theme commissions from developers

Download Themes from Trusted Sources

Only install themes from developers you trust. Themes have access to your panel's templates and can potentially include malicious code. Always review theme files before installation.

Recommended: Use the PteroCA Marketplace for verified, security-reviewed themes.

Custom Themes

You can also commission custom themes from developers or create your own. See the Creating Your Own Themes section for more information.

---

Installing Themes

Installing a theme involves placing the theme files in the correct directory and ensuring proper structure.

Prerequisites

Before installing a theme:

• Access to your server's file system (SSH, SFTP, or file manager)

• Theme files (usually provided as a ZIP archive or folder)

• Write permissions on the /themes/ directory

Installation Steps

Step 1: Obtain Theme Files

1. Download the theme from a trusted source

2. Extract the archive if it's in ZIP format

3. Verify the theme folder contains a template.json file

Valid theme structure:

my-theme/
├── template.json          # Required: Theme metadata
├── base.html.twig        # Base template
├── assets/
│   ├── css/              # Stylesheets (optional)
│   ├── js/               # JavaScript (optional)
│   └── fonts/            # Custom fonts (optional)
├── panel/                # Admin panel templates (optional)
├── bundles/              # Bundle overrides (optional)
├── components/           # Reusable components (optional)
└── email/                # Email templates (optional)

Step 2: Upload Theme to Server

1. Connect to your server via SSH, SFTP, or file manager

2. Navigate to the PteroCA installation directory

3. Locate the /themes/ folder (e.g., /var/www/pteroca/themes/)

4. Upload/copy the theme folder into /themes/

Example:

# Via SSH
cd /var/www/pteroca/themes/
unzip my-theme.zip
# or
cp -r /path/to/my-theme ./

Result:

/var/www/pteroca/themes/
├── default/              # Default theme (always present)
│   └── template.json
└── my-theme/             # Your new theme
    └── template.json

Step 3: Set Permissions (if needed)

Ensure the web server can read the theme files:

chown -R www-data:www-data /var/www/pteroca/themes/my-theme
chmod -R 755 /var/www/pteroca/themes/my-theme

Replace www-data with your web server user if different (e.g., nginx, apache).

Step 4: Place Theme Assets (if applicable)

If the theme includes CSS, JavaScript, or image assets, place them in the public assets directory:

1. Navigate to /public/assets/theme/

2. Create a folder matching your theme name (e.g., my-theme)

3. Upload compiled assets (CSS, JS, images, fonts)

Example:

/public/assets/theme/
├── default/
│   ├── css/
│   ├── js/
│   └── fonts/
└── my-theme/
    ├── css/
    │   └── app.css       # Main stylesheet
    ├── js/
    │   └── custom.js     # Custom scripts
    └── img/
        └── logo.png      # Theme logo

Asset Directory Naming

The asset folder name must match your theme folder name. If your theme is /themes/my-theme/, assets must be in /public/assets/theme/my-theme/.

Step 5: Verify Installation

1. Log in to the Admin Panel

2. Navigate to Settings → Theme

3. Your theme should appear in the "Current theme" dropdown

4. If it doesn't appear, check the Troubleshooting section

---

Activating Themes

Once installed, you can activate a theme through the Admin Panel.

Activation Steps

1. Log in to the Admin Panel with an account that has theme management permissions

2. Navigate to Settings in the left sidebar

3. Click Theme in the settings menu

4. Locate the "Current theme of the panel" setting

5. Click Edit (pencil icon)

6. Select your desired theme from the dropdown list

7. (Optional) Click the ℹ️ icon next to a theme to view its information (version, author, features)

8. Click Save

What happens when you activate a theme:

1. ✅ System validates the theme has a valid template.json

2. ✅ Theme templates become active immediately (no restart needed)

3. ✅ Theme assets are loaded on next page load

4. ✅ Color and dark mode settings adjust based on theme capabilities

5. ✅ Users see the new theme on their next page load

Instant Theme Switching

Theme changes take effect immediately. Simply refresh your browser to see the new theme in action.

Switching Back to Default

If you encounter issues with a custom theme, you can always switch back to the default theme:

1. Go to Settings → Theme

2. Select "default" from the theme dropdown

3. Click Save

The system automatically falls back to the default theme if an active theme is invalid or missing.

---

Managing Themes

New in v0.6.3: PteroCA includes a comprehensive theme management interface for uploading, copying, exporting, and deleting themes.

Accessing Theme Management

1. Log in to the Admin Panel with theme management permissions

2. Navigate to Themes in the left sidebar

3. View all installed themes with their details

Theme List

The theme list displays:

• Name: Theme identifier and display name

• Version: Current theme version

• Author: Theme creator

• Contexts: Supported contexts (panel, landing, email)

• Status: Whether theme is currently active in any context

• Actions: Available operations (view, set default, copy, export, delete)

Theme Operations

Viewing Theme Details

1. Click on a theme in the list

2. View comprehensive information:

   • Metadata (name, version, author, license)

   • Supported contexts

   • Compatibility (PteroCA version, PHP version)

   • Feature support (dark mode, custom colors)

   • Active status per context

Setting Default Theme

1. Click Set Default button next to a theme

2. Select the context (panel, landing, or email)

3. Confirm the change

4. Theme becomes active for that context immediately

Requirements:

• Theme must support the selected context

• User must have set_default_theme permission

Uploading Themes

Upload new themes as ZIP packages:

1. Click Upload Theme button

2. Select a theme ZIP file

3. System validates:

   • Valid template.json file

   • Correct directory structure

   • Unique theme name (no conflicts)

4. Theme is extracted and registered

5. Assets are published to public directory

ZIP package structure:

my-theme.zip
└── my-theme/
    ├── template.json
    ├── panel/
    ├── landing/
    ├── email/
    └── assets/

Theme Name Conflicts

If a theme with the same name already exists, upload will fail. Delete or rename the existing theme first, or use the Copy feature to create a variant.

Copying Themes

Create a copy of an existing theme:

1. Click Copy button next to a theme

2. Enter a new name for the copy

3. System creates duplicate with new name

4. Edit the copy without affecting the original

Use cases:

• Create theme variants (light/dark versions)

• Backup before making changes

• Build on existing themes

Exporting Themes

Export themes as ZIP packages:

1. Click Export button next to a theme

2. System packages theme files and assets

3. Download ZIP archive

4. Share with others or backup

What's included:

• All template files

• template.json metadata

• Assets (CSS, JS, images)

• Proper directory structure for re-upload

Deleting Themes

Remove themes from the system:

1. Click Delete button next to a theme

2. Confirm deletion

3. Theme files and database records are removed

Restrictions:

• Cannot delete the default theme

• Cannot delete currently active themes

• Must deactivate theme from all contexts first

Deletion is Permanent

Deleted themes cannot be recovered unless you have a backup. Consider exporting themes before deletion.

---

Theme Configuration

Many themes support customization options, allowing you to adjust colors and appearance without modifying theme files.

Available Configuration Options

The configuration options available depend on your active theme's capabilities:

1. Current Theme

Setting: Current theme of the panel

Description: Select which theme is active for your panel.

Available for: All installations

How to use:

• Select from dropdown of installed themes

• Click the info icon to see theme details

• Save to apply immediately

2. Custom Colors (if supported)

Settings:

• Default color for light mode - Primary UI color in light mode

• Default background color for dark mode - Background color in dark mode

Description: Customize the color scheme of your theme without editing CSS files.

Available for: Themes with supportCustomColors: true in template.json

How to use:

1. Click the color picker field

2. Choose a color or enter a hex code (e.g., #FF5733)

3. Preview updates in real-time

4. Click Save to apply globally

What these colors affect:

• Light mode color: Buttons, links, active menu items, highlights

• Dark mode color: Sidebar background, content area background, dark mode UI elements

Theme Must Support Custom Colors

If you don't see color configuration options, your active theme doesn't support custom colors. Switch to a different theme or contact the theme developer.

3. Dark Mode Settings (if supported)

Setting: Disable dark mode

Description: Completely disable dark mode for all users.

Available for: Themes with supportDarkMode: true in template.json

Options:

• Unchecked (default): Users can toggle between light and dark modes

• Checked: Dark mode is disabled; users only see light mode

Use cases:

• Your branding requires light mode only

• Dark mode conflicts with custom styling

• Simplify user interface options

Setting: Default theme mode

Description: Set the default color scheme for users who haven't chosen a preference.

Available for: Themes with dark mode support and dark mode not disabled

Options:

• Light: Always use light mode by default

• Dark: Always use dark mode by default

• Auto: Follow user's system preference (operating system dark mode setting)

Note: Users can still override this preference in their account settings unless dark mode is completely disabled.

Configuration Best Practices

Choose colors carefully:

• Test colors in both light and dark modes

• Ensure sufficient contrast for readability

• Consider color blindness accessibility

• Preview on different devices and screen sizes

Dark mode considerations:

• If your brand has strict color requirements, consider disabling dark mode

• Auto mode provides the best user experience for most users

• Test custom colors in both modes before finalizing

---

Theme Features and Capabilities

Themes can declare which features they support in their template.json file.

Feature Flags

Themes use feature flags to indicate capabilities:

Feature	Description	Impact on Admin Settings
supportDarkMode	Theme supports light and dark color schemes	Shows dark mode configuration options
supportCustomColors	Allows admin to configure custom colors	Shows color picker fields in settings

How to Check Theme Features

Method 1: Admin Panel

1. Go to Settings → Theme

2. Click the ℹ️ icon next to a theme name

3. View "Options" section showing supported features

Method 2: API

curl -X GET https://your-panel.com/panel/api/template/theme-name \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Response:

{
  "Template name": "my-theme",
  "Version": "1.0.0",
  "Options": {
    "Support dark mode": true,
    "Allow configuring custom colors": true
  }
}

What Happens When Features Are Disabled

If supportDarkMode: false:

• Dark mode settings hidden in Admin Panel

• Users cannot toggle dark mode

• Theme always displays in light mode

If supportCustomColors: false:

• Color picker fields hidden in Admin Panel

• Theme uses its built-in color scheme

• Custom colors cannot be applied

---

Theme Assets and Resources

Themes use assets like CSS, JavaScript, images, and fonts to create their visual appearance.

Asset Structure

Theme source files: /themes/{theme-name}/assets/

• May contain source files (SCSS, uncompiled JS)

• Not directly served to browsers

Public compiled assets: /public/assets/theme/{theme-name}/

• Compiled and optimized files

• Served directly to users' browsers

• Accessible via web URLs

Asset Types

CSS Stylesheets:

• Main styles: app.css

• Page-specific: panel.css, errors.css

• Loaded automatically by theme

JavaScript:

• Custom interactive features

• Libraries (Chart.js, etc.)

• Loaded in theme templates

Images:

• Logos, icons, backgrounds

• Referenced in templates or CSS

Fonts:

• Custom typography

• Web fonts (WOFF2, TTF)

How Assets Are Loaded

Themes reference assets using the template_asset() Twig function:

<link rel="stylesheet" href="{{ template_asset('css/app.css') }}">
<script src="{{ template_asset('js/custom.js') }}"></script>

Generated URL:

https://your-panel.com/assets/theme/my-theme/css/app.css
https://your-panel.com/assets/theme/my-theme/js/custom.js

Asset Best Practices

For theme installation:

• Always place assets in /public/assets/theme/{theme-name}/

• Match folder name exactly to theme name

• Ensure proper file permissions (readable by web server)

For troubleshooting:

• Check browser console for 404 errors on assets

• Verify asset files exist in public directory

• Check web server has read access to asset files

---

Permissions

To manage themes, users need specific permissions:

Permission	Action	Description
access_themes	View theme list	Access the theme management interface
view_theme	View theme details	See detailed theme information
set_default_theme	Set default theme	Activate themes for different contexts
configure_theme	Configure theme settings	Adjust theme colors and options
upload_theme	Upload themes	Install new theme packages
copy_theme	Copy themes	Duplicate existing themes
export_theme	Export themes	Download themes as ZIP packages
delete_theme	Delete themes	Remove themes from system

Default Permissions

• Admin role: Has all theme permissions by default

• User role: No theme permissions by default

For detailed information about the permission system, see Access Control.

---

Troubleshooting

Common issues and solutions when working with themes.

Theme Not Appearing in Selection

Symptoms: Installed theme doesn't show up in the theme dropdown.

Possible causes:

• Missing template.json file

• Invalid JSON syntax in template.json

• Incorrect folder structure

• Missing required fields in template.json

Solutions:

1. Verify template.json exists:

ls /var/www/pteroca/themes/my-theme/template.json

1. Validate JSON syntax:

cat /var/www/pteroca/themes/my-theme/template.json | jq .

If jq reports an error, fix the JSON syntax.

1. Check required fields:

{
  "template": {
    "name": "my-theme",
    "version": "1.0.0",
    "pterocaVersion": "0.6",
    "phpVersion": ">=8.2"
  }
}

1. Verify folder name matches template name: Folder: /themes/my-theme/ JSON: "name": "my-theme" (must be identical)

Custom Colors Not Applying

Symptoms: Color picker settings don't change the panel appearance.

Cause: Theme doesn't support custom colors.

Solutions:

1. Check theme capabilities:

   • Go to Settings → Theme

   • Click info icon next to theme name

   • Check "Allow configuring custom colors" option

2. If feature is missing:

   • Switch to a theme with custom color support

   • Contact theme developer to request feature

   • Use the default theme (supports custom colors)

3. Clear browser cache:

   • Press Ctrl+Shift+Delete (Cmd+Shift+Delete on Mac)

   • Clear cached images and files

   • Refresh page

Dark Mode Settings Not Visible

Symptoms: Can't find dark mode configuration options.

Cause: Theme doesn't support dark mode.

Solutions:

1. Check theme capabilities:

   • Verify theme has "supportDarkMode": true in template.json

2. Switch themes:

   • Choose a theme with dark mode support

   • Default theme supports dark mode

Theme Assets Not Loading (404 Errors)

Symptoms: Broken styling, missing images, browser console shows 404 errors.

Causes:

• Assets not uploaded to /public/assets/theme/{theme-name}/

• Incorrect folder name (doesn't match theme name)

• File permissions issue

Solutions:

1. Verify assets directory exists:

ls /var/www/pteroca/public/assets/theme/my-theme/

1. Check folder name matches:

   • Theme folder: /themes/my-theme/

   • Asset folder: /public/assets/theme/my-theme/

   • Names must match exactly

2. Set correct permissions:

chown -R www-data:www-data /var/www/pteroca/public/assets/theme/my-theme
chmod -R 755 /var/www/pteroca/public/assets/theme/my-theme

1. Check asset paths in templates:

   • Ensure theme uses template_asset() function

   • Verify file paths are correct

Theme Causes Errors or Blank Pages

Symptoms: Panel shows errors or blank pages after activating theme.

Immediate fix:

1. Switch back to default theme via database:

# Connect to database
mysql -u pteroca_user -p pteroca_db

# Update theme setting
UPDATE setting SET value = 'default' WHERE name = 'current_theme';
exit;

1. Clear cache:

cd /var/www/pteroca
php bin/console cache:clear

1. Check logs:

tail -f var/log/prod.log

Root cause solutions:

• Contact theme developer with error logs

• Ensure theme is compatible with your PteroCA version

• Verify all theme files are uploaded correctly

• Check PHP error logs for template syntax errors

Theme Appears Outdated or Incompatible

Symptoms: Warning message about theme compatibility.

Cause: Theme's pterocaVersion requirement is older than your PteroCA installation.

Solutions:

1. Check theme version:

   • Look for theme updates from developer

   • Verify theme supports your PteroCA version

2. Update theme:

   • Download latest version

   • Replace theme files (backup old version first)

   • Test in a staging environment if possible

3. Use default theme:

   • Always up-to-date with PteroCA releases

   • Switch back until theme is updated

Need More Help?

If you're still experiencing issues:

• Check the FAQ

• Review Troubleshooting Guide

• Ask in the Discord community

• Contact your theme developer for support

---

Creating Your Own Themes

If you're a developer interested in creating custom themes for PteroCA, see the complete Theme Development Guide in the "For Developers" section.

The developer guide includes:

• Theme structure and file organization

• Template.json schema and validation

• Twig templating and template hierarchy

• CSS styling and color customization

• JavaScript integration

• Asset management and compilation

• Testing and debugging themes

• Best practices for theme development

---

Related Documentation

Configuration Guides

• Theme Settings - Detailed theme settings reference

• General Settings - Site logo and branding

• Access Control - Theme management permissions

Customization

• Overview - General customization options

• Plugins - Extend functionality with plugins

Developer Resources

• Theme Development - Complete developer guide

• Twig Documentation - Template engine reference

Need Help?

If you have questions about themes or need assistance:

• Check the FAQ

• Review the Theme Development Guide

• Join our Discord community

• Report issues on GitHub