# 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 `` 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:**
```css
/* 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:
```php
// 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
```
## 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:**
```css
.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:**
```css
/* 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:**
```css
.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:**
```css
.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:**
```css
.has-itinerator-block-itineraries .itin.itinerator-itineraries {
background-color: #f8f9fa;
padding: 2rem;
}
```
## Responsive Design
### Mobile Optimizations
**Mobile-First Approach:**
```css
/* 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:**
```css
.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:
```javascript
// 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:**
```css
/* 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](https://getbootstrap.com/docs/4.6/)
- [CSS Grid Layout](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_Grid_Layout)
- [Flexbox Layout](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_Flexible_Box_Layout)
### Tools
- [CSS Validator](https://jigsaw.w3.org/css-validator/)
- [Color Contrast Checker](https://webaim.org/resources/contrastchecker/)
- [CSS Specificity Calculator](https://specificity.keegan.st/)
---
**Need help with customization?** Contact Itinerator support or check the [Troubleshooting](../troubleshooting.md) guide.