# 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 >

``` 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 get_the_ID() ] ); ?> ``` Inside the located template, read injected values with `get_query_var()` when needed: ```php ``` ## 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.