Template.json

Every theme must include a template.json file with metadata.

Complete Schema

{
  "template": {
    "name": "my-theme",
    "description": "A beautiful custom theme for PteroCA",
    "author": "Your Name",
    "version": "1.0.0",
    "license": "MIT",
    "pterocaVersion": "0.6.3",
    "phpVersion": ">=8.2",
    "contexts": ["panel", "landing", "email"],
    "options": {
      "supportDarkMode": true,
      "supportCustomColors": true
    }
  }
}

Field Descriptions

Required Fields

All fields must be nested inside the "template" object.

• name (required): Unique theme identifier in kebab-case

  • Must match theme folder name

  • Used internally by PteroCA

  • Example: "my-theme", "dark-mode"

• description (required): Brief theme description

  • Shown in admin panel theme settings

  • Keep concise (1-2 sentences)

  • Example: "A beautiful custom theme for PteroCA"

• author (required): Theme author name

  • Simple string with author name

  • Example: "Your Name", "PteroCA Team"

• version (required): Semantic version number

  • Format: MAJOR.MINOR.PATCH

  • Example: "1.0.0", "2.3.1"

• license (required): License identifier

  • SPDX license identifier recommended

  • Example: "MIT", "GPL-3.0", "Apache-2.0"

• pterocaVersion (required): Minimum PteroCA version

  • Theme won't work on older versions

  • Format: "MAJOR.MINOR" (no patch version)

  • Example: "0.6"

• phpVersion (required): Minimum PHP version

  • Constraint operator format

  • Example: ">=8.2", "^8.2"

• contexts (optional): Array of supported contexts

  • Determines where theme can be activated

  • Valid values: "panel", "landing", "email"

  • Default: ["panel"] if omitted

  • Example: ["panel", "email"] for panel and email support only

  • Example: ["panel", "landing", "email"] for all contexts

Optional Fields

• options (optional): Theme capability flags

  • supportDarkMode (boolean): Theme supports dark mode toggle

  • supportCustomColors (boolean): Theme supports custom color configuration

  • If not specified, both default to false

Example template.json

Minimal Example

{
  "template": {
    "name": "simple-theme",
    "description": "A simple, clean theme",
    "author": "Your Name",
    "version": "1.0.0",
    "license": "MIT",
    "pterocaVersion": "0.6",
    "phpVersion": ">=8.2"
  }
}

Complete Example with Options

{
  "template": {
    "name": "dark-professional",
    "description": "A sleek dark theme for professional hosting panels",
    "author": "PteroCA Team",
    "version": "1.2.0",
    "license": "MIT",
    "pterocaVersion": "0.6",
    "phpVersion": ">=8.2",
    "options": {
      "supportDarkMode": true,
      "supportCustomColors": true
    }
  }
}

Version Constraints

PHP Version

Use the phpVersion field with constraint operators:

{
  "template": {
    "phpVersion": ">=8.2"
  }
}

Common operators:

• >=8.2 - PHP 8.2 or higher

• ^8.2 - Compatible with 8.2.x

PteroCA Version

Use the pterocaVersion field with MAJOR.MINOR format (no patch version):

{
  "template": {
    "pterocaVersion": "0.6"
  }
}

Format: Always use "MAJOR.MINOR" format without patch version.

Theme Options

The options object enables theme capabilities that affect PteroCA's theme settings UI:

supportDarkMode

{
  "template": {
    "options": {
      "supportDarkMode": true
    }
  }
}

• Type: boolean

• Default: false

• Effect: When enabled, users can toggle between light and dark modes in theme settings

• Requirement: Your theme must provide CSS for both modes

supportCustomColors

{
  "template": {
    "options": {
      "supportCustomColors": true
    }
  }
}

• Type: boolean

• Default: false

• Effect: When enabled, users can customize primary colors in theme settings

• Requirement: Your theme must use CSS variables for color customization

Context Configuration

The contexts field controls where your theme can be activated.

Context Options

panel

• Admin panel interface

• Client dashboard

• Server management pages

• All authenticated user interfaces

landing

• Public landing pages

• Marketing content

• Unauthenticated public pages

email

• Transactional email templates

• Notification emails

• System emails

Context Best Practices

Single-context themes:

{
  "template": {
    "contexts": ["email"]
  }
}

Use when theme is highly specialized (e.g., email-only themes with table-based layouts)

Multi-context themes:

{
  "template": {
    "contexts": ["panel", "email"]
  }
}

Use when you want consistent branding across multiple areas

Universal themes:

{
  "template": {
    "contexts": ["panel", "landing", "email"]
  }
}

Use when theme supports all use cases (requires more templates)

Multi-Context Theme Example

{
  "template": {
    "name": "universal-theme",
    "description": "A versatile theme supporting all contexts",
    "author": "Theme Developer",
    "version": "2.0.0",
    "license": "MIT",
    "pterocaVersion": "0.6.3",
    "phpVersion": ">=8.2",
    "contexts": ["panel", "landing", "email"],
    "options": {
      "supportDarkMode": true,
      "supportCustomColors": true
    }
  }
}

Context-Specific Theme Example

{
  "template": {
    "name": "email-only-theme",
    "description": "Specialized theme for email templates",
    "author": "Email Designer",
    "version": "1.0.0",
    "license": "MIT",
    "pterocaVersion": "0.6.3",
    "phpVersion": ">=8.2",
    "contexts": ["email"]
  }
}

---

Validation

To validate your template.json:

# Check JSON syntax
cat themes/my-theme/template.json | python -m json.tool

# Or use jq for pretty-printed validation
cat themes/my-theme/template.json | jq .

After creating the theme, test by activating it in the admin panel (Settings → Appearance → Current theme).

Common Errors

Invalid JSON

Error: Syntax error in template.json

Solution: Validate JSON syntax

• Remove trailing commas

• Use double quotes, not single quotes

• Ensure proper bracket/brace matching

Name Mismatch

Error: Theme name doesn't match folder name

Solution: Ensure name field matches theme folder:

Folder: themes/my-theme/
JSON:   "name": "my-theme"  ✓
JSON:   "name": "MyTheme"   ✗

Version Format

Error: Invalid version format

Solution: Use semantic versioning:

"version": "1.0.0"     ✓
"version": "1.0"       ✗
"version": "v1.0.0"    ✗

Related Guides

• Theme Structure - File organization

• Creating Themes - Create a new theme

• Testing - Validate your theme