250 lines
7.7 KiB
Markdown
250 lines
7.7 KiB
Markdown
# WP Kaliroots
|
|
|
|
Use this skill when a Websimple WordPress site uses the `kaliroots` parent theme or when behavior may come from Kaliroots parent-theme code.
|
|
|
|
Kaliroots source of truth: `https://gitea.websimple.com/wp-themes/kaliroots`.
|
|
|
|
Use `references/wp-theme-dev.md` for general theme PHP conventions that do not conflict with Kaliroots. Use `references/wp-browser.md` for frontend checks and `references/wp-xdebug.md` when parent/child template resolution or hooks are unclear.
|
|
|
|
## Core rule
|
|
|
|
For Kaliroots child themes, do not apply generic WordPress template organization blindly. Kaliroots has its own wrapper and template lookup system.
|
|
|
|
Prefer child-theme overrides and additions. Treat parent theme changes as higher-risk because they can affect many sites.
|
|
|
|
## Confirm Kaliroots usage
|
|
|
|
Before applying Kaliroots conventions, confirm the active theme relationship:
|
|
|
|
```bash
|
|
wp theme list --status=active
|
|
wp theme get $(wp option get stylesheet) --field=template
|
|
```
|
|
|
|
Or inspect the child theme `style.css` for a parent declaration like:
|
|
|
|
```css
|
|
Template: kaliroots
|
|
```
|
|
|
|
Inspect the child theme first, then inspect the parent theme only when inherited behavior or helper functions matter.
|
|
|
|
## Parent theme structure
|
|
|
|
Kaliroots parent uses a compact structure:
|
|
|
|
```text
|
|
functions.php
|
|
includes/
|
|
core/
|
|
purgecss.php
|
|
theme-setup.php
|
|
theme-wrapper.php
|
|
helpers/
|
|
assets.php
|
|
attachment.php
|
|
datetime.php
|
|
html.php
|
|
input.php
|
|
mail.php
|
|
media.php
|
|
menu.php
|
|
meta.php
|
|
mutex.php
|
|
query.php
|
|
shortcodes.php
|
|
social.php
|
|
taxonomy.php
|
|
template.php
|
|
user.php
|
|
utilities.php
|
|
wpfs.php
|
|
vendors/
|
|
acf.php
|
|
gutenberg.php
|
|
wpbakery.php
|
|
templates/
|
|
html/
|
|
head.php
|
|
mail.php
|
|
wrap.php
|
|
content/
|
|
main.php
|
|
```
|
|
|
|
The parent `functions.php` is a loader for `includes/core`, `includes/helpers`, and `includes/vendors`.
|
|
|
|
Child themes may add their own `includes/`, `templates/`, and asset sources. Preserve existing child-theme conventions unless the user asks for cleanup.
|
|
|
|
## Template wrapper model
|
|
|
|
Kaliroots wraps base WordPress templates through the `template_include` filter.
|
|
|
|
The parent wrapper flow is:
|
|
|
|
1. `template_include` calls `kaliroots_wrap_base_template()`.
|
|
2. The wrapper locates `templates/html/wrap-{base}.php` through `kaliroots_locate_template()`.
|
|
3. `{base}` is expanded by `kaliroots_base_placeholders()` using WordPress conditional context.
|
|
4. `locate_template()` gives child themes priority over parent templates.
|
|
|
|
Parent default wrapper:
|
|
|
|
```php
|
|
<!DOCTYPE html>
|
|
<html <?php language_attributes(); ?>>
|
|
<?= kaliroots_html_template( 'head' ); ?>
|
|
<body class="<?= join( ' ', get_body_class() ) ?>">
|
|
<div id="app">
|
|
<main>
|
|
<?= kaliroots_generic_template( '{base}' ) ?>
|
|
</main>
|
|
</div>
|
|
<?php wp_footer(); ?>
|
|
</body>
|
|
</html>
|
|
```
|
|
|
|
When changing page layout in a Kaliroots child theme, prefer overriding or adding wrapper/content templates in the child theme instead of replacing standard WordPress top-level templates without checking how Kaliroots resolves them.
|
|
|
|
## Template helper functions
|
|
|
|
Kaliroots provides template helper functions in `includes/helpers/template.php`.
|
|
|
|
Common helpers:
|
|
|
|
```php
|
|
kaliroots_generic_template( $template_path, $vars = [], $args = [] );
|
|
kaliroots_html_template( $template_name, $vars = [], $args = [] );
|
|
kaliroots_site_template( $template_name, $vars = [], $args = [] );
|
|
kaliroots_content_template( $template_name, $vars = [], $args = [] );
|
|
kaliroots_loop_template( $template_name, $vars = [], $args = [] );
|
|
kaliroots_section_template( $template_name, $vars = [], $args = [] );
|
|
kaliroots_shortcode_template( $template_name, $vars = [], $args = [] );
|
|
kaliroots_widget_template( $template_name, $vars = [], $args = [] );
|
|
```
|
|
|
|
These helpers locate templates through the Kaliroots lookup pipeline, inject `$vars` using `set_query_var()`, buffer template output, and can optionally cache rendered output.
|
|
|
|
Example:
|
|
|
|
```php
|
|
<?= kaliroots_content_template( 'hero', [ 'post_id' => get_the_ID() ] ); ?>
|
|
```
|
|
|
|
Inside the located template, read injected values with `get_query_var()` when needed:
|
|
|
|
```php
|
|
<?php $post_id = get_query_var( 'post_id' ); ?>
|
|
```
|
|
|
|
## Template naming and lookup
|
|
|
|
Kaliroots lookup supports placeholders:
|
|
|
|
- `{base}`: expanded using the current WordPress conditional/template context.
|
|
- `{post_type}`: expanded using `get_post_type()` when available.
|
|
|
|
Examples:
|
|
|
|
```php
|
|
kaliroots_html_template( 'head' );
|
|
// looks for templates/html/head-{base}.php, then falls back through base placeholder variants.
|
|
|
|
kaliroots_content_template( 'main' );
|
|
// looks for templates/content/main-{base}.php variants.
|
|
|
|
kaliroots_loop_template( 'default' );
|
|
// looks for templates/content/loops/default-{post_type}.php, then fallback variants.
|
|
```
|
|
|
|
When adding child-theme templates, prefer Kaliroots-compatible paths and names:
|
|
|
|
```text
|
|
templates/html/wrap-front-page.php
|
|
templates/html/wrap.php
|
|
templates/content/main-front-page.php
|
|
templates/content/main-single-project.php
|
|
templates/content/loops/default-project.php
|
|
```
|
|
|
|
Inspect the actual child theme before adding a new path; some projects may already have established naming.
|
|
|
|
## Extending template resolution
|
|
|
|
Kaliroots exposes filters for template lookup.
|
|
|
|
Use these only when adding a reusable lookup convention is clearer than adding explicit templates:
|
|
|
|
```php
|
|
add_filter( 'kaliroots_locate_templates', 'example_kaliroots_locate_templates' );
|
|
function example_kaliroots_locate_templates( array $templates ): array {
|
|
$templates[] = 'templates/content/custom-fallback';
|
|
|
|
return $templates;
|
|
}
|
|
```
|
|
|
|
```php
|
|
add_filter( 'kaliroots_base_placeholders', 'example_kaliroots_base_placeholders' );
|
|
function example_kaliroots_base_placeholders( array $templates ): array {
|
|
if ( is_post_type_archive( 'project' ) ) {
|
|
array_unshift( $templates, 'archive-project-featured' );
|
|
}
|
|
|
|
return $templates;
|
|
}
|
|
```
|
|
|
|
Keep these filters rare and well-named; they affect template resolution globally.
|
|
|
|
## Helpers and inherited behavior
|
|
|
|
Before reimplementing helper logic in a child theme, inspect Kaliroots helpers under `includes/helpers/`.
|
|
|
|
Useful parent helpers include:
|
|
|
|
- asset registration with filemtime cache busting;
|
|
- template loading and pagination;
|
|
- menu/media/meta/query helpers;
|
|
- HTML cleaning helpers;
|
|
- shortcode and utility helpers.
|
|
|
|
Do not assume helper behavior from memory. Inspect the parent helper before using or overriding it.
|
|
|
|
## Parent vs child changes
|
|
|
|
Default to child-theme changes:
|
|
|
|
- child template override;
|
|
- child `includes/` function/hook;
|
|
- child asset/source change;
|
|
- child-specific filter/action.
|
|
|
|
Only edit Kaliroots parent when the user explicitly asks to change shared parent behavior or the bug truly belongs in the parent.
|
|
|
|
Before parent edits, report blast radius:
|
|
|
|
- which projects/sites may inherit the change;
|
|
- whether a child override is safer;
|
|
- how behavior will be verified.
|
|
|
|
## Refactoring workflow
|
|
|
|
1. Confirm active child theme and Kaliroots parent.
|
|
2. Inspect child theme overrides first.
|
|
3. Inspect relevant Kaliroots parent files: usually `includes/core/theme-wrapper.php` and `includes/helpers/template.php`.
|
|
4. Choose child override vs parent change deliberately.
|
|
5. Keep changes small and reversible.
|
|
6. Run PHP lint/style checks via `references/wp-code-style.md` when PHP files changed.
|
|
7. Use `references/wp-browser.md` for frontend smoke checks.
|
|
8. Use `references/wp-xdebug.md` if template resolution/hook flow is unclear.
|
|
9. Inspect the diff before claiming success.
|
|
|
|
## Safety
|
|
|
|
- Do not apply generic `references/wp-theme-dev.md` template structure when Kaliroots lookup rules apply.
|
|
- Do not edit parent Kaliroots casually; prefer child overrides.
|
|
- Do not mass-reorganize child templates without approval.
|
|
- Do not touch core, vendor, uploads, caches, or compiled assets.
|
|
- Preserve existing project conventions when they are coherent.
|