Ctm Placeholder Label Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require contao-thememanager/ctm-placeholder-label
   

   Ensure the package is enabled in config/packages.php or via Contao's extension manager.

2. ThemeManager Configuration

   • Navigate to Themes > [Your Theme] > Settings > Placeholder Label.
   • Configure the four provided CSS variables ($pl-input-top-offset, $pl-textarea-top-offset, $pl-label-filled-top-offset, $pl-label-filled-font-size) to match your design requirements.

3. CSS Integration

   • In your theme's Layout > Stylesheet Settings, add _placeholderlabel.css after _theme.css (order matters).
   • Example order in layout.css:

     /* ... other styles ... */
     @import '_theme.css';
     @import '_placeholderlabel.css';
     

4. JavaScript Integration

   • In your theme's Layout > JavaScript Template, add js_ctm_placeholderlabel.
   • Ensure the script loads after jQuery (if not already handled by Contao).

5. First Use Case Add a form field (e.g., <input type="text" name="email" placeholder="Your Email">) in a template. The placeholder will animate when the field is filled, and the label will shift upward based on your configured offsets.

Implementation Patterns

Core Workflow

1. Form Field Styling Use the package to replace static placeholders with animated labels. Example:

   <form>
       <input type="text" name="username" class="form-control">
       <label for="username">Username</label>
   </form>
   

   • The package will handle the placeholder-to-label transition via CSS/JS.

2. Dynamic Configuration Override default offsets per form type (e.g., textareas vs. inputs):

   /* In your theme's CSS */
   $pl-textarea-top-offset: 12px;
   $pl-label-filled-font-size: 14px;
   

3. Excluding Forms Disable the effect for specific forms by adding the pl-none class:

   <form class="pl-none">
       <!-- Placeholder label disabled -->
   </form>
   

4. Custom JavaScript Extend or override the default behavior by modifying js_ctm_placeholderlabel:

   // Override the default options
   window.ctmPlaceholderLabelConfig = {
       selector: '.custom-form',  // Target specific forms
       excludeClass: 'no-animation' // Custom exclusion class
   };
   

5. Integration with Contao Forms For Contao-managed forms, ensure the package’s JS/CSS is included in the Form Layout settings:

   • Layout > [Your Form] > CSS/JS Includes → Add _placeholderlabel.css and js_ctm_placeholderlabel.

Advanced Patterns

1. Conditional Label Animation Use Contao’s enctype or custom classes to toggle animations:

   <input type="text" name="password" class="pl-animate-on-focus">
   

   Extend the JS to handle this:

   window.ctmPlaceholderLabelConfig = {
       selector: 'form',
       customTriggers: ['focus', 'input'] // Add custom events
   };
   

2. Theme-Specific Overrides Create a child theme to override the package’s CSS/JS without modifying the parent theme’s settings.

3. Accessibility Ensure labels remain accessible by pairing with aria-label or aria-labelledby:

   <input type="text" name="search" aria-labelledby="search-label">
   <label id="search-label">Search</label>
   

Gotchas and Tips

Pitfalls

1. CSS Order Dependency

   • Issue: Placeholder labels may not animate if _placeholderlabel.css is loaded before _theme.css.
   • Fix: Strictly follow the order: _theme.css → _placeholderlabel.css.

2. JavaScript Conflicts

   • Issue: If jQuery is not loaded before js_ctm_placeholderlabel, the script fails silently.
   • Fix: Verify jQuery is included in your theme’s JS template (Contao typically handles this).

3. Form Field Selector Mismatch

   • Issue: The default selector: 'form' may target unintended forms (e.g., Contao backend forms).
   • Fix: Narrow the selector (e.g., .frontend-form) or use the excludeClass to opt out.

4. Custom CSS Variable Overrides

   • Issue: Overriding $pl-* variables in a child theme may not apply if the parent theme’s CSS is cached.
   • Fix: Clear Contao’s cache (contao:clear-cache) or use !important sparingly.

5. Textarea Handling

   • Issue: Textareas may require additional padding/margin adjustments due to their default styling.
   • Fix: Increase $pl-textarea-top-offset or add custom CSS:

     textarea.form-control {
         padding-top: calc(var(--pl-textarea-top-offset) + 2px);
     }
     

Debugging Tips

1. Inspect Element Use browser dev tools to check if:

   • CSS variables (--pl-input-top-offset) are applied.
   • The JS file (js_ctm_placeholderlabel) is loaded and error-free.

2. Console Logs Add debug logs to js_ctm_placeholderlabel to verify initialization:

   console.log('PlaceholderLabel initialized for:', window.ctmPlaceholderLabelConfig.selector);
   

3. Disable Caching Temporarily disable Contao’s cache to rule out cached assets:

   // config/localconfig.php
   $GLOBALS['TL_CACHEDIR'] = '/tmp/contao-cache';
   

Extension Points

1. Custom Animations Extend the JS to support GSAP, Anime.js, or CSS transitions:

   // Example: Replace default fade with slide-up
   window.ctmPlaceholderLabelConfig.animation = {
       enter: 'slideUp',
       exit: 'slideDown'
   };
   

2. Server-Side Validation Hooks Trigger label animations on form submission success/failure via Contao hooks:

   // config/config.php
   $GLOBALS['TL_HOOKS']['outputFrontendTemplate'][] = function() {
       if (\Input::get('do') === 'save' && \Input::get('token') === \Session::get('CSRF')) {
           echo '<script>document.querySelectorAll(".form-success").each(function(el) {
               el.querySelector("input").dispatchEvent(new Event("input"));
           });</script>';
       }
   };
   

3. Multi-Language Support Dynamically update labels for multilingual forms by binding to Contao’s language switcher:

   document.addEventListener('languageChanged', function() {
       window.ctmPlaceholderLabel.init();
   });