Sulu Preview Block Focus Bundle Laravel Package

Getting Started

Minimal Setup

1. Install the bundle:

   composer require alengo/sulu-preview-block-focus-bundle
   

   Register in config/bundles.php:

   Alengo\SuluPreviewBlockFocusBundle\PreviewBlockFocusBundle::class => ['all' => true],
   

2. Admin-side integration:

   • Add the dependency to assets/admin/package.json:

     "sulu-preview-block-focus-bundle": "file:../../vendor/alengo/sulu-preview-block-focus-bundle/assets/admin"
     

   • Install and import:

     cd assets/admin && npm install
     

     // assets/admin/app.js
     import 'sulu-preview-block-focus-bundle';
     

   • Rebuild:

     cd assets/admin && npm run build
     

3. Website-side integration (for preview iframe):

   • Add to webpack.config.js:

     .addEntry('suluPreviewBlockFocus', './vendor/alengo/sulu-preview-block-focus-bundle/assets/website/index.js')
     

   • Include conditionally in Twig:

     {% if sulu_user_loggedin_and_preview(app.request) %}
         {{ encore_entry_script_tags('suluPreviewBlockFocus') }}
     {% endif %}
     

4. Enable block focus in Twig templates:

   <div{{ (sulu_user_loggedin_and_preview(app.request) ? ' data-block-id="' ~ content._id ~ '"')|raw }}>
       {# Your block content #}
   </div>
   

First Use Case

Scenario: A content editor hovers over a block in the Sulu preview iframe, clicks the focus button, and expects the corresponding block in the admin panel to scroll into view and expand. Steps:

1. Open a page in Sulu’s preview mode.
2. Hover over a block—an overlay with a focus button appears.
3. Click the button—the admin panel scrolls to the matching block and expands it.

Implementation Patterns

Workflow Integration

1. Preview Context Detection: Use sulu_user_loggedin_and_preview(app.request) to conditionally render data-block-id and load the script only in preview mode. Avoid exposing block IDs in production.

2. Nested Block Support: The bundle handles nested blocks by sending parent-to-child IDs in sequence (e.g., parentId|childId). Ensure your Twig templates pass the correct _id for nested structures:

   <div data-block-id="{{ (sulu_user_loggedin_and_preview(app.request) ? content._id ~ (content.children|length ? '|' ~ content.children[0]._id : '') : '') }}">
   

3. Admin Panel React Integration: The admin-side script uses React fiber introspection to locate blocks. If your admin panel uses custom React components for blocks, ensure they are properly mounted in the React tree and accessible via ReactDOM.findDOMNode().

4. Custom Block Types: For custom block types, extend the bundle’s JavaScript logic:

   • Override the sulu-preview-block-focus-bundle admin script by publishing its assets:

     php bin/console assets:install public
     

   • Extend the SuluPreviewBlockFocusBundle class to add custom block selectors or logic.

5. Performance Considerations:

   • Lazy Loading: Load the website script only in preview mode to avoid unnecessary overhead.
   • Debouncing: The admin script may trigger performance spikes if handling many blocks. Test with large pages to ensure smooth scrolling/expansion.

Common Integration Patterns

Gotchas and Tips

Pitfalls

1. Block ID Exposure:

   • Risk: Accidentally exposing data-block-id in production.
   • Fix: Always wrap data-block-id in sulu_user_loggedin_and_preview() checks. Use Twig’s raw filter to avoid XSS risks.

2. React Tree Accessibility:

   • Issue: The admin script fails to find blocks if they are dynamically rendered or not part of the initial React tree.
   • Debug: Verify ReactDOM.findDOMNode() can locate your block components. Use console.log in the bundle’s JS to inspect the React tree.

3. Nested Block ID Format:

   • Mistake: Using incorrect delimiters (e.g., commas instead of |).
   • Fix: Ensure nested IDs are separated by | (e.g., parent|child). Test with nested structures in preview mode.

4. Admin Script Conflicts:

   • Problem: Custom admin JS might interfere with the bundle’s message listeners.
   • Solution: Wrap your custom logic in useEffect or ensure the bundle’s event listeners (sulu-preview-block-click) are not overridden.

5. Webpack Encore Cache:

   • Issue: Changes to suluPreviewBlockFocus entry not reflecting after rebuilds.
   • Fix: Clear Encore cache:

     rm -rf var/cache/dev/*
     npm run dev
     

Debugging Tips

1. Check Messages:

   • Open browser dev tools (Console tab) and listen for sulu-preview-block-click messages from the iframe to the admin window.

2. React DevTools:

   • Use React DevTools to inspect the React tree in the admin panel and verify block components are mounted.

3. Network Tab:

   • Ensure the website script (suluPreviewBlockFocus) loads only in preview mode. Check for 404 errors if the path is incorrect.

4. CSS Overrides:

   • If the focus button is invisible, inspect the generated HTML/CSS in the iframe. Override styles in:

     // assets/admin/styles/sulu-preview-block-focus.scss
     .sulu-preview-block-focus-button {
       opacity: 1 !important;
     }
     

Extension Points

1. Custom Block Selectors: Extend the admin script to support custom block types by overriding the getBlockElement logic in the bundle’s JS. Example:

   // Override in a custom admin script
   window.SuluPreviewBlockFocus = {
     ...window.SuluPreviewBlockFocus,
     getBlockElement: (blockId) => {
       // Custom logic for your block types
       return document.querySelector(`[data-custom-block-id="${blockId}"]`);
     }
   };
   

2. Animation Control: Disable or customize scroll/expand animations by modifying the admin script’s handleBlockClick method:

   window.SuluPreviewBlockFocus.handleBlockClick = (blockId) => {
     // Custom animation logic
     document.querySelector(`[data-block-id="${blockId}"]`).scrollIntoView({ behavior: 'auto' });
   };
   

3. Multi-Tab Support: If using multiple admin tabs (e.g., Sulu’s tabbed interfaces), ensure the bundle’s event listeners are scoped to the correct tab context. This may require extending the admin script to target specific tabs.

4. Server-Side Logic: For complex block structures, pre-process block IDs server-side (e.g., in a Twig extension) to generate the correct data-block-id format before rendering.