Epiceditor Bundle Laravel Package

Getting Started

Minimal Setup

1. Install via Composer:

   composer require backender/epiceditor-bundle
   

2. Enable the Bundle in AppKernel.php:

   new Backender\EpiceditorBundle\BackenderEpiceditorBundle(),
   

3. Install Assets (critical for frontend functionality):

   php bin/console assets:install web --symlink
   

4. First Use Case: Add the editor to a form field in a controller or entity type:

   $builder->add('description', 'epiceditor', [
       'clientSideStorage' => true,
       'parser' => 'marked'
   ]);
   

Where to Look First

• Default Configuration: Check config/packages/backender_epiceditor.yaml (auto-generated after installation).
• Form Integration: Focus on Form\Type\EpiceditorType for customization options.
• Asset Paths: Verify /web/bundles/backenderepiceditor/ exists post-asset install.

Implementation Patterns

Common Workflows

1. Basic Form Integration:

   // src/Form/PostType.php
   $builder->add('content', 'epiceditor', [
       'label' => 'Article Content',
       'autoSave' => 60, // Auto-save every 60 seconds
   ]);
   

2. Dynamic Configuration via Twig:

   {% form_theme form _self %}
   {% block epiceditor_widget %}
       {{ form_widget(form.content, {
           'theme': {
               'editor': '/bundles/yourtheme/editor.css'
           }
       }) }}
   {% endblock %}
   

3. Entity Field Mapping:

   # config/doctrine/Post.orm.yml
   fields:
       body:
           type: text
           column: content
           options:
               form_type: epiceditor
   

4. Custom Theming:

   • Override epiceditor.css in web/css/ and reference it in form options:

     'theme' => ['editor' => '/css/epiceditor.css']
     

Integration Tips

• Asset Management: Use asset() helper in Twig for paths:

  {{ asset('bundles/backenderepiceditor/js/epiceditor.min.js') }}
  

• LocalStorage Sync: Enable clientSideStorage for offline persistence.
• Parser Selection: Use 'parser' => 'marked' for Markdown or 'parser' => 'showdown' for alternatives.

Gotchas and Tips

Pitfalls

1. Asset Installation:

   • Forgetting assets:install causes JS/CSS 404s. Run it after every composer update.
   • Fix: Verify /web/bundles/backenderepiceditor/ exists.

2. Configuration Overrides:

   • Form-level options do not override class from config.yml. This is a silent failure.
   • Fix: Extend EpiceditorType if you need to modify the underlying class.

3. Parser Dependencies:

   • The marked parser requires marked.js (not bundled by default). Include it manually:

     {{ asset('vendor/marked/marked.min.js') }}
     

4. LocalStorage Conflicts:

   • localStorageName collisions can corrupt data if multiple editors use the same key.
   • Fix: Use unique names (e.g., localStorageName: 'post_{{ post.id }}_editor').

Debugging

• Console Errors: Check browser console for missing assets or JS errors (e.g., Uncaught ReferenceError: EpicEditor is not defined).
• Form Data: Verify submitted data is HTML-encoded (EpicEditor outputs HTML by default). Use htmlspecialchars_decode() if needed:

  $content = htmlspecialchars_decode($form->get('content')->getData());
  

Extension Points

1. Custom Parsers:

   • Extend EpiceditorType to add new parsers:

     // src/Form/Type/CustomEpiceditorType.php
     class CustomEpiceditorType extends EpiceditorType {
         public function configureOptions(OptionsResolver $resolver) {
             $resolver->setDefaults(['parser' => 'custom']);
         }
     }
     

   • Register the parser in resources/public/js/epiceditor-extensions.js:

     EpicEditor.registerParser('custom', function(markup) { ... });
     

2. Event Listeners:

   • Hook into form events to modify editor behavior:

     $form->addEventListener(FormEvents::PRE_SET_DATA, function (FormEvent $event) {
         $event->getForm()->add('content', 'epiceditor', [
             'autoSave' => $event->getData()->getAutoSaveInterval()
         ]);
     });
     

3. Twig Extensions:

   • Create a custom Twig extension to generate editor instances dynamically:

     // src/Twig/EpicEditorExtension.php
     class EpicEditorExtension extends \Twig_Extension {
         public function getFunctions() {
             return [
                 new \Twig_SimpleFunction('epic_editor', [$this, 'renderEditor']),
             ];
         }
         public function renderEditor($options = []) {
             return $this->render('BackenderEpiceditorBundle:Form:fields.html.twig', [
                 'type' => new EpiceditorType(),
                 'options' => $options,
             ]);
         }
     }
     

     Usage in Twig:

     {{ epic_editor({'theme': {'editor': '/custom.css'}}) }}