Trumbowyg Bundle Laravel Package

Getting Started

Minimal Setup

1. Install the Bundle

   composer require alexdw/trumbowyg-bundle
   

2. Enable the Bundle Add to config/bundles.php (Symfony 4+) or AppKernel.php (Symfony 2/3):

   Alexdw\TrumbowygBundle\AlexdwTrumbowygBundle::class => ['all' => true],
   

3. Install Assets

   php bin/console assets:install public
   

4. Include in Twig Add to your base template (e.g., base.html.twig):

   {{ trumbowyg_js() }}
   {{ trumbowyg_css() }}
   

First Use Case: Basic Form Integration

Add a Trumbowyg field to a form type:

use Alexdw\TrumbowygBundle\Form\Type\TrumbowygType;

$builder->add('content', TrumbowygType::class, [
    'label' => 'Article Content',
    'attr' => ['class' => 'editor-full-width'],
]);

Implementation Patterns

1. Form Integration

• Default Configuration: Use the bundle’s defaults for quick setup.
• Custom Options: Override defaults via YAML (config/packages/alexdw_trumbowyg.yaml):

  alexdw_trumbowyg:
      btns:
          - ["bold", "italic"]
          - ["insertImage"]
  

• Dynamic Options: Pass options directly in the form type:

  $builder->add('content', TrumbowygType::class, [
      'btns' => [["bold"], ["link"]],
      'autogrow' => true,
  ]);
  

2. Asset Management

• Override Assets: Copy bundle assets (e.g., vendor/alexdw/trumbowyg-bundle/Resources/public/) to public/bundles/alexdwtrumbowyg/ and customize.
• Lazy Loading: Use {{ trumbowyg_js({'include_jquery': false}) }} if jQuery is already loaded.

3. Twig Extensions

• Conditional Loading: Load assets only on specific pages:

  {% if app.request.attributes.get('_route') == 'admin_article_edit' %}
      {{ trumbowyg_js() }}
  {% endif %}
  

4. API Integration

• Fetch Content: Access raw HTML via form data:

  $content = $form->get('content')->getData(); // Returns HTML string
  

• Sanitization: Use Symfony’s HtmlPurger or DOMPurify to sanitize output before saving to DB.

5. Advanced Features

• Custom Plugins: Extend Trumbowyg by adding custom buttons or plugins via JavaScript:

  {{ trumbowyg_js({
      'btns': [['customButton']],
      'plugins': {'customPlugin': '/path/to/plugin.js'}
  }) }}
  

• Language Switching: Dynamically set language via Twig:

  {{ trumbowyg_js({'language': app.request.locale }) }}
  

Gotchas and Tips

Pitfalls

1. Asset Paths:

   • If assets fail to load, verify base_path in config matches your assets:install output.
   • For Symfony 4+, ensure public/ is the web root (not public/index.php).

2. jQuery Dependency:

   • If include_jquery: true conflicts with existing jQuery, set it to false and ensure jQuery is loaded first.

3. Form Theming:

   • Override the form theme (templates/form/trumbowyg_widget.html.twig) to customize the wrapper or add classes.

4. CSRF Tokens:

   • Trumbowyg’s AJAX features may break if CSRF tokens are missing. Ensure {{ csrf_token() }} is included in forms.

5. Database Storage:

   • HTML content may bloat your database. Consider:
     • Storing as text and compressing.
     • Using a dedicated table for rich content.

Debugging Tips

• Check Console Errors: Verify assets are loaded correctly (404s for JS/CSS).
• Inspect Network Requests: Confirm Trumbowyg’s JS/CSS paths are correct.
• Disable Plugins: Temporarily remove custom plugins to isolate issues.

Extension Points

1. Custom Buttons: Add a button via JavaScript:

   {{ trumbowyg_js({
       'btns': [['customButton']]
   }) }}
   

   Then define the button in a separate JS file:

   $.extend(true, $.trumbowyg.svgPath, '/bundles/alexdwtrumbowyg/ui/');
   $.trumbowyg.btns.push({
       xtag: 'customButton',
       fn: function() { /* Logic */ }
   });
   

2. Event Listeners: Hook into Trumbowyg events (e.g., tbwChange) via JavaScript:

   {{ trumbowyg_js() }}
   <script>
       $('#my-editor').on('tbwChange', function() {
           console.log('Content changed!');
       });
   </script>
   

3. Configuration Overrides: Override bundle config in config/packages/alexdw_trumbowyg.yaml:

   alexdw_trumbowyg:
       btns:
           - ["bold", "italic", "strikethrough"]
       autogrow: true
   

4. Symfony 5+ Flex Compatibility: If using Symfony Flex, manually register the bundle in config/bundles.php (Flex may not auto-discover it).

Pro Tips

• Use with API Platform: Leverage Trumbowyg for rich-text fields in API-driven apps by serializing HTML.
• Pair with CKEditor: Offer users a choice between editors by conditionally loading assets.
• Localization: Override the language config for multilingual support (e.g., language: '{{ app.request.locale }}').