Parallax Sections Plugin

Overview

The Parallax Sections plugin creates engaging parallax scrolling effects for website sections using shortcodes. It applies background images to content blocks and moves them at different speeds than the foreground content, creating a 3D depth illusion.

Features

✅ Reliable Image Coverage - Background images maintain full coverage during all scroll positions
✅ Smooth Performance - Hardware-accelerated animations with optimized JavaScript
✅ Responsive Design - Works seamlessly across all device sizes
✅ Theme Integration - Automatically adapts to light/dark themes
✅ Content Separation - Content stays in markdown files, not hardcoded in templates

Usage

Basic Shortcode Structure

<div class="parallax-section parallax-effect-scroll" id="your-unique-id" data-parallax-speed="0.5" data-parallax-effect="scroll""><div class="parallax-background" style="background-image: url('/path/to/your/image.jpg');"></div><div class="parallax-overlay" style="background-color: rgba(0,0,0,0.4); opacity: 0.4;"></div><div class="parallax-content"><!-- Your content goes here -->
    <p>This is the content that will scroll over the parallax background.</p></div></div>

Required Attributes

id (Required): A unique identifier for the parallax section.
- Example: id="hero-section"
- Note: Must be unique across the entire page
background_image (Required): The URL to the background image.
- Example: background_image="/uploads/my-parallax-background.jpg"
- Supported formats: JPG, PNG, WebP, SVG
- Recommended: High-resolution images (1920x1080 or larger)

Optional Attributes

speed (Optional): Controls parallax scroll speed. Default: 0.5
- 0.0 = Background stays fixed (classic parallax)
- 0.3 = Subtle movement (recommended for hero sections)
- 0.5 = Moderate movement (default)
- 0.8 = More pronounced movement
- Example: speed="0.3"
effect (Optional): Animation effect type. Default: "scroll"
- "scroll": Standard parallax scrolling effect
- Example: effect="scroll"
overlay_color (Optional): Text overlay color for better readability.
- Color names: red, blue, green, black, white
- Hex codes: #0066cc, #ff0000
- RGBA: rgba(0,0,0,0.5)
- Example: overlay_color="rgba(0,0,0,0.6)"
overlay_opacity (Optional): Overlay transparency. Default: 0.4
- Range: 0.0 (transparent) to 1.0 (opaque)
- Example: overlay_opacity="0.7"

Examples

Hero Section with Dark Overlay

<div class="parallax-section parallax-effect-scroll" id="hero" data-parallax-speed="0.3" data-parallax-effect="scroll""><div class="parallax-background" style="background-image: url('/uploads/hero-bg.jpg');"></div><div class="parallax-overlay" style="background-color: rgba(0,0,0,0.5); opacity: 0.5;"></div><div class="parallax-content"># Welcome to Our Site
<span style="color:white;">Experience stunning parallax effects that bring your content to life</span>
[Get Started](/about)</div></div>

About Section with Blue Overlay

<div class="parallax-section parallax-effect-scroll" id="about" data-parallax-speed="0.4" data-parallax-effect="scroll""><div class="parallax-background" style="background-image: url('/uploads/about-bg.jpg');"></div><div class="parallax-overlay" style="background-color: #0066cc; opacity: 0.6;"></div><div class="parallax-content">## About Our Company
Our story with a blue overlay for better readability</div></div>

Services Section with Red Overlay

<div class="parallax-section parallax-effect-scroll" id="services" data-parallax-speed="0.5" data-parallax-effect="scroll""><div class="parallax-background" style="background-image: url('/uploads/services-bg.jpg');"></div><div class="parallax-overlay" style="background-color: red; opacity: 0.7;"></div><div class="parallax-content">## Our Services
Professional services with red overlay for emphasis</div></div>

Contact Section with Custom Styling

<div class="parallax-section parallax-effect-scroll" id="contact" data-parallax-speed="0.4" data-parallax-effect="scroll""><div class="parallax-background" style="background-image: url('/uploads/contact-bg.jpg');"></div><div class="parallax-overlay" style="background-color: rgba(0,0,0,0.6); opacity: 0.6;"></div><div class="parallax-content"><div style="text-align: center; padding: 120px 0; color: white;">
    <h2>Get In Touch</h2>
    <p>Ready to start your next project? Let's talk!</p>
    <div style="margin-top: 30px;">
        <a href="mailto:hello@example.com" style="color: white; border: 1px solid white; padding: 12px 25px; text-decoration: none; margin: 0 10px; border-radius: 5px;">Email Us</a>
        <a href="tel:+1234567890" style="color: white; border: 1px solid white; padding: 12px 25px; text-decoration: none; margin: 0 10px; border-radius: 5px;">Call Us</a>
    </div>
</div></div></div>

Best Practices

Image Selection

High resolution: Use images at least 1920x1080 pixels
Optimized files: Compress images for faster loading
Aspect ratios: Consider how images will crop on different devices
File formats: WebP for modern browsers, JPG/PNG for compatibility

Content Styling

Text contrast: Use light text on dark backgrounds or vice versa
Text shadows: Add shadows for better readability over images
Content spacing: Provide adequate padding around text content
Responsive text: Use relative font sizes for mobile compatibility

Performance Tips

Image optimization: Compress background images appropriately
Section count: Limit to 3-5 parallax sections per page
Scroll speed: Use lower speed values (0.3-0.5) for subtle effects
Content length: Keep sections reasonably sized for smooth scrolling

Troubleshooting

Common Issues

Images not covering sections completely

Ensure images are high resolution (1920x1080+)
Check that background-size: cover is working
Verify no conflicting CSS is overriding parallax styles

Performance issues

Reduce the number of parallax sections
Use lower speed values
Optimize background images (compress, use WebP)

Text not readable

Add overlay_color and overlay_opacity attributes
Use text shadows in your content
Ensure sufficient contrast between text and background

Debug Mode

Enable debug logging by setting the environment variable:

export FCMS_DEBUG=true

This will log detailed information about parallax processing to help troubleshoot issues.

Content Management

Template Integration

Content separation: Parallax sections belong in markdown files, not templates
Dynamic rendering: Plugin automatically processes shortcodes in content
Theme compatibility: Works with all FearlessCMS themes
Plugin independence: No theme modifications required

File Organization

content/
├── home.md          # Contains parallax shortcodes
├── about.md         # Other content files
└── blog/
    └── post-1.md    # Blog posts with parallax sections

themes/
└── default/         # Theme templates (no parallax code needed)

Recent Improvements

v2.0 - Enhanced Coverage & Performance

Fixed image coverage issues - Backgrounds now maintain full coverage during all scroll positions
Improved CSS architecture - Clean, conflict-free styling with proper specificity
Enhanced JavaScript - Viewport-aware calculations and smooth performance
Better dark mode support - Automatic theme adaptation
Content separation - Moved from hardcoded templates to markdown files

Technical Fixes

CSS specificity issues resolved - Dark mode styles now work correctly
Image positioning improved - Centered backgrounds with proper overflow handling
Performance optimized - Hardware acceleration and smooth transitions
Mobile responsive - Better coverage on all device sizes

Future Enhancements

Additional effects: Fade, zoom, and rotation animations
Video backgrounds: Support for MP4 and WebM files
Advanced overlays: Gradient and pattern overlays
Performance monitoring: Built-in performance metrics
Accessibility: ARIA labels and keyboard navigation support

The Parallax Sections plugin is designed to be reliable, performant, and easy to use. It automatically handles the complexities of image coverage, scroll performance, and responsive design while maintaining clean, maintainable code.