Page Bundle Laravel Package

Getting Started

Minimal Steps

1. Installation:

   composer require aropixel/page-bundle
   

   Ensure aropixel/admin-bundle is already installed.

2. Configure Routes: Add to config/routes.yaml:

   aropixel_page:
       resource: "@AropixelPageBundle/src/Resources/config/routes.yaml"
       prefix: /admin/page
   

3. Create Custom Entities: Extend the base entities in src/Entity/Page.php and src/Entity/PageTranslation.php.

4. Run Migrations:

   php bin/console make:migration
   php bin/console doctrine:migrations:migrate
   

5. First Use Case: Create a page via the admin interface (/admin/page). Use TYPE_DEFAULT for simple HTML content or TYPE_CUSTOM for the visual builder.

Implementation Patterns

Core Workflows

1. Page Creation & Management:

   • Use the admin interface (/admin/page) to create pages of type TYPE_DEFAULT (CKEditor) or TYPE_CUSTOM (visual builder).
   • For TYPE_CUSTOM, the JSON payload is pre-rendered to HTML at save time, stored in htmlContent, and displayed with {{ page.htmlContent|raw }} in Twig.

2. Fixed Pages:

   • Define system pages (e.g., homepage) using the #[AsFixedPage] attribute:

     #[AsFixedPage(code: 'homepage', title: 'Home')]
     class HomepageFixedPage {}
     

   • Sync with the database:

     php bin/console aropixel:page:sync-fixed
     

   • Retrieve fixed pages via staticCode:

     $page = $pageRepository->findOneBy(['staticCode' => 'homepage']);
     

3. Custom JSON Page Types:

   • Extend AbstractJsonPageType for structured forms (e.g., contact pages):

     class ContactPageType extends AbstractJsonPageType {
         protected function buildCustomForm(FormBuilderInterface $builder, array $options): void {
             $builder->add('phone', TextType::class);
         }
         public function getType(): string { return 'contact'; }
     }
     

   • Override Twig templates in templates/bundles/AropixelPageBundle/{type}/form.html.twig.

4. Multilingual Support:

   • Configure locales in aropixel_admin.translations.locales (AdminBundle).
   • Use the locale switcher in the page builder to sync structural changes across locales.

5. Front-End Integration:

   • Render pages in Twig:

     {{ page.htmlContent|raw }}
     

   • Fetch pages by slug or ID in controllers:

     $page = $pageRepository->findOneBy(['slug' => 'about']);
     

Integration Tips

• Events: Listen to PageSavedEvent to invalidate caches (Varnish, Redis) after page updates:

  use Aropixel\PageBundle\Event\PageSavedEvent;
  use Symfony\Component\EventDispatcher\Attribute\AsEventListener;
  
  #[AsEventListener(event: PageSavedEvent::class, method: 'onPageSaved')]
  public function onPageSaved(PageSavedEvent $event): void {
      // Invalidate cache logic
  }
  

• Custom Blocks: Extend the visual builder with custom blocks (see custom-blocks.md).

• SEO: Leverage metaTitle, metaDescription, and slug fields per locale for SEO optimization.

Gotchas and Tips

Pitfalls

1. Entity Configuration:

   • Forgetting to update config/packages/aropixel_page.yaml with custom entity classes after extending the base entities will cause Doctrine errors.
   • Fix: Ensure the config includes:

     aropixel_page:
         entities:
             Aropixel\PageBundle\Entity\PageInterface: App\Entity\Page
             Aropixel\PageBundle\Entity\PageTranslationInterface: App\Entity\PageTranslation
     

2. Fixed Pages Sync:

   • Running aropixel:page:sync-fixed without defining #[AsFixedPage] classes will create no fixed pages.
   • Fix: Verify classes are autoloaded (e.g., in src/).

3. Page Builder Styling:

   • Empty title_styles or button_colors in aropixel_page.yaml hides the corresponding selectors in the builder.
   • Fix: Explicitly define styles/colors even if empty to show the UI:

     title_styles: []
     button_colors: []
     

4. Multilingual Slugs:

   • Translated slugs must be unique per locale but can conflict across locales (e.g., /en/about and /fr/about).
   • Fix: Validate slugs in your application logic or use a slug generator that appends locale prefixes.

5. JavaScript Assets:

   • Modifying files in assets/ requires rebuilding with npm run build before committing.
   • Fix: Always run the build step after JS changes and commit both assets/ and src/Resources/public/js/.

Debugging

• Pre-Rendered HTML Issues:

  • If htmlContent is empty or incorrect, check the jsonContent for malformed JSON or unsupported blocks.
  • Debug: Temporarily log jsonContent in a PageSavedEvent listener to inspect the payload.

• Fixed Pages Not Syncing:

  • Ensure #[AsFixedPage] classes are in a directory covered by Symfony’s autodiscovery (e.g., src/).
  • Debug: Run php bin/console debug:autowiring to verify the classes are loaded.

• Custom Block Not Loading:

  • Verify the block’s JavaScript registration matches the YAML config (e.g., block IDs must align).
  • Debug: Check browser console for 404 errors on JS assets or missing block definitions.

Extension Points

1. Custom Page Types:

   • Override AbstractJsonPageType to create reusable page structures (e.g., "Product Page," "Blog Post").

2. Block Extensions:

   • Add custom blocks by extending the builder’s JavaScript API and registering them in YAML (see custom-blocks.md).

3. Event Listeners:

   • Extend functionality via PageSavedEvent, PageDeletedEvent, or PagePublishedEvent (e.g., for analytics or notifications).

4. Twig Overrides:

   • Customize the admin interface by overriding Twig templates in templates/bundles/AropixelPageBundle/.

5. Configuration:

   • Dynamically configure title_styles or button_colors via services or commands (e.g., fetch styles from a database).