Ctm Effects Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require contao-thememanager/ctm-effects
   

   Ensure your Laravel project uses Laravel 8+ (check composer.json for compatibility).

2. Publish Assets: Run the package’s asset publisher (if available) or manually link the JS/CSS files in your resources/views or public folder. Check the package’s README for exact paths (e.g., vendor/contao-thememanager/ctm-effects/dist/).

3. First Use Case:

   • Basic Animation: Add a class to a ThemeManager component (e.g., <div class="ctm-fade-in">) and include the package’s JS:

     <script src="{{ asset('vendor/contao-thememanager/ctm-effects/dist/ctm-effects.js') }}"></script>
     

   • Trigger Effects: Use data attributes (e.g., data-ctm-effect="slide-up") on elements to apply animations on page load or via JavaScript events.

4. Configuration: No config file is required for basic usage. For advanced options, check if the package supports a .env or config file (e.g., config/ctm-effects.php). If not, inspect the JS source for customization hooks.

Implementation Patterns

Core Workflows

1. Component Integration:

   • ThemeManager Components: Apply effects to existing ThemeManager components (e.g., modals, accordions, or sliders) by extending their classes or templates.

     <!-- Example: Add effect to a ThemeManager modal -->
     <div class="theme-manager-modal" data-ctm-effect="fade" data-ctm-duration="500">
         <!-- Modal content -->
     </div>
     

   • Custom Components: For non-ThemeManager elements, wrap them in a container with the effect class or use the package’s JS API to attach effects dynamically.

2. Event-Driven Effects:

   • Use JavaScript to trigger effects on user interactions (e.g., hover, click, or scroll):

     document.querySelector('.my-element').addEventListener('click', function() {
         CtmEffects.trigger(this, 'pulse', 300);
     });
     

   • Check the package’s API docs for available methods (e.g., CtmEffects.init(), CtmEffects.play()).

3. Performance Optimization:

   • Lazy Loading: Load effects only when needed (e.g., via Intersection Observer for below-the-fold elements).
   • Debouncing: For scroll-triggered effects, debounce the event listener to avoid performance hits:

     let ticking = false;
     window.addEventListener('scroll', function() {
         if (!ticking) {
             window.requestAnimationFrame(() => CtmEffects.checkScrollEffects());
             ticking = true;
         }
     });
     

4. Theming and Styling:

   • Override default styles by extending the package’s CSS variables (if supported) or by targeting its classes in your global CSS:

     /* Customize transition duration */
     .ctm-effect {
         transition-duration: 0.8s !important;
     }
     

   • Use SASS/PostCSS to compile custom animations if the package lacks flexibility.

5. Server-Side Rendering (SSR) Considerations:

   • If using Laravel Vapor or SSR frameworks (e.g., Inertia.js), ensure effects are only applied client-side:

     @if(!app()->runningInConsole())
         <script src="{{ asset('vendor/ctm-effects.js') }}"></script>
     @endif
     

Gotchas and Tips

Pitfalls

1. No Official Documentation:

   • The package lacks a README.md or dedicated docs. Reverse-engineer usage by inspecting:
     • Source Code: vendor/contao-thememanager/ctm-effects/src/ for classes/methods.
     • Tests: vendor/contao-thememanager/ctm-effects/tests/ for usage examples.
     • Release Notes: release/0.1.0.md for initial feature list.

2. Dependency Conflicts:

   • The package may rely on ThemeManager (unspecified version). Ensure compatibility:

     composer require contao/core-bundle  # If ThemeManager is a Symfony bundle
     

   • Check for jQuery or modern JS framework dependencies (e.g., Alpine.js) and include them manually if needed.

3. Animation Conflicts:

   • Effects may clash with existing CSS transitions/animations. Use unique classes or namespaces:

     <div class="my-prefix-fade-in">...</div>
     

   • Disable conflicting animations temporarily during development:

     .ctm-effect, .my-prefix-fade-in { transition: none !important; }
     

4. Browser Support:

   • Test effects on IE11 or older browsers if targeting legacy users. The package likely uses modern CSS/JS features (e.g., requestAnimationFrame).
   • Polyfills may be needed for critical projects:

     <script src="https://cdn.polyfill.io/v3/polyfill.min.js?features=default,Element.prototype.classList"></script>
     

5. Debugging:

   • Console Errors: Check browser dev tools (F12) for missing dependencies or typos in effect names.
   • Network Tab: Verify JS/CSS files load without 404s (e.g., ctm-effects.js).
   • Source Maps: If the package includes them, enable in your IDE for easier debugging.

Tips

1. Extending Functionality:

   • Custom Effects: Add new animations by extending the package’s JS:

     CtmEffects.registerEffect('custom-spin', {
         enter: 'transform: rotate(0deg);',
         leave: 'transform: rotate(360deg);'
     });
     

   • PHP Integration: Use Blade directives to conditionally load effects:

     @if(auth()->check())
         <div data-ctm-effect="slide-down">Welcome back!</div>
     @endif
     

2. Testing:

   • Write Jest or Laravel Dusk tests for critical effects:

     // Example Jest test
     test('applies fade effect', () => {
         document.body.innerHTML = '<div class="ctm-fade-in">Test</div>';
         CtmEffects.init();
         expect(document.querySelector('.ctm-fade-in')).toHaveStyle('opacity: 1');
     });
     

   • Test edge cases (e.g., rapid effect triggers, nested components).

3. Performance Monitoring:

   • Use Lighthouse or WebPageTest to audit animation performance. Aim for:
     • 60fps: Ensure transition-timing-function uses cubic-bezier for smoothness.
     • Low Layout Shifts: Avoid transform changes that trigger repaints.

4. Fallbacks:

   • Provide static content as a fallback for users with JS disabled:

     <noscript>
         <div class="static-fallback">This content loads without animations.</div>
     </noscript>
     

5. Community Support:

   • Open an issue on GitHub if stuck. Mention:
     • Laravel version.
     • ThemeManager version (if applicable).
     • Steps to reproduce the problem.
   • Check for forks or similar packages (e.g., laravel-animation) if this package is abandoned.