Contao Rocksolid Custom Elements Laravel Package

Getting Started

Minimal Setup

1. Install the package:

   composer require madeyourday/contao-rocksolid-custom-elements
   

2. Activate the extension in Contao’s config/autoload.php:

   'rocksolid_custom_elements' => ['enabled' => true],
   

3. Create a basic custom element:
   • Define a YAML config file (e.g., resources/contao/custom_elements/my_element.yaml):

     name: "My Custom Element"
     type: "text"
     template: "ce_my_element"
     fields:
       - name: "headline"
         type: "text"
         label: "Headline"
     

   • Register the config in config/autoload.php:

     'rocksolid_custom_elements' => [
         'enabled' => true,
         'elements' => [
             'my_element' => 'path/to/my_element.yaml',
         ],
     ],
     

4. Create a Twig template (templates/ce_my_element.html5):

   <div class="my-element">
       <h2>{{ element.headline }}</h2>
       {{ element.content|raw }}
   </div>
   

First Use Case

Use the package to replace generic Contao content elements (e.g., text, html) with domain-specific components (e.g., testimonial, pricing_table). For example:

• Build a nested testimonial element with fields for name, role, quote, and avatar.
• Restrict placement to specific page types via allowedIn in the YAML config.
• Note: Ensure compatibility with Contao 5.7 (fixed in v2.4.15).

Implementation Patterns

1. Modular Element Definition

• YAML-based configuration centralizes element logic:

  name: "Pricing Table"
  type: "table"  # Supports: text, table, list, group, etc.
  template: "ce_pricing_table"
  fields:
    - name: "title"
      type: "text"
      label: "Table Title"
    - name: "items"
      type: "list"
      label: "Pricing Items"
      fields:
        - name: "name"
          type: "text"
          label: "Plan Name"
        - name: "price"
          type: "text"
          label: "Price"
          default: "$0"
  

• Reuse fields across elements via extends:

  extends: "base_fields.yaml"
  

2. Conditional Logic

• Dynamic field visibility with dependsOn:

  fields:
    - name: "show_cta"
      type: "checkbox"
      label: "Show CTA Button"
    - name: "cta_text"
      type: "text"
      label: "CTA Text"
      dependsOn: "show_cta"  # Hidden unless checkbox is checked
  

• Backend validation: Use validate callbacks in PHP for complex rules.

3. Nested Elements

• Group elements for hierarchical content:

  type: "group"
  fields:
    - name: "tabs"
      type: "list"
      label: "Tabs"
      fields:
        - name: "title"
          type: "text"
        - name: "content"
          type: "html"
  

• Template inheritance: Extend base templates (e.g., ce_base.html5) for shared markup.

4. Integration with Contao Workflows

• Backend integration:
  • Elements appear in the Contao content picker (tl_content).
  • Use palettes to organize fields logically:

    palettes:
      default: "title;items"
    

• Frontend rendering:
  • Override default templates in templates/ce_* for custom styling.
  • Use Twig’s {{ element|rocksolid_custom_elements }} filter for dynamic content.
• Contao 5.7 Compatibility: Widgets now fully support Contao 5.7 (fixed in v2.4.15).

5. Advanced Features

• Custom widgets: Extend the package’s widget system (e.g., for drag-and-drop builders).
• API hooks: Attach to rocksolid_custom_elements.load or rocksolid_custom_elements.save for custom logic.
• Asset management: Bundle CSS/JS per element via assets key in YAML.

Gotchas and Tips

Pitfalls

1. Template Paths:

   • Twig templates must be named ce_<element_name>.html5 and placed in templates/.
   • Fix: Verify the template key in YAML matches the filename exactly.

2. Field Dependencies:

   • dependsOn does not work with type: "hidden" fields.
   • Fix: Use type: "checkbox" with eval: "tl_class=invisible" for hidden-but-conditional fields.

3. Contao Version Mismatches:

   • Contao 5.7: Fully supported in v2.4.15 (previously had widget compatibility issues).
   • Older versions: Use v2.3.x for Contao <4.9 or 4.9–5.6.
   • Check: Run php bin/contao-requirements-check after updates.

4. Nested List Quirks:

   • Bug: List items may swallow subsequent fields if misconfigured.
   • Fix: Ensure type: "list" fields include a unique name and proper fields structure.

5. Backend Route Conflicts:

   • Issue: Custom backend routes may clash with Contao’s router.
   • Fix: Prefix routes with rocksolid_custom_elements_ (e.g., rocksolid_custom_elements.my_element).

Debugging Tips

• Enable debug mode in config/localconfig.php:

  $GLOBALS['TL_DEBUG'] = true;
  

• Check YAML syntax: Use a validator like YAML Lint for config files.
• Inspect DCA: Dump the generated tl_content fields:

  \System::log(\Database::getInstance()->prepare("SELECT * FROM tl_content WHERE type='my_element'")->execute()->fetchAll(), 'DEBUG');
  

• Clear cache after config changes:

  php bin/contao-console cache:clear
  

Extension Points

1. Custom Widgets:

   • Extend \RockSolid\CustomElementsBundle\Widget\AbstractWidget for new field types.
   • Contao 5.7: Ensure widgets implement ContaoCoreBundle\Framework\Widget\WidgetInterface for full compatibility.

2. Validation Hooks:

   • Implement RockSolid\CustomElementsBundle\Event\ValidateElementEvent for pre-save checks:

     $eventDispatcher->addListener(
         'rocksolid_custom_elements.validate.my_element',
         function ($event) {
             if (empty($event->getData()['headline'])) {
                 $event->setError('Headline is required.');
             }
         }
     );
     

3. Twig Extensions:

   • Add custom filters/functions to rocksolid_custom_elements.twig:

     {% macro render_element(element) %}
         {{ include('ce_' ~ element.type ~ '_' ~ element.template) with {
             'element': element
         }}}
     {% endmacro %}
     

4. Asset Bundling:

   • Override the default asset pipeline by binding a custom AssetManager:

     $container->bind('rocksolid_custom_elements.asset_manager', function () {
         return new \App\CustomAssetManager();
     });
     

Performance

• Avoid heavy computations in onload callbacks (run async if possible).
• Lazy-load non-critical fields (e.g., images) with eval: "mandatory=false".
• Cache templates: Use Twig’s {% cache %} for static elements.

Migration Tips

• Update from v2.x to v2.4.15:
  • Contao 5.7 users: No action required—widget compatibility is now fixed.
  • Downgrade Contao: Use composer require contao/core:4.9.* and the package’s v2.3.x branch.
• Downgrade package: For Contao <5.7, use v2.3.x to avoid widget issues.

Contao 5.7-Specific Notes

• Widget Compatibility: All built-in widgets (e.g., text, textarea, select) now work seamlessly.
• Backend UI: Updated to match Contao 5.7’s styling (e.g., improved field layouts).
• Testing: Verify custom widgets by extending AbstractWidget and implementing WidgetInterface.