Block Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require arkounay/block-bundle
   

   Add to AppKernel.php:

   new Arkounay\BlockBundle\ArkounayBlockBundle(),
   

2. Assets & Routes:

   php bin/console assets:install
   

   Import routes in routing.yml:

   block:
       resource: "@ArkounayBlockBundle/Resources/config/routing.yml"
   

3. Twig Setup: Include CSS/JS in your base template:

   {% include '@ArkounayBlock/assets/include_css.html.twig' %}
   {% if has_inline_edit_permissions() %}
       <script src="https://code.jquery.com/jquery-3.1.1.min.js"></script>
       <script src="https://cdnjs.cloudflare.com/ajax/libs/tinymce/4.4.3/tinymce.min.js"></script>
   {% endif %}
   {% include '@ArkounayBlock/assets/include_js.html.twig' %}
   

4. First Editable Block:

   {{ render_block('homepage_hero') }}
   

   First edit creates a PageBlock entity in the DB.

First Use Case: CMS-Style Page Editing

Add a WYSIWYG-editable hero section to your homepage:

<div class="hero">
    {{ render_block('homepage_hero', true, 'div') }}
</div>

• Admin clicks the block → TinyMCE editor loads.
• Non-admin sees rendered HTML.

Implementation Patterns

Core Workflows

1. Dynamic Blocks:

   {% for section in ['header', 'footer', 'sidebar'] %}
       {{ render_block(section) }}
   {% endfor %}
   

   • Reuse blocks across templates with unique IDs.

2. Entity Field Integration:

   {{ render_entity_field(post, 'content') }}
   

   • Extend existing entities (e.g., Post) with inline editing.

3. Conditional Loading:

   {% if app.user.hasRole('ROLE_EDITOR') %}
       {% include '@ArkounayBlock/assets/include_js.html.twig' %}
   {% endif %}
   

   • Optimize asset loading for specific roles.

Integration Tips

1. Custom TinyMCE Config: Override the default JS template (@ArkounayBlock/assets/include_js.html.twig):

   <script>
       tinymce.init({
           selector: '.js-arkounay-block-bundle-editable',
           plugins: 'code table',
           toolbar: 'bold italic | alignleft aligncenter alignright'
       });
   </script>
   

2. Database Schema: Run after installation:

   php bin/console doctrine:schema:update --force
   

   • Creates page_block table for block storage.

3. Permissions: Configure allowed roles in config.yml:

   arkounay_block:
       roles: ['ROLE_ADMIN', 'ROLE_EDITOR']
   

4. Shortcut Tags: Use predefined wrappers:

   {{ render_span_block('small_text') }}  {# Renders in <span> #}
   

Gotchas and Tips

Pitfalls

1. TinyMCE Dependency:

   • Issue: Bundle requires jQuery + TinyMCE (not bundled).
   • Fix: Ensure scripts are loaded after the editable block in Twig.

2. CSRF Token Mismatch:

   • Issue: Ajax saves may fail if CSRF token is missing.
   • Fix: Verify {% csrf_token %} is included in forms or templates.

3. Database Conflicts:

   • Issue: Schema updates may fail if page_block table exists.
   • Fix: Backup DB before running doctrine:schema:update.

4. Role-Based Rendering:

   • Issue: has_inline_edit_permissions() may return false unexpectedly.
   • Fix: Debug with:

     {{ dump(app.user.getRoles()) }}
     

Debugging Tips

1. Check Block Existence:

   php bin/console doctrine:query:sql "SELECT * FROM page_block WHERE id = 'block_id'"
   

2. TinyMCE Console Errors:

   • Open browser dev tools (F12) to verify TinyMCE initialization:

     console.log(tinymce.editors);  // Check if editor is loaded
     

3. Ajax Debugging:

   • Inspect network requests for failed saves (status 403 = permission issue).

Extension Points

1. Custom Block Types: Extend PageBlock entity to add metadata (e.g., layout_type):

   // src/Entity/CustomBlock.php
   class CustomBlock extends PageBlock {
       private $layoutType;
   }
   

2. Override Twig Functions: Create a custom Twig extension to modify rendering logic:

   // src/Twig/BlockExtension.php
   class BlockExtension extends \Twig_Extension {
       public function getFunctions() {
           return [
               new \Twig_SimpleFunction('render_custom_block', [$this, 'renderCustomBlock']),
           ];
       }
   }
   

3. Event Listeners: Hook into block save events (e.g., log changes):

   // src/EventListener/BlockListener.php
   class BlockListener {
       public function onBlockSave(BlockEvents $events) {
           $block = $events->getBlock();
           // Custom logic (e.g., analytics)
       }
   }
   

Performance Notes

• Lazy Loading: Blocks are created on first edit (no pre-populated DB).
• Caching: Disable TinyMCE cache in production for consistent edits:

  <script>tinymce.init({ cache_suffix: '' });</script>