Page Bundle Laravel Package

## Getting Started

### Minimal Setup
1. **Installation**:
   ```bash
   composer require artgris/page-bundle
   php bin/console doctrine:schema:update --force

2. Configure Dependencies:

   • Add Knp\DoctrineBehaviors\DoctrineBehaviorsBundle to config/bundles.php:

     return [
         // ...
         Knp\DoctrineBehaviors\DoctrineBehaviorsBundle::class => ['all' => true],
     ];
     

   • Add locale parameter in config/services.yaml:

     parameters:
         locale: 'en'
     

3. Integrate with EasyAdmin:

   • Add ArtgrisPage to DashboardController:

     use Artgris\Bundle\PageBundle\Entity\ArtgrisPage;
     
     public function configureMenuItems(): iterable {
         yield MenuItem::linkToCrud('Page', 'fa fa-file-alt', ArtgrisPage::class);
     }
     

4. First Use Case:

   • Access the EasyAdmin dashboard, navigate to the Page CRUD, and create a new page.
   • Add a block (e.g., title) and assign it to a route (e.g., App\Controller\MainController::index).
   • Retrieve the block in Twig:

     {{ blok('title') }}
     

Implementation Patterns

Core Workflow

1. Page Management:

   • Use the EasyAdmin CRUD to create/edit pages and blocks.
   • Assign blocks to routes via the route selector in the page configuration.

2. Block Rendering:

   • Single Block:

     {{ blok('block-tag') }}  {# Retrieves a block by tag #}
     

   • All Blocks (Current Page or Unlinked):

     {% for blok in bloks() %}
         {{ blok }}
     {% endfor %}
     

   • Blocks by Page Tag:

     {% for blok in page('homepage') %}
         {{ blok }}
     {% endfor %}
     

   • Regex-Based Blocks:

     {% for blok in regex_array_blok('^sidebar-*') %}
         {{ blok }}
     {% endfor %}
     

3. Custom Form Types:

   • Extend PageFromInterface to create custom block types (e.g., TinyMCE):

     namespace App\Form;
     
     use Artgris\Bundle\PageBundle\Form\Type\PageFromInterface;
     use Symfony\Component\Form\AbstractType;
     use Symfony\Component\Form\Extension\Core\Type\TextareaType;
     
     class CustomType extends AbstractType implements PageFromInterface {
         public function getParent() { return TextareaType::class; }
         public static function getRenderType($value) { return $value . '<hr>'; }
     }
     

   • Register the type in config/packages/artgris_page.yaml:

     artgris_page:
         types:
             - custom: 'App\Form\CustomType'
     

4. Translation Support:

   • Configure a2lix_translation_form in config/packages/a2lix_translation_form.yaml:

     a2lix_translation_form:
         locales: [fr, en]
         default_locale: fr
     

5. Debugging:

   • Use the Debug Bar to inspect blocks and copy-paste Twig snippets.

Integration Tips

• EasyAdmin Assets: Add JavaScript/CSS for custom form types (e.g., TinyMCE) in DashboardController:

  public function configureAssets(): Assets {
      return Assets::new()
          ->addJsFile('js/tinymce5/tinymce.min.js');
  }
  

• Caching:

  • Blocks linked to the current route or unlinked blocks are cached after the first call to bloks() or blok().
  • Use page() or regex functions sparingly (they bypass cache and query the DB each time).

• Data Export/Import:

  • Export the current model to YAML:

    php bin/console artgris:page:export
    

  • Import a YAML file:

    php bin/console artgris:page:import
    

  • Clean up deviant data (e.g., mismatched types):

    php bin/console artgris:page:import --remove-deviants
    

Gotchas and Tips

Pitfalls

1. Route Selector Misconfiguration:

   • If hide_route_form: true is set in artgris_page.yaml, blocks won’t be linked to routes. Use this only for single-page sites.

2. Cache Invalidation:

   • Cached blocks (via bloks() or blok()) are not updated until the cache is cleared or the page is refreshed.
   • Avoid relying on page() or regex functions for dynamic content if performance is critical.

3. Translation Quirks:

   • Ensure a2lix_translation_form is properly configured. Missing locales may cause errors when editing translatable blocks.

4. Doctrine Behaviors:

   • Forgetting to add Knp\DoctrineBehaviorsBundle to bundles.php will break the schema update and block functionality.

5. Custom Type Rendering:

   • Override getRenderType() in custom form types to control how blocks are rendered. Forgetting this may result in raw data being output.

Debugging Tips

1. Debug Bar:

   • Use the PageBundle Debug Bar to inspect available blocks and their tags. Click the "copy" button to quickly generate Twig code.

2. Database Schema:

   • Run php bin/console doctrine:schema:update --dump-sql to verify schema changes after installation.

3. YAML Import Errors:

   • Use --ignore-names to skip name mismatches during import:

     php bin/console artgris:page:import --ignore-names
     

   • Use --remove-deviants to delete blocks with mismatched types:

     php bin/console artgris:page:import --remove-deviants
     

4. EasyAdmin Compatibility:

   • Ensure your EasyAdminBundle version is compatible (e.g., ^4.0 for PageBundle 4.x). Check the release notes.

Extension Points

1. Custom Block Types:

   • Implement PageFromInterface to create reusable block types (e.g., rich text editors, custom inputs).

2. Override Twig Functions:

   • Extend the bundle’s Twig environment to add custom logic for block retrieval or rendering.

3. Event Listeners:

   • Listen to artgris.page.pre_save or artgris.page.post_save events to modify page/block data before/after saving.

4. Form Themes:

   • Customize the EasyAdmin form theme for pages/blocks by overriding the artgris_page template in your project’s templates/ directory.

5. Validation:

   • Add validation constraints to custom block types using Symfony’s validator component.

---