Appearance
Themes
Introduction
A theme draws the public site. kitloom/site handles a request the way WordPress does — the main query finds what the address asks for, the template hierarchy lists template names from the most specific to index — and the active theme shows the page with the first template it has. A site can have many themes installed; only one is active at a time.
Themes are part of kitloom/site: there is no separate themes package. A theme is a Composer package (or a folder of your application) whose service provider extends Kitloom\Site\Themes\ThemeServiceProvider. See Writing a Theme.
Engines
The theme names the engine that shows its templates:
| Engine | Package | Templates |
|---|---|---|
blade | kitloom/site | resources/views/templates/{name}.blade.php — rendered on the server, nothing to build |
inertia | kitloom/site-inertia | resources/js/Templates/{name}.vue — Vue 3 pages, or {name}.tsx — React components; through Inertia 3, built with Vite |
The Blade engine comes with kitloom/site. The Inertia engine is registered by kitloom/site-inertia, which a Vue or React theme requires, so it is installed together with the theme.
The engine follows the active theme, not the installed packages: one application can have Vue, React and Blade themes side by side, and whichever is active decides.
Bundled themes
Each one with screenshots and links to it on the demo stand: Theme Catalog.
| Theme | Package | Engine | What it is |
|---|---|---|---|
BladeTheme (Blade) | kitloom/blade-theme | Blade | A plain site drawn on the server: a menu, a sidebar and footer widgets, comments. Nothing to build. |
Journal | kitloom/journal-theme | Vue | A personal blog. |
Bureau | kitloom/bureau-theme | Vue | A one-page agency site. |
Portfolio | kitloom/portfolio-theme | Vue | A design studio's portfolio. |
GameReviews (Game Reviews) | kitloom/game-reviews-theme | Vue | A review site; the reference for everything a theme can bring. |
Parsec | kitloom/parsec-theme | Vue | A dark news magazine. |
Saffron | kitloom/saffron-theme | Vue | A food blog with recipe cards. |
Pantry | kitloom/pantry-theme | Vue | A food store on kitloom/shop. |
Quire | kitloom/quire-theme | React | A stationery shop on kitloom/shop. |
Marketplace | kitloom/marketplace-theme | Blade | A storefront on kitloom/shop; its CSS is prebuilt, so the site builds nothing. |
Atelier | kitloom/atelier-theme | Vue | A salon with online booking on kitloom/bookings. |
Keystone | kitloom/keystone-theme | Vue | A real estate agency on kitloom/listings. |
Waypoint | kitloom/waypoint-theme | Vue | A city guide on kitloom/listings. |
Lyceum | kitloom/lyceum-theme | Vue | An online school on kitloom/courses. |
Every theme is proprietary, as every kitloom package is. Each has a demo command that fills an empty site — php artisan journal:demo, blade:demo, marketplace:demo — named in its composer.json (extra.kitloom.theme.demo).
Which theme is active
The active theme is named by an option of kitloom's own, kitloom_theme (kitloom-site.theme.option) — not WordPress's current_theme, which WordPress overwrites whenever its own theme is switched on a database the two share:
- The theme the
kitloom_themeoption names, when it is installed. - Otherwise — the option is not set yet, or names a theme that is not installed — the default theme,
APP_THEMEin.env(kitloom-site.theme.default). - When neither names an installed theme, the site has no theme.
The option set to an empty string means no theme, whatever APP_THEME says. This is what Deactivate on the Themes screen writes, and php artisan site:theme --none.
ini
APP_THEME=PortfolioThe option name is kitloom-site.theme.option in config/kitloom-site.php.
Without a theme
Without an active theme every page answers with its data as JSON — the same document a client gets from any page with Accept: application/json: kind, template, url and the page parts. That is a headless site; see Headless & APIs.
The Themes screen
Appearance → Themes lists the installed themes and switches them, as WordPress does. Install the package for your admin panel:
| Panel | Package | Turned off by |
|---|---|---|
| Filament | kitloom/site-filament | kitloom-site.filament.register |
| Nova | kitloom/site-nova | kitloom-site.nova.register |
Each theme is a card: its screenshot, name, description, version, authors and engine (Blade or Vue). The active theme comes first. The screen is open to roles with the switch_themes permission.
Activate on a card:
- is disabled for a Vue theme that is not built yet — the card says Not built yet: run npm run build:themes;
- is disabled while a module the theme's package requires is switched off on the Modules screen — the card lists the modules it needs and the disabled ones;
- runs the theme's pending migrations first — the card says how many will run; if they fail, the theme is not switched and the error is shown;
- then writes the theme's name into
kitloom_theme.
The active theme's card has Deactivate instead, and counts the theme's migrations a deploy brought that have not run yet: php artisan migrate runs them. After a confirmation the site has no theme and serves JSON; a notice above the cards says so until a theme is activated again.
Nova The general settings page of kitloom/wp-schema-nova also gets a Current Theme select. It refuses a Vue theme that is not built, but only writes the option — the theme's migrations run from the Themes screen.
The screen only switches themes. Themes are installed and removed with Composer, through your deployment.
Themes and modules
A theme that is not active does not keep a module switched on: on the Modules screen you can switch off a module that only an inactive theme needs. That theme then cannot be activated until the module is back.
Child themes
To change a bundled theme without copying it, make a child theme: it holds only the templates, views, components and styles it changes, and takes everything else from its parent — including the parent's updates.
bash
php artisan kitloom:make-theme Inkwell --parent=JournalColours, the logo and similar settings need no child at all: the owner changes them on Appearance → Customize. To start from scratch, generate a theme.