Block Settings Bundle Laravel Package

Getting Started

Minimal Setup

1. Install the package:

   composer require alengo/block-settings-bundle
   

2. Enable the bundle in config/bundles.php:

   Alengo\SuluBlockSettingsBundle\BlockSettingsBundle::class => ['all' => true],
   

3. Configure sections in config/packages/alengo_block_settings.yaml:

   alengo_block_settings:
       sections:
           - content_block_settings_theme
           - content_block_settings_spacing
   

4. Create XML forms for each section (e.g., config/forms/content_block_settings_theme.xml):

   <form xmlns="...">
       <key>content_block_settings_theme</key>
       <properties>
           <section name="theme">
               <property name="template_theme" type="select">
                   <!-- Define options -->
               </property>
           </section>
       </properties>
   </form>
   

First Use Case

Extend a block's settings with a theme selector and spacing controls without writing custom FormMetadataVisitor classes. The bundle injects these sections into the content_block_settings form automatically.

Implementation Patterns

Workflow for Adding New Sections

1. Define the XML form (e.g., content_block_settings_background.xml) with properties like:

   <property name="background_color" type="color" />
   <property name="background_image" type="media" />
   

2. Add the section key to alengo_block_settings.yaml:

   alengo_block_settings:
       sections:
           - content_block_settings_theme
           - content_block_settings_background  # New section
   

3. Clear cache to apply changes:

   php bin/console cache:clear
   

Integration with Sulu Blocks

• Dynamic block types: Use the bundle to inject settings for custom block types (e.g., custom_block_settings).

  alengo_block_settings:
      form_key: custom_block_settings
      sections:
          - custom_block_settings_layout
  

• Conditional injection: Leverage Sulu’s FormMetadataVisitor priority to override or extend existing settings.

Best Practices

• Order matters: Sections are injected in the order defined in sections. Reorder for UI consistency.
• Reuse forms: Share XML forms across projects by storing them in a shared package.
• Localization: The bundle handles locale-specific forms automatically (idempotent injection).

Gotchas and Tips

Pitfalls

1. Form Key Mismatch:

   • If form_key in config doesn’t match the target form (e.g., content_block_settings), sections won’t inject.
   • Fix: Verify the form key in XmlFormMetadataLoader matches the bundle’s config.

2. Duplicate Sections:

   • The bundle skips sections already present in the target form. If a section appears twice in sections, the first occurrence is used.
   • Fix: Use unique keys or debug with var_dump($form->getKey()) in a custom visitor.

3. Cache Dependencies:

   • Changes to XML forms or config require cache clearing:

     php bin/console cache:clear
     

Debugging

• Inspect injected forms: Override the visitor temporarily to log form structure:

  // src/Admin/FormMetadataVisitor/CustomVisitor.php
  public function visitFormMetadata(FormMetadata $formMetadata, FormMetadataVisitorContext $context) {
      if ($formMetadata->getKey() === 'content_block_settings') {
          var_dump($formMetadata->getProperties());
      }
  }
  

• Check XML validation: Invalid XML (e.g., missing key or section tags) will cause silent failures. Validate with:

  php bin/console debug:container Alengo\SuluBlockSettingsBundle\BlockSettingsFormMetadataVisitor
  

Extension Points

1. Custom Visitor Logic: Override the visitor to add dynamic behavior (e.g., skip sections based on block type):

   # config/services.yaml
   App\Admin\FormMetadataVisitor\CustomBlockSettingsVisitor:
       tags:
           - { name: sulu_admin.form_metadata_visitor, priority: -5 }
   

2. Dynamic Section Loading: Load sections from a database or API by extending BlockSettingsFormMetadataVisitor:

   public function visitFormMetadata(FormMetadata $formMetadata, FormMetadataVisitorContext $context) {
       if ($formMetadata->getKey() === $this->formKey) {
           $dynamicSections = $this->sectionLoader->loadDynamicSections();
           foreach ($dynamicSections as $section) {
               $this->loadSection($section, $formMetadata);
           }
       }
   }
   

3. Form Metadata Hooks: Use Symfony’s kernel.event_listener to modify forms before injection:

   services:
       App\EventListener\BlockSettingsFormListener:
           tags:
               - { name: kernel.event_listener, event: sulu_admin.form_metadata_loaded, method: onFormLoaded }