Cws Quilljs Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require creative-web-solution/cws-quilljs-bundle
   

2. Enable Bundle: Add to config/bundles.php:

   Cws\Bundle\QuillJsBundle\CwsQuillJsBundle::class => ['all' => true],
   

3. Basic Configuration: Create config/packages/cws_quill_js.yaml:

   cws_quill_js:
       enabled: true
       toolbar:
           - ['bold', 'italic']
   

4. First Use Case: In a Symfony form type, inject the QuillJsType:

   use Cws\Bundle\QuillJsBundle\Form\Type\QuillJsType;
   
   $builder->add('content', QuillJsType::class);
   

   Render the form in a Twig template. The bundle auto-loads QuillJS assets.

Implementation Patterns

Form Integration

• Field Mapping: Use QuillJsType for any textarea field requiring rich text:

  $builder->add('description', QuillJsType::class, [
      'toolbar_config' => [
          ['bold', 'italic', 'underline'],
          ['link', 'image']
      ]
  ]);
  

• Dynamic Toolbars: Override toolbar config per field:

  # config/packages/cws_quill_js.yaml
  cws_quill_js:
      default_toolbar: ['bold', 'italic']
      field_specific:
          article_content: [['bold', 'italic', 'link'], ['clean']]
  

  Then reference in form:

  $builder->add('article_content', QuillJsType::class, ['field_name' => 'article_content']);
  

Asset Management

• Auto-Loading: The bundle registers QuillJS and dependencies (quill, quill.snow) via Symfony’s asset mapper. No manual <script> tags needed.
• Custom Themes: Extend the default theme by overriding the bundle’s Twig templates (templates/bundles/cwsquilljs/).

Validation & Data Handling

• Sanitization: Quill outputs HTML. Sanitize before saving:

  use Symfony\Component\DomCrawler\Crawler;
  
  $html = $form->get('content')->getData();
  $crawler = new Crawler($html);
  $sanitized = $crawler->html(); // Basic sanitization
  

• Delta Format: For advanced use, access Quill’s delta format via JavaScript:

  const quill = document.querySelector('.ql-editor').closest('.quill').quill;
  const delta = quill.getContents(); // Raw delta format
  

Twig Integration

• Embedding Editors: Use the quill_js_editor Twig function to render standalone editors:

  {{ quill_js_editor({
      'id': 'custom-editor',
      'toolbar': [['bold'], ['italic']],
      'value': old_content
  }) }}
  

Gotchas and Tips

Pitfalls

• Asset Pipeline Conflicts: If using Webpack Encore, ensure QuillJS isn’t duplicated. Exclude the bundle’s assets:

  // webpack.config.js
  Encore.enableSingleRuntimeChunk()
    .disableSingleRuntimeChunk()
    .configureBabel(() => { /* ... */ })
    .copyFiles({
      from: './vendor/creative-web-solution/cws-quilljs-bundle/public',
      to: 'bundles/cwsquilljs/[path][name].[ext]',
      pattern: /\.(js|css)$/
    });
  

• CSRF with AJAX: Quill’s AJAX saves may fail due to missing CSRF tokens. Use Symfony’s csrf_token helper in JavaScript:

  const token = document.querySelector('meta[name="csrf-token"]').content;
  fetch('/save', {
    method: 'POST',
    headers: { 'X-CSRF-Token': token },
    body: JSON.stringify({ content: quill.getContents() })
  });
  

• Configuration Overrides: Field-specific configs in field_specific must match the form field name exactly (case-sensitive).

Debugging

• Console Errors: Check for quill is not defined if assets fail to load. Verify:
  • app/design/config/bundles.php includes the bundle.
  • No typos in cws_quill_js.yaml.
  • Clear cache: php bin/console cache:clear.
• Toolbar Not Rendering: Ensure the toolbar config is a nested array (e.g., [['bold'], ['italic']]), not a flat array.

Extension Points

• Custom Modules: Register Quill modules globally via config:

  cws_quill_js:
      modules:
          syntax: true
          mentions:
              endpoint: '/api/mentions'
  

  Then use in Twig:

  {{ quill_js_editor({
      'modules': ['syntax', 'mentions']
  }) }}
  

• Event Listeners: Subscribe to Quill events via JavaScript:

  document.querySelector('.ql-editor').addEventListener('blur', (e) => {
    const content = e.target.closest('.ql-container').querySelector('.ql-editor').innerHTML;
    // Trigger Symfony event or AJAX save
  });
  

• Override Templates: Copy vendor/creative-web-solution/cws-quilljs-bundle/templates/ to templates/bundles/cwsquilljs/ to customize editor behavior.

Performance Tips

• Lazy Loading: Disable Quill for non-critical forms:

  cws_quill_js:
      enabled: false  # Disable globally
  

  Then enable per field:

  $builder->add('content', QuillJsType::class, ['enabled' => true]);
  

• Minify Assets: Use Symfony’s asset mapper to auto-minify:

  # config/packages/asset_mapper.yaml
  framework:
      assets:
          version_strategy: hash