Template Customization
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:
1. Go to Itinerator → Settings
2. Scroll to the Theme Settings section
3. Configure class overrides for buttons, cards, forms, etc.
4. 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:
1. Select a block in the editor
2. Open block settings in the sidebar
3. Add custom CSS class in the Advanced section
4. 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:
1. Go to Appearance → Customize
2. Add Custom CSS section
3. Target Itinerator classes
4. 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
1. Download the helper plugin from https://tourismo.co/wordpress-plugin
2. Install and activate like any WordPress plugin
3. Configure template overrides through the plugin interface
4. 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:
1. Inspect elements to see applied styles
2. Check CSS specificity with computed styles
3. Test responsive design with device simulation
4. 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
- Bootstrap 4.6.1 Documentation
- CSS Grid Layout
- Flexbox Layout
Tools
- CSS Validator
- Color Contrast Checker
- CSS Specificity Calculator
Need help with customization? Contact Itinerator support or check the Troubleshooting guide.