Contao Component Style Manager Laravel Package

Getting Started

Minimal Steps

1. Installation:

   composer require oveleon/contao-component-style-manager
   

   Or via Contao Manager by searching for "StyleManager."

2. First Use Case:

   • Navigate to Contao Backend → System → Style Manager.
   • Create a new archive (e.g., my_theme_classes) and define groups (e.g., colors, spacing).
   • Add CSS classes (e.g., bg-red, mt-2) with labels and descriptions.
   • Assign the archive to a page, module, or content element via the backend widget.

3. Template Integration: Use the template variable $styleManagerClasses in your Twig templates to output the selected classes:

   <div class="{{ styleManagerClasses.my_theme_classes }}">
       Your content here
   </div>
   

Implementation Patterns

Core Workflows

1. Backend Configuration:

   • Archives: Organize classes into logical groups (e.g., header_styles, button_variants).
   • Groups: Use tabs or collapsible sections for better UX (e.g., colors, animations).
   • Classes: Define CSS classes with:
     • Labels (user-friendly names, e.g., "Red Background").
     • Descriptions (tooltip hints).
     • Scope: Limit visibility to specific elements (e.g., extendModule: ["news_list"]).
     • Label Callback: Use label_callback (replaces deprecated child_record_callback) for dynamic labels:

       my_group:
           classes:
               dynamic_class:
                   label_callback: "App\Callback\DynamicLabelCallback"
       

2. Template Usage:

   • Passing Data:

     {{ styleManagerClasses.my_archive_identifier|join(' ') }}
     

   • Conditional Logic:

     {% if styleManagerClasses.my_archive_identifier contains 'bg-dark' %}
         <div class="dark-mode">
     {% endif %}
     

3. Dynamic Integration:

   • Modules/Content Elements: Extend DCA (Data Container Array) for custom elements:

     // config/autoload/contao-style-manager.php
     return [
         'style_manager' => [
             'archives' => [
                 'my_custom_archive' => [
                     'title' => 'Custom Archive',
                     'groups' => [
                         'my_group' => [
                             'title' => 'My Group',
                             'classes' => [
                                 'custom-class' => 'Custom Class Label',
                             ],
                         ],
                     ],
                 ],
             ],
         ],
     ];
     

   • Forms: Enable via extendFormFields: true in YAML/Backend config.

4. YAML Configuration (Recommended for Reusability): Create /templates/style-manager-custom.yaml:

   my_archive:
       title: "Custom Styles"
       groupAlias: my_group
       children:
           my_group:
               cssClasses:
                   "text-bold": "Bold Text"
                   "text-italic": "Italic Text"
               extendContentElement: true
               contentElements: ["text", "headline"]
   

Integration Tips

• Bundle Configurations: Use BundleConfigListener to load styles from vendor packages (e.g., themes).
• Partial Imports: Merge YAML files dynamically without overwriting existing archives.
• Frontend Validation: Sanitize output in Twig:

  {{ styleManagerClasses.my_archive|replace({' ': '_'}) }}
  

• Performance: Cache template variables if used frequently:

  // In a custom service or controller
  $this->StyleManager->getClassesForArchive('my_archive');
  

Gotchas and Tips

Pitfalls

1. Deprecated Features:

   • child_record_callback is removed in v3.12.1. Replace with label_callback for dynamic labels.
   • XML import/export is deprecated (use YAML/Bundle Config instead).

2. PHP/Contao Compatibility:

   • Requires Contao 5.7+ and PHP 8.3+ (as of v3.12.1).
   • Backward compatibility breaks may occur with older versions (e.g., Symfony 7.3+ in v3.9.3).

3. YAML Parsing Issues:

   • Ensure YAML files are placed in /templates/ or /vendor/ with correct naming (style-manager-*.yaml).
   • Avoid duplicate pid or id keys when merging configurations.

4. Backend Widget Quirks:

   • Keyboard Accessibility: Buttons replaced checkboxes for better focus management (v3.9.0+).
   • Default Width: Changed to 4 columns (override with CSS: --sm-i: 3 or .w33 class).
   • Blank Options: Requires explicit blankOption: true in YAML.

5. Template Variable Scope:

   • Variables are not automatically available in all templates. Ensure they’re passed via:

     $this->Template->styleManagerClasses = $this->StyleManager->getClassesForArchive('my_archive');
     

Debugging Tips

1. Check Archive Assignment: Verify archives are linked to the correct DCA in the backend widget settings.

2. YAML Validation: Use a validator (e.g., YAML Lint) to catch syntax errors.

3. Backend Logs: Enable Contao’s debug mode (config/localconfig.php):

   $GLOBALS['TL_CONFIG']['debugMode'] = true;
   

   Check for errors in System → Log.

4. Class Output: Debug template variables with:

   {{ dump(styleManagerClasses) }}
   

Extension Points

1. Custom Form Fields: Extend form fields by adding to YAML:

   my_group:
       extendFormFields: true
       formFields: ["input", "textarea"]
   

2. Third-Party DCA Support: Register custom DCAs in config/autoload/contao-style-manager.php:

   return [
       'style_manager' => [
           'supported_dcas' => [
               'tl_my_custom_table' => [
                   'archive_identifier' => 'my_custom_archive',
               ],
           ],
       ],
   ];
   

3. Override Widget Templates: Copy /vendor/oveleon/contao-component-style-manager/src/Resources/contao/templates/ to /templates/ and modify:

   • style_manager_widget.html5 (main widget).
   • style_manager_group.html5 (group tabs).

4. Event Listeners: Hook into the style_manager.archives.load event to dynamically modify archives:

   // src/EventListener/StyleManagerListener.php
   public function onLoadArchives(StyleManagerEvent $event) {
       $event->getArchives()->add('dynamic_archive', [
           'title' => 'Dynamic Archive',
           // ...config
       ]);
   }
   

   Register in services.yaml:

   services:
       App\EventListener\StyleManagerListener:
           tags:
               - { name: kernel.event_listener, event: style_manager.archives.load, method: onLoadArchives }
   

5. CSS/JS Overrides: Load custom assets via AddBackendAssetsListener:

   // src/EventListener/AddBackendAssetsListener.php
   public function onAddBackendAssets(BackendAssetsEvent $event) {
       $event->addCssFile('bundles/mytheme/css/style-manager-override.css');
   }
   

   Note: Ensure your callback classes implement StyleManagerLabelCallbackInterface for label_callback:

   class DynamicLabelCallback implements StyleManagerLabelCallbackInterface {
       public function getLabel(string $className, array $config): string {
           return "Dynamic Label for {$className}";
       }
   }