Creating Themes

Learn how to create a new theme for PteroCA using the CLI command.

Create Theme via CLI

The fastest way to create a new theme is using the CLI command.

Create Theme Command

docker exec pteroca_web_dev php bin/console pteroca:dev:make-theme

This command is interactive and will prompt you for:

1. Theme name (kebab-case identifier)

2. Display name (human-readable)

3. Author name

4. Author email

5. Theme description

6. License (default: MIT)

What the Command Does

1. Copies default theme to themes/{your-theme-name}/

2. Creates template.json with your provided metadata

3. Copies assets to public/assets/theme/{your-theme-name}/

4. Sets up directory structure with all necessary folders

5. Makes theme ready for customization

Command Output Example

Theme Creator
=============

Creating a new theme based on the default PteroCA theme.

Theme name (kebab-case, e.g., my-awesome-theme):
> dark-professional

Display name:
> Dark Professional

Author name:
> John Doe

Author email:
> [email protected]

Description:
> A sleek dark theme for professional hosting panels

License [MIT]:
> MIT

Creating theme 'dark-professional'...
✓ Copied theme templates to themes/dark-professional/
✓ Copied theme assets to public/assets/theme/dark-professional/
✓ Created template.json with metadata
✓ Theme created successfully!

Next steps:
1. Go to Settings → Appearance → Current theme
2. Select 'Dark Professional'
3. Start customizing templates in themes/dark-professional/
4. Edit styles in public/assets/theme/dark-professional/css/

Activating Your Theme

After creation, activate your theme using one of these methods:

Method 1: Via Admin Panel

1. Navigate to Settings → Appearance

2. Find Current theme of the panel (current_theme)

3. Change to your theme name

4. Click Save

Method 2: Via Database

UPDATE setting
SET value = 'my-theme'
WHERE name = 'current_theme';

First Steps After Creation

1. Verify Theme Installation

Check that your theme directory exists:

# Verify theme folder structure
ls -la themes/my-theme/

# Check template.json is valid
cat themes/my-theme/template.json | python -m json.tool

2. Test Theme Activation

1. Activate your theme via Admin Panel

2. Clear browser cache (Ctrl+Shift+R)

3. Refresh the panel

4. Verify no errors appear

3. Make Your First Customization

Edit the main stylesheet:

# Edit CSS
nano public/assets/theme/my-theme/css/main.css

Add a simple customization:

/* public/assets/theme/my-theme/css/main.css */

/* Custom primary color */
:root {
    --bs-primary: #6366f1;  /* Indigo */
}

/* Custom navbar background */
.navbar {
    background: linear-gradient(135deg, #667eea 0%, #764ba2 100%);
}

Refresh the page to see changes.

No Visible Changes?

After switching from the default theme to your new one, you might not see any changes. This is normal!

Your theme is currently identical to the default theme. Start customizing to see the difference:

1. Modify CSS in public/assets/theme/my-theme/css/

2. Override templates in themes/my-theme/

3. Add custom JavaScript in public/assets/theme/my-theme/js/

Creating a Theme from Scratch

If you prefer not to use the default theme as a base:

1. Create Directory Structure

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

2. Create template.json

cat > themes/my-theme/template.json << 'EOF'
{
  "template": {
    "name": "my-theme",
    "description": "My custom theme",
    "author": "Your Name",
    "version": "1.0.0",
    "license": "MIT",
    "pterocaVersion": "0.6",
    "phpVersion": ">=8.2"
  }
}
EOF

3. Create Minimal Structure

You only need to override templates you want to customize. The rest will inherit from the default theme.

Theme Development Workflow

1. Development Environment

Work in development mode for better debugging:

# .env
APP_ENV=dev
APP_DEBUG=true

This enables:

• Symfony debug toolbar

• Detailed error messages

• Template paths in debug toolbar

• No caching (changes appear immediately)

2. Make Changes

Edit templates, CSS, or JavaScript files.

3. Clear Cache (if needed)

docker exec pteroca_web_dev php bin/console cache:clear

Note: In dev mode, Twig templates don't require cache clearing.

4. Test Changes

1. Refresh browser (Ctrl+Shift+R for hard refresh)

2. Check console for errors (F12)

3. Verify changes appear correctly

5. Iterate

Repeat the cycle: make changes, test, refine.

Troubleshooting

Theme Not Appearing in Settings

Check:

1. template.json exists and is valid JSON

2. Theme folder name matches name field in template.json

3. All required fields are present in template.json (name, description, author, version, license, pterocaVersion, phpVersion)

4. Restart the application or clear cache: php bin/console cache:clear

Changes Not Appearing

Solutions:

1. Clear browser cache (Ctrl+Shift+R)

2. Clear Symfony cache: php bin/console cache:clear

3. Verify correct theme is activated

4. Check file paths are correct

Template Errors

Debug:

1. Enable dev mode (APP_ENV=dev)

2. Check error messages

3. Verify template syntax

4. Use Symfony debug toolbar to see which templates are loaded

Related Guides

• Theme Structure - Understand file organization

• Template.json - Configure metadata

• Overriding Templates - Customize specific templates

• Styling - Add custom CSS

• Testing - Quality assurance