Template Override Developer Guide

This guide shows theme developers and site builders how to customize JakBot’s chat interface templates using the theme override system. You’ll learn to safely modify templates in your active theme without losing changes during plugin updates.

Understanding the Template Override System

The template override system allows you to copy any chat interface template into your active theme directory. Once a copy exists in your theme, JakBot loads your version instead of its own. This approach ensures plugin updates never overwrite your customizations and enables per-theme template customization with full WordPress child-theme hierarchy support.

Setting Up Template Overrides

Creating the Directory Structure

1. Navigate to your active theme directory at wp-content/themes/your-theme/
2. Create a new subdirectory named jays-chat-assistant
3. Inside this directory, create a folder named after your template (e.g., standard)
4. Place your template files in this structure: your-theme/jays-chat-assistant/{template-name}/

your-theme/
  jays-chat-assistant/
    standard/
      chat-interface.php   (required)
      style.css            (optional)
      script.js            (optional)
      template.json        (optional)

Copying Templates via Admin UI

1. Go to JakBot > Templates in your WordPress admin dashboard
2. Locate the template card you want to customize
3. Click the Copy to Theme button
4. Verify the plugin copies all template files to your theme directory
5. Begin editing the copied files directly in your theme

Copying Templates Manually

1. Locate the source template in wp-content/plugins/jays-chat-assistant/templates/{template-name}/
2. Copy the entire template directory to wp-content/themes/your-theme/jays-chat-assistant/{template-name}/
3. Clear the template cache or wait for automatic detection on the next page load

Understanding Template Files

Required and Optional Files

1. Create chat-interface.php as your main template file containing HTML output for the chatbot widget
2. Add style.css for template-specific stylesheets (automatically enqueued with cache-busting)
3. Include script.js for template-specific JavaScript (automatically enqueued with jQuery dependency)
4. Configure template.json for template metadata, version tracking, and feature support flags

Creating Template Metadata

1. Create a template.json file in your template directory
2. Define the template name, description, version, and author information
3. Specify supported features like minimize, transcript, avatar, and positioning options
4. Set default settings for the template

{
    "name":        "My Custom Template",
    "description": "A customized chat interface for the Acme theme.",
    "version":     "1.2.0",
    "author":      "Your Name",
    "min_plugin_version": "2.1.0",
    "supports": {
        "minimize":    true,
        "transcript":  true,
        "avatar":      true,
        "positioning": ["bottom-right", "bottom-left", "top-right", "top-left"]
    },
    "settings": {
        "default_position": "bottom-right"
    }
}

Working with Template Variables

1. Access extracted PHP variables in your chat-interface.php template file
2. Use $bot_id for the database ID of the active bot
3. Reference $bot_name and $bot_slug for display name and URL-safe slug
4. Access $welcome_message array for welcome message strings
5. Use $user for the currently logged-in user object
6. Reference $position, $minimize, and $style_string for widget settings

Customizing Template Behavior with Filters

Modifying Template Directory Location

1. Add the jca_theme_override_dir filter to your theme’s functions.php
2. Return your preferred directory name instead of the default jays-chat-assistant

add_filter( 'jca_theme_override_dir', function( $dir ) {
    return 'my-chatbot-templates';
} );

Adding Custom Template Search Locations

1. Use the jca_template_search_locations filter to add new directories to the search path
2. Add shared template directories for network/multisite installations
3. Specify the template name and file parameters for targeted customizations

add_filter( 'jca_template_search_locations', function( $locations, $template, $file ) {
    // Add a network-wide shared directory before the plugin default
    array_splice( $locations, -1, 0, array(
        '/var/www/shared-templates/' . $template . '/' . $file
    ) );
    return $locations;
}, 10, 3 );

Modifying Template Output

1. Apply the jca_template_render_output filter to modify final HTML output
2. Access the complete HTML string, template name, and data variables
3. Return modified HTML output for lightweight customizations

add_filter( 'jca_template_render_output', function( $output, $template, $data ) {
    return '
' . $output . '
';
}, 10, 3 );

Managing Template Versions and Updates

Handling Template Updates

1. Monitor the admin UI for templates flagged as Outdated when your theme version is older than the plugin version
2. Choose Update (Overwrite) to replace your theme files with current plugin versions (creates timestamped backup)
3. Select Safe Update (.new) to write new plugin files alongside yours with .new suffix
4. Review .new files and manually merge changes as needed

Version Control Best Practices

1. Increment the version field in template.json whenever you make significant changes
2. Use the min_plugin_version field to document minimum plugin requirements