Ctm Sticky Header Laravel Package

Getting Started

Minimal Steps

1. Installation

   composer require contao-thememanager/ctm-sticky-header
   

   Ensure the package is autoloaded in composer.json and run composer dump-autoload.

2. Enable in Theme Manager

   • Navigate to Theme Manager in Contao backend.
   • Select your target theme and enable the "Sticky Header" module under the "Extensions" tab.

3. Configure CSS/JS

   • In your theme’s Layout settings:
     • Add _stickyheader.css to the Layout stylesheet field.
     • Add js_ctm_stickyheader to the JavaScript template field.

4. CSS Order Ensure your theme’s CSS includes _stickyheader.css before _theme.css (Theme Manager core) for proper rendering.

5. First Use Case

   • Set $sh-background-start (e.g., #ffffff) and $sh-color-start (e.g., #333333) in the Sticky Header settings.
   • Preview the frontend to verify the header sticks on scroll with the configured colors.

Implementation Patterns

Workflows

1. Dynamic Styling Use the start/end color variables ($sh-background-start, $sh-background-end) to create gradient or transition effects as the header scrolls. Example:

   // _stickyheader.css
   .sticky-header {
     background: var(--sh-background-start);
     transition: background 0.3s ease;
   }
   .sticky-header.scrolled {
     background: var(--sh-background-end);
   }
   

2. Integration with Contao Elements

   • Navigation Menus: Style menu items using $sh-color-start/$sh-color-end for consistent hover/active states.
   • Logo/Images: Ensure assets in the sticky header are optimized for small dimensions (e.g., SVG or compressed PNGs).

3. JavaScript Hooks Extend functionality via Contao’s frontend hooks. Example: Trigger custom logic when the header sticks:

   // config/autoload.php
   $GLOBALS['TL_HOOKS']['ctmStickyHeaderOnStick'][] = function() {
       // Add your custom JS logic here
       echo '<script>console.log("Header stuck!");</script>';
   };
   

4. Responsive Adjustments Use media queries in _stickyheader.css to disable sticking on mobile:

   @media (max-width: 768px) {
       .sticky-header { position: relative !important; }
   }
   

5. Performance Optimization

   • CSS: Combine _stickyheader.css with other critical CSS files to reduce HTTP requests.
   • JS: Defer js_ctm_stickyheader loading until after DOM content is loaded (if using Contao’s onload hooks).

Gotchas and Tips

Pitfalls

1. CSS Specificity Conflicts

   • If the sticky header doesn’t render, check for conflicting styles in _theme.css. Use !important sparingly; instead, increase specificity in _stickyheader.css:

     body .sticky-header { /* Target more precisely */ }
     

2. JavaScript Errors

   • Ensure js_ctm_stickyheader is loaded after the DOM is ready. If using Contao’s onload hooks, verify the hook is registered correctly:

     $GLOBALS['TL_JAVASCRIPT']['ctm_stickyheader'] = 'js/ctm_stickyheader.js|static';
     

3. Scroll Behavior Issues

   • If the sticky header lags or jumps, add will-change: transform to the CSS for smoother animations:

     .sticky-header { will-change: transform; }
     

4. Theme Manager Cache

   • Clear Contao’s cache (?purge=1) after enabling the module or updating settings. The backend cache may persist old configurations.

5. Browser Compatibility

   • Test in older browsers (e.g., IE11) if supporting legacy users. Use polyfills for IntersectionObserver if needed.

Debugging Tips

1. Inspect Variables Use browser dev tools to verify CSS variables are applied:

   .sticky-header {
     background: var(--sh-background-start) !important; /* Temporarily force */
   }
   

2. Check JS Console Look for errors in the console when scrolling. Common issues:

   • Missing IntersectionObserver support (add a fallback).
   • Conflicts with other sticky/scroll libraries (e.g., lazy-loading scripts).

3. Fallback for No-JS Style the header to appear sticky by default in CSS:

   .sticky-header { position: sticky; top: 0; }
   

Extension Points

1. Custom Transitions Override the default JavaScript behavior by extending the ctmStickyHeader class:

   // js/custom_stickyheader.js
   document.addEventListener('DOMContentLoaded', function() {
       const originalStick = ctmStickyHeader.stick;
       ctmStickyHeader.stick = function() {
           originalStick.call(this);
           // Add custom logic (e.g., analytics tracking)
       };
   });
   

2. Additional Triggers Use Contao’s onload hooks to add sticky behavior to non-header elements:

   $GLOBALS['TL_HOOKS']['frontendOutput'][] = function() {
       if (\Input::get('autoSticky')) {
           echo '<script>document.querySelector(".custom-element").classList.add("sticky");</script>';
       }
   };
   

3. Server-Side Logic Dynamically enable/disable the sticky header based on user roles or page types:

   $GLOBALS['TL_HOOKS']['getPageLayout'][] = function($page) {
       if ($page->type === 'home') {
           $GLOBALS['TL_CONFIG']['ctmStickyHeaderEnabled'] = true;
       }
   };