Contao Rocksolid Icon Picker Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require madeyourday/contao-rocksolid-icon-picker
   

   Ensure your composer.json includes "minimum-stability": "dev" if using Contao 5.x.

2. First Use Case:

   • Add the icon picker to a custom content element or DCA field (e.g., tl_content or a custom table).
   • Example DCA integration (in dca.php):

     $GLOBALS['TL_DCA']['tl_content']['fields']['iconPicker'] = [
         'label'     => &$GLOBALS['TL_LANG']['tl_content']['iconPicker'],
         'inputType' => 'iconPicker',
         'eval'      => ['tl_class' => 'clr', 'mandatory' => false],
         'options'   => ['fontPath' => 'bundles/rocksolidiconpicker/font'],
     ];
     

   • Backend: The icon picker appears as a modal with a grid of icons (e.g., Font Awesome, custom SVG). Note: WOFF2 fonts are now loaded in the backend by default (v2.1.2+).

3. Frontend Output: Use the icon in templates via:

   <i class="icon {{ $row->iconPicker }}"></i>
   

   Or with dynamic styling:

   echo '<i class="icon ' . $this->iconPicker . '" style="color: ' . $this->iconColor . ';"></i>';
   

Implementation Patterns

Common Workflows

1. Dynamic Icon Selection:

   • Use in custom modules or content elements where users need to pick icons (e.g., buttons, social media links).
   • Example: Add to a tl_module field:

     $GLOBALS['TL_DCA']['tl_module']['fields']['moduleIcon'] = [
         'inputType' => 'iconPicker',
         'eval'      => ['mandatory' => true],
     ];
     

2. Theming Integration:

   • Override icon sets by extending the fontPath in DCA:

     'options' => ['fontPath' => 'assets/fonts/custom-icons'],
     

   • Ensure the font files (.woff, .woff2) are accessible via the defined path. Note: WOFF2 files are now prioritized in both frontend and backend.

3. Conditional Logic:

   • Toggle visibility based on field values:

     'eval' => [
         'mandatory' => $this->isRootElement ? true : false,
         'iconPicker' => ['allowBlank' => !$this->isRootElement],
     ],
     

4. Backend Configuration:

   • Dark Mode Support: The package auto-adapts to Contao’s dark theme (no extra config needed).
   • Blank Option: Automatically adds a "none" option if mandatory => false.
   • WOFF2 Backend Support: Icons now render smoothly in the backend with WOFF2 fonts (v2.1.2+).

5. Frontend Styling:

   • Use CSS to style icons dynamically:

     .icon-picked { color: var(--theme-color); }
     .icon-picked:hover { transform: scale(1.1); }
     

Integration Tips

• Contao 4 vs. 5:

  • For Contao 5, ensure symfony/flex is configured in composer.json:

    "extra": {
        "contao": {
            "version": "5.0"
        }
    }
    

• Custom Icon Sets:

  • Place fonts in assets/fonts/ and reference them in fontPath.
  • Example structure:

    /assets/fonts/
      ├── custom-icons.woff
      ├── custom-icons.woff2  // WOFF2 now preferred
    

  • Update DCA:

    'options' => ['fontPath' => 'assets/fonts', 'iconSet' => 'custom-icons'],
    

• Performance:

  • Preload fonts in assets.json (Contao 5) or via <link rel="preload">:

    <link rel="preload" href="assets/fonts/custom-icons.woff2" as="font" type="font/woff2" crossorigin>
    

  • Backend Optimization: WOFF2 fonts reduce backend load times (v2.1.2+).

Gotchas and Tips

Pitfalls

1. Font Path Issues:

   • Symptom: Icons don’t render; console shows 404 for font files.
   • Fix:
     • Verify fontPath points to a web-accessible directory (e.g., web/fonts/).
     • On Windows, use forward slashes (web/fonts/), not backslashes.
     • Clear Contao cache (php contao-console cache:clear).
     • WOFF2 Priority: Ensure .woff2 files exist alongside .woff files for optimal loading.

2. Dark Mode Conflicts:

   • Symptom: Icons appear invisible in dark mode.
   • Fix:
     • Ensure the icon font uses color: currentColor (default in RockSolid’s sets).
     • Override CSS if needed:

       .icon { color: inherit !important; }
       

3. Blank Option Missing:

   • Symptom: "None" option doesn’t appear even with mandatory => false.
   • Fix:
     • Check for typos in DCA (e.g., 'iconPicker' vs. 'icon_picker').
     • Update to v2.1.2+ (automatically handles WOFF2 backend loading).

4. Contao 5 Symfony Mismatch:

   • Symptom: "Class not found" errors after upgrading.
   • Fix:
     • Ensure symfony/dependency-injection and symfony/http-kernel are compatible with Contao 5.
     • Run:

       composer require symfony/dependency-injection:^6.0
       composer require symfony/http-kernel:^6.0
       

5. Icon Names Merging:

   • Symptom: Custom icon names clash with default sets.
   • Fix:
     • Use a unique prefix (e.g., custom- or myproject-).
     • Example: iconSet: 'custom-icons' in DCA options.

Debugging Tips

• Check Font Loading:

  • Inspect network requests in DevTools for failed font loads.
  • Test paths manually: http://yoursite.com/web/fonts/custom-icons.woff2.
  • WOFF2 Debugging: Verify WOFF2 files are loaded in the backend (v2.1.2+).

• DCA Validation:

  • Add debug output to verify DCA loading:

    echo '<pre>'; print_r($GLOBALS['TL_DCA']['tl_your_table']['fields']); echo '</pre>';
    

• Clear Caches Aggressively:

  • After changes, run:

    php contao-console cache:clear --env=prod
    php contao-console assets:generate
    

Extension Points

1. Custom Icon Sets:

   • Extend the icon picker by adding new font files and updating fontPath.
   • Example: Create a CustomIconPicker class to override default behavior:

     class CustomIconPicker extends IconPicker {
         protected function getIconOptions() {
             $options = parent::getIconOptions();
             $options['iconSet'] = 'my-custom-set';
             $options['preferWoff2'] = true; // Explicitly enable WOFF2
             return $options;
         }
     }
     

   • Register in config/autoload.php:

     $container->set('icon_picker', CustomIconPicker::class);
     

2. Dynamic Icon Filtering:

   • Use JavaScript to filter icons in the picker modal:

     // In a custom JS file
     $(document).on('ready.pjax', function() {
         $('.icon-picker-modal').on('show', function() {
             $('.icon-grid .icon').filter(':not(.fa-brands)').hide(); // Hide brands only
         });
     });
     

3. Backend Localization:

   • Override icon labels in languages/en/tl_content.php:

     $GLOBALS['TL_LANG']['tl_content']['iconPicker'] = ['Icon', 'Select an icon'];
     

4. Frontend Fallbacks:

   • Provide fallback icons for unsupported browsers:

     <i class="icon {{ $row->iconPicker }} icon-fallback"></i>
     <style>
         .icon-fallback { background-image: url('themes/default/img/fallback-icon.svg'); }
     </style>
     

5. WOFF2 Fallback Handling:

   • Add a fallback for browsers not supporting WOFF2:

     @supports not (font-variation-settings: normal)