N1Ed Editor Bundle Laravel Package

Getting Started

Minimal Setup

1. Install the Bundle Add the package via Composer:

   composer require brandcodenl/n1ed-editor-bundle
   

   Enable the bundle in config/bundles.php:

   return [
       // ...
       BrandcodeNL\N1EDEditorBundle\BrandcodeNLN1EDEditorBundle::class => ['all' => true],
   ];
   

2. Configure the Bundle Add the required configuration to .env:

   N1ED_API_KEY=your_api_key_here
   

   Define the bundle configuration in config/packages/brandcodenl_n1editor.yaml:

   brandcode_nln1ed_editor:
       includeEditor: true
       apiKey: '%env(resolve:N1ED_API_KEY)%'
       config:
           framework: "bootstrap4"
           ui:
               iframePopUp: true
   

3. First Use Case: Basic Form Integration Use the N1EDType in a Symfony form:

   use BrandcodeNL\N1EDEditorBundle\Form\Type\N1EDType;
   
   $builder->add('content', N1EDType::class, [
       'label' => 'Rich Text Content',
       'required' => false,
   ]);
   

   Render the form in a Twig template:

   {{ form_row(form.content) }}
   

Implementation Patterns

Workflow: Editor Integration in Forms

1. Form Definition Extend the N1EDType in your form builder for customization:

   $builder->add('description', N1EDType::class, [
       'config' => [
           'ui' => [
               'iframePopUp' => false,
               'activateBootstrapEditorOnFullScreen' => true,
           ],
       ],
   ]);
   

2. Dynamic Configuration Override bundle config per form or entity using pre_set_data or pre_bind:

   public function buildForm(FormBuilderInterface $builder, array $options)
   {
       $builder->addEventListener(FormEvents::PRE_SET_DATA, function (FormEvent $event) {
           $data = $event->getData();
           $form = $event->getForm();
   
           $form->add('content', N1EDType::class, [
               'config' => $data->getEditorConfig() ?? [],
           ]);
       });
   }
   

3. Validation and Processing Handle submitted data in your controller:

   public function saveAction(Request $request, YourEntity $entity)
   {
       $form = $this->createForm(YourFormType::class, $entity);
       $form->handleRequest($request);
   
       if ($form->isSubmitted() && $form->isValid()) {
           $content = $form->get('content')->getData(); // Raw HTML or JSON
           // Process/save $content
       }
   }
   

4. Twig Integration Customize the editor rendering in Twig by extending the block:

   {# templates/brandcodenl_n1editor/n1ed_widget.html.twig #}
   {% block n1ed_widget %}
       {{ parent() }}
       <script>
           // Custom JS logic for the editor
       </script>
   {% endblock %}
   

Gotchas and Tips

Pitfalls

1. API Key Validation

   • The bundle does not validate the N1ED_API_KEY on startup. Ensure the key is correct in .env or the editor will fail silently.
   • Test the key via the N1ED API docs before integration.

2. CSS/JS Conflicts

   • If includeCssToGlobalDoc: true is set, the bundle injects CSS globally. This may conflict with other front-end assets.
   • Fix: Set includeCssToGlobalDoc: false and manually include build/app.css in your base template.

3. Deprecated Configuration

   • The rootContains: 'rows' option is undocumented and may break if N1ED updates its structure.
   • Tip: Use the default config unless you have a specific need for this setting.

4. Form Theme Overrides

   • The bundle uses Twig templates in templates/brandcodenl_n1editor/. Overriding these requires clearing the cache:

     php bin/console cache:clear
     

5. Editor Initialization Race Conditions

   • If the editor fails to load, check:
     • The includeEditor: true flag is set.
     • No JavaScript errors block the editor initialization (inspect browser console).
     • The apiKey is correctly resolved from .env.

Debugging Tips

1. Enable Debug Mode Set includeEditor: false in development to bypass the editor and test form submission:

   brandcode_nln1ed_editor:
       includeEditor: false  # Debug mode
   

2. Log Submitted Data Dump the raw editor output in your controller to verify data structure:

   dump($form->get('content')->getData());
   

   Expected output: HTML string or JSON (depends on N1ED config).

3. Check Network Requests

   • Open DevTools (F12) and verify the editor’s API calls to https://n1ed.com/api/.
   • Ensure no CORS or firewall blocks are interfering.

Extension Points

1. Custom Editor Config Dynamically pass config per field:

   $builder->add('bio', N1EDType::class, [
       'config' => [
           'ui' => [
               'toolbar' => ['bold', 'italic', 'insertImage'], // Custom toolbar
           ],
       ],
   ]);
   

2. Event Listeners Attach listeners to the form for pre/post-processing:

   $builder->addEventListener(FormEvents::SUBMIT, function (FormEvent $event) {
       $data = $event->getData();
       // Sanitize or transform $data before submission
   });
   

3. Asset Management Override the default CSS/JS paths in config:

   brandcode_nln1ed_editor:
       config:
           include:
               css:
                   - 'path/to/custom.css'
               js:
                   - 'path/to/custom.js'