Template Customization

This guide covers how to customize the appearance of Itinerator blocks to match your theme and brand.

Overview

The Itinerator plugin uses a flexible styling system that allows you to:

Override default Bootstrap styles
Add custom CSS classes
Target specific blocks using body classes

Body Classes for Targeting

The plugin automatically adds CSS classes to the <body> tag to help you target specific blocks:

.has-itinerator-blocks - Added when any Itinerator block is present on the page
.has-itinerator-block-{name} - Added for specific block types (e.g., .has-itinerator-block-itineraries)

Example targeting:

/* Target all Itinerator blocks */
.has-itinerator-blocks .itin .card {
    border-radius: 12px;
}

/* Target only itinerary blocks */
.has-itinerator-block-itineraries .itin.itinerator-itineraries {
    background-color: #f8f9fa;
}

/* Target only event blocks */
.has-itinerator-block-events .itin.itinerator-events {
    padding: 2rem;
}

CSS Class Override System

The plugin includes a CSS class override system that allows you to customize Bootstrap classes to match your theme or page builder.

How It Works

Class overrides - Replace Bootstrap classes with custom ones
Settings-based - Configure overrides in the plugin settings area
Template integration - Use helper functions in templates
Fallback support - Falls back to Bootstrap defaults if no override set

Available Helper Functions

The plugin provides helper functions for consistent styling:

// Button classes
btn_primary($additional_classes)
btn_secondary($additional_classes)
btn_outline($additional_classes)
btn_success($additional_classes)
btn_danger($additional_classes)

// Component classes
card_class($additional_classes)
card_body_class($additional_classes)
btn_wrapper_class($additional_classes)
form_control_class($additional_classes)
badge_class($additional_classes)

How to Use Helper Functions

In your templates, you can use these functions to get the appropriate CSS classes:

<?php
use function Itinerator\Config\{
  btn_primary,
  btn_secondary,
  card_class,
  form_control_class
};
?>

<button class="<?php echo btn_primary(); ?>">Submit</button>
<button class="<?php echo btn_secondary('btn-sm'); ?>">Cancel</button>
<div class="<?php echo card_class('mb-4'); ?>">
  <input type="email" class="<?php echo form_control_class(); ?>" name="email">
</div>

Customization Methods

Method 1: CSS Class Overrides

Configure custom CSS classes in the WordPress admin:

Go to Itinerator → Settings
Scroll to the Theme Settings section
Configure class overrides for buttons, cards, forms, etc.
Save settings to apply changes

Available Overrides:

Button Classes - Primary, secondary, outline, success, danger buttons
Card Classes - Card containers and card body elements
Form Classes - Form controls and input elements
Badge Classes - Badge and tag elements
Wrapper Classes - Button wrapper elements

Example Override Settings:

Primary Button: elementor-button elementor-button-primary
Card Container: custom-card theme-card
Form Control: wpforms-field-input

Method 2: Custom CSS Classes

Add custom CSS classes to blocks in the editor:

Select a block in the editor
Open block settings in the sidebar
Add custom CSS class in the Advanced section
Write CSS targeting your custom class

Example:

.has-itinerator-blocks .itin .card {
    border: none;
    box-shadow: 0 4px 6px rgba(0, 0, 0, 0.1);
}

.has-itinerator-block-itineraries .itin .itinerator-itineraries {
    background-color: #f8f9fa;
    border-radius: 12px;
    padding: 2rem;
}

Method 3: Theme Customizer

Use WordPress Customizer for global changes:

Go to Appearance → Customize
Add Custom CSS section
Target Itinerator classes
Preview changes in real-time

Example:

/* Global Itinerator styling */
.has-itinerator-blocks .itin {
    font-family: 'Your Custom Font', sans-serif;
}

.has-itinerator-blocks .itin .btn-primary {
    background-color: #your-brand-color;
    border-color: #your-brand-color;
}

Method 4: Template Override Helper Plugin

For advanced customization, use the Itinerator Template Override Helper plugin to store templates, CSS, and JavaScript outside of your theme. See the Template Override Helper Plugin section below for detailed information.

Common Customizations

Basic Styling Examples

Colors and Typography:

.has-itinerator-blocks .itin {
    font-family: 'Your Custom Font', sans-serif;
}

.has-itinerator-blocks .itin .btn-primary {
    background-color: #your-primary-color;
    border-color: #your-primary-color;
}

Layout and Spacing:

.has-itinerator-blocks .itin .card {
    border-radius: 12px;
    box-shadow: 0 4px 6px rgba(0, 0, 0, 0.1);
    margin-bottom: 2rem;
}

Targeting Specific Blocks:

.has-itinerator-block-itineraries .itin.itinerator-itineraries {
    background-color: #f8f9fa;
    padding: 2rem;
}

Responsive Design

Mobile Optimizations

Mobile-First Approach:

/* Base styles (mobile) */
.has-itinerator-blocks .itin .card {
    margin-bottom: 1rem;
}

/* Tablet and up */
@media (min-width: 768px) {
    .has-itinerator-blocks .itin .card {
        margin-bottom: 2rem;
    }
}

/* Desktop and up */
@media (min-width: 1024px) {
    .has-itinerator-blocks .itin .card {
        margin-bottom: 3rem;
    }
}

Touch-Friendly Elements:

.has-itinerator-blocks .itin .btn {
    min-height: 44px; /* Touch-friendly minimum */
    padding: 0.75rem 1.5rem;
}

.has-itinerator-blocks .itin .card {
    cursor: pointer;
}

Advanced Customizations

Template Override Helper Plugin

For easier template management, you can use the Itinerator Template Override Helper plugin. This plugin allows you to store template overrides outside of your theme directory and add custom CSS and JS that will be theme independent.

How It Works

The helper plugin:

Stores template overrides in the plugin folder
Creates symlinks to your active theme directory
Enqueues app.js and app.css for custom styling and JavaScript
Keeps templates organized outside of theme files
Simplifies updates and maintenance

Benefits

Theme independence - Templates survive theme updates
Better organization - All overrides in one location
Easier backups - Template overrides backed up with plugin
Cleaner themes - No template files cluttering theme directory

Installation

Download the helper plugin from https://tourismo.co/wordpress-plugin
Install and activate like any WordPress plugin
Configure template overrides through the plugin interface
Templates are automatically linked to your active theme

Usage

Once activated, the helper plugin will:

Create a dedicated directory for template overrides
Automatically symlink templates to your active theme
Provide an interface for managing template files
Handle template updates and maintenance

Note: This is a basic overview. More detailed documentation for the helper plugin will be available in future updates.

JavaScript Customizations

Add custom JavaScript for interactive features:

// Custom hover effects
jQuery(document).ready(function($) {
    $('.has-itinerator-blocks .itin .card').hover(
        function() {
            $(this).addClass('hover-effect');
        },
        function() {
            $(this).removeClass('hover-effect');
        }
    );
});

Performance Optimizations

CSS Optimization:

/* Use specific selectors for better performance */
.has-itinerator-blocks .itin .card .card-title {
    /* More specific than just .card-title */
}

/* Avoid expensive properties */
.has-itinerator-blocks .itin .card {
    /* Use transform instead of margin/padding for animations */
    transform: translateY(0);
    transition: transform 0.2s ease;
}

Troubleshooting Customizations

Common Issues

Styles not applying:

Check CSS specificity
Clear browser cache
Verify CSS syntax
Check for conflicting styles

Responsive issues:

Test on actual devices
Check media query syntax
Verify viewport meta tag
Test different screen sizes

Performance problems:

Minimize CSS file size
Use efficient selectors
Avoid expensive properties
Optimize images

Debugging Tools

Browser Developer Tools:

Inspect elements to see applied styles
Check CSS specificity with computed styles
Test responsive design with device simulation
Profile performance with performance tools

CSS Validation:

Use CSS validators to check syntax
Test with different browsers
Verify vendor prefixes

Best Practices

Maintainability

Use consistent naming conventions
Document customizations thoroughly
Test across browsers and devices
Keep backups of custom code

Performance

Minimize CSS file size
Use efficient selectors
Optimize images and assets
Enable caching for CSS files

Accessibility

Maintain color contrast ratios
Use semantic HTML structure
Test with screen readers
Ensure keyboard navigation

Resources

CSS References

Tools

Need help with customization? Contact Itinerator support or check the Troubleshooting guide.