If you’ve found an error, spotted something missing, or feel a section could be clearer or better explained, we’d love to hear from you. Your feedback helps keep the documentation accurate and useful for everyone.
Please report issues or suggest improvements on GitHub. Community input is invaluable in making the docs stronger.
Not comfortable with GitHub? No problem — you can also get in touch with us directly via our contact form. We welcome all feedback.
Theme Implementation
This section covers the practical aspects of working with themes in Trongate, including theme structure, asset management, and theme creation.
Theme Location and Structure
Themes in Trongate are stored in the public/themes/ directory. Within this directory, you have complete flexibility to structure your themes as needed for your application.
Example: Admin Theme Structure
The default admin theme demonstrates one possible way to organize theme variations:
Alternative structures are possible. For example, a theme with shared assets might use:
Managing Theme Assets
Trongate provides the THEME_DIR constant for referencing theme-specific assets. This constant becomes available when a theme is loaded.
Example: Loading Theme-Specific and Shared Assets
This approach allows you to:
- Share common assets across theme variations
- Override specific styles for each variation
- Maintain a clean separation between shared and variation-specific assets
Registering Themes
Themes are registered in the config/themes.php file. Each theme requires two key properties:
dir: The theme's directory path relative topublic/themes/template: The primary template file for the theme
Example: Theme Registration
Theme keys (e.g., 'admin', 'desktop_app_mx') should be unique and descriptive, as they'll be used to reference the theme in your application code.
Theme Loading Process
When a theme is loaded via the template() method, Trongate:
- Checks if the requested template exists in
THEMES - If found, constructs the theme path using the theme's directory and template file
- Defines
THEME_DIRfor asset referencing - Loads the template file with any provided data
- Asset Organization: Consider separating shared and variation-specific assets
- Theme Variations: Use consistent directory structures across variations
- Asset References: Always use
THEME_DIRfor theme-specific assets - Theme Registration: Use clear, descriptive keys in
themes.php - Directory Structure: Choose a structure that makes sense for your specific needs - there's no mandatory layout
The Benefits of Using Themes
While templates serve their purpose for basic page layouts, themes offer several significant advantages that make them invaluable for modern web applications:
- Portability: Entire design packages can be contained within a single folder, making them easy to transfer between projects or share with the community
- Complete Design Systems: Themes can include everything needed for a consistent look and feel:
- Templates
- Stylesheets
- JavaScript files
- Images and icons
- Fonts
- Color schemes
- Easy Switching: Change the entire appearance of your application by modifying a single line in your theme configuration
- Version Control: Keep entire design packages under version control as a single unit, making it easier to track design changes
- Resource Management: The
THEME_DIRconstant provides a reliable way to reference theme-specific assets, eliminating path management headaches - Multiple Variations: Support different color schemes or design variations without duplicating your entire codebase
- Clean Separation: Keep design assets separate from your application logic, improving maintainability
- Rapid Deployment: Quick implementation of new designs by switching themes, perfect for A/B testing or seasonal changes
These benefits make themes particularly valuable for applications that require flexible styling, multiple design variations, or the ability to quickly change their appearance.