Sir Trevor Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require edsi-tech/sir-trevor-bundle
   

   Register the bundle in app/AppKernel.php:

   new EdsiTech\SirTrevorBundle\EdsiTechSirTrevorBundle(),
   

2. Define a Block Entity: Extend AbstractBlock and map it to Doctrine:

   use EdsiTech\SirTrevorBundle\Entity\AbstractBlock;
   use Doctrine\ORM\Mapping as ORM;
   
   /**
    * @ORM\Entity
    * @ORM\Table(name="my_custom_block")
    */
   class MyCustomBlock extends AbstractBlock
   {
       // Add custom fields as needed
   }
   

3. First Render: Pass a collection of blocks to Twig:

   {% set blocks = app.doctrine.orm.entity_manager.getRepository('AppBundle:MyCustomBlock').findAll() %}
   {{ cms_render(blocks) }}
   

First Use Case

Create a simple page with editable blocks:

1. Define a Page entity with a OneToMany relation to MyCustomBlock.
2. Render the page with editable blocks:

   {% set page = app.doctrine.orm.entity_manager.getRepository('AppBundle:Page').find(1) %}
   {{ cms_render(page.blocks, { is_editable: true }) }}
   

Implementation Patterns

Block Mapping

1. Entity Design:

   • Extend AbstractBlock for each block type (e.g., TextBlock, ImageBlock).
   • Use @ORM\Table and @ORM\Column annotations for custom fields.
   • Example:

     /**
      * @ORM\Column(type="string", nullable=true)
      * @var string
      */
     private $customField;
     

2. Block Types:

   • Map JavaScript SirTrevor block types to Doctrine entities via getType() in AbstractBlock:

     public function getType()
     {
         return 'my_custom_type';
     }
     

Twig Integration

1. Rendering:

   • Use cms_render() in Twig with optional is_editable:

     {{ cms_render(blocks, { is_editable: true, theme: 'MyBundle:Render:custom_theme.html.twig' }) }}
     

   • Pass additional options like config (SirTrevor config) or assets (custom JS/CSS).

2. Theming:

   • Override the default theme (_blocks_theme.html.twig) by:
     • Creating a template at Resources/views/Render/blocks_theme.html.twig.
     • Configuring the bundle:

       edsi_tech_sir_trevor:
           theme: 'MyBundle:Render:custom_theme.html.twig'
       

Workflows

1. CRUD Operations:

   • Use Doctrine repositories to manage blocks (e.g., findBy, findOneBy).
   • Example:

     $blocks = $entityManager->getRepository(MyCustomBlock::class)->findBy(['page' => $page]);
     

2. Dynamic Block Loading:

   • Fetch blocks dynamically in a controller and pass them to Twig:

     public function showAction(Page $page)
     {
         return $this->render('page/show.html.twig', [
             'blocks' => $page->getBlocks(),
             'is_editable' => $this->getUser()->hasRole('ROLE_EDITOR'),
         ]);
     }
     

3. Asset Management:

   • Register custom assets (JS/CSS) via the bundle config:

     edsi_tech_sir_trevor:
         assets:
             js: ['/bundles/mybundle/js/custom.js']
             css: ['/bundles/mybundle/css/custom.css']
     

Gotchas and Tips

Pitfalls

1. Block Type Mismatch:

   • Ensure getType() in AbstractBlock matches the SirTrevor JS block type. Mismatches cause rendering issues.
   • Debug: Check browser console for SirTrevor errors if blocks fail to load.

2. Twig Template Overrides:

   • Overriding _blocks_theme.html.twig requires the template to extend the base template:

     {% extends 'EdsiTechSirTrevorBundle:Render:_blocks_theme.html.twig' %}
     

   • Forgetting this causes the template to render incorrectly.

3. Doctrine Annotations:

   • AbstractBlock already includes basic annotations (id, type, content). Adding redundant annotations (e.g., @ORM\Id) may cause conflicts.

4. Editable Mode:

   • is_editable: true requires SirTrevor JS to be loaded. Ensure the bundle’s assets are included in your base template or layout.

Debugging

1. Console Errors:

   • Check for SirTrevor or EdsiTechSirTrevorBundle errors in the browser console. Common issues:
     • Missing JS/CSS assets.
     • Invalid block types.
     • Doctrine entity mapping errors.

2. Symfony Profiler:

   • Use the profiler to inspect Doctrine queries and block collections passed to Twig.

3. Log Block Data:

   • Temporarily log block data in a controller to verify entity hydration:

     foreach ($blocks as $block) {
         $this->get('logger')->info('Block type: ' . $block->getType());
     }
     

Tips

1. Custom Block Fields:

   • Use accessors/mutators to handle custom fields in AbstractBlock:

     public function getCustomField()
     {
         return $this->customField;
     }
     
     public function setCustomField($value)
     {
         $this->customField = $value;
         return $this;
     }
     

2. SirTrevor Configuration:

   • Pass custom SirTrevor config via Twig:

     {{ cms_render(blocks, {
         is_editable: true,
         config: {
             'someOption': true,
             'anotherOption': 'value'
         }
     }) }}
     

3. Performance:

   • Lazy-load blocks for pages with many blocks:

     $blocks = $entityManager->getRepository(MyCustomBlock::class)
         ->createQueryBuilder('b')
         ->where('b.page = :page')
         ->setParameter('page', $page)
         ->getQuery()
         ->getResult();
     

4. Testing:

   • Test block rendering in isolation using PHPUnit:

     public function testBlockRendering()
     {
         $block = new MyCustomBlock();
         $block->setType('test_type');
         $block->setContent('<p>Test</p>');
     
         $twig = $this->get('twig');
         $html = $twig->render('EdsiTechSirTrevorBundle:Render:_blocks_theme.html.twig', [
             'blocks' => [$block],
             'is_editable' => false,
         ]);
     
         $this->assertStringContainsString('<p>Test</p>', $html);
     }
     

5. Extending the Bundle:

   • Override bundle services or templates by creating a custom bundle that extends EdsiTechSirTrevorBundle.
   • Example services.yml:

     services:
         my_custom.block_type:
             class: AppBundle\Entity\MyCustomBlock
             tags:
                 - { name: edsi_tech_sir_trevor.block_type }