Jquery Ui Bundle Laravel Package

Getting Started

Minimal Steps

1. Installation:

   composer require bmatzner/jquery-ui-bundle
   

   Add the bundle to app/AppKernel.php under $bundles.

2. Asset Installation:

   php app/console assets:install web --symlink
   

   (Replace web with your public directory if different.)

3. First Use Case: Include jQuery UI in a Twig template:

   {# app/Resources/views/base.html.twig #}
   <link rel="stylesheet" href="{{ asset('bundles/bmatznerjqueryui/css/smoothness/jquery-ui.css') }}">
   <link rel="stylesheet" href="{{ asset('bundles/bmatznerjqueryui/css/smoothness/jquery.ui.theme.css') }}">
   <script src="{{ asset('bundles/bmatznerjquery/js/jquery.min.js') }}"></script>
   <script src="{{ asset('bundles/bmatznerjqueryui/js/minified/jquery-ui.min.js') }}"></script>
   

   Initialize a widget (e.g., datepicker) in a JS file:

   $(document).ready(function() {
       $("#datepicker").datepicker();
   });
   

Implementation Patterns

Common Workflows

1. Theming:

   • Use the included themes (smoothness, redmond, etc.) or add custom themes by placing CSS files in web/bundles/bmatznerjqueryui/css/.
   • Example for custom theme:

     <link rel="stylesheet" href="{{ asset('bundles/bmatznerjqueryui/css/custom-theme/jquery-ui.css') }}">
     

2. Lazy Loading:

   • Load jQuery UI only where needed (e.g., for a specific page or modal) using Twig conditions:

     {% if is_granted('ROLE_ADMIN') %}
         <script src="{{ asset('bundles/bmatznerjqueryui/js/minified/jquery-ui.min.js') }}"></script>
     {% endif %}
     

3. Widget Initialization:

   • Initialize widgets in separate JS files (e.g., app/Resources/public/js/jquery-ui-init.js) and include them conditionally:

     // app/Resources/public/js/jquery-ui-init.js
     $(document).ready(function() {
         $("#sortable-list").sortable();
         $("#draggable-item").draggable();
     });
     

     <script src="{{ asset('js/jquery-ui-init.js') }}"></script>
     

4. Symfony Forms Integration:

   • Use jQuery UI widgets with Symfony forms by targeting form fields:

     {{ form_widget(form.dateField, {'attr': {'class': 'datepicker'}}) }}
     

     $(document).ready(function() {
         $(".datepicker").datepicker();
     });
     

5. Asset Versioning:

   • Append a version query string to assets for cache busting:

     <script src="{{ asset('bundles/bmatznerjqueryui/js/minified/jquery-ui.min.js?v=' ~ '1.10.3') }}"></script>
     

Gotchas and Tips

Pitfalls

1. Asset Paths:

   • The bundle assumes assets are installed in web/bundles/. If using a custom public directory (e.g., public/), update the paths in Twig or reconfigure assets:install.
   • Fix: Verify paths with {{ asset('bundles/bmatznerjqueryui/...') }} and adjust if needed.

2. jQuery Dependency:

   • The bundle includes jQuery, but conflicts may arise if another bundle (e.g., symfony/webpack-encore) also loads jQuery.
   • Fix: Exclude jQuery from other bundles or use noConflict():

     var jQueryUI = $.noConflict(true);
     jQueryUI(document).ready(function() { ... });
     

3. Theme Overrides:

   • Custom themes must be manually placed in web/bundles/bmatznerjqueryui/css/ and referenced correctly. The bundle does not auto-detect custom themes.
   • Fix: Ensure theme CSS files follow the same structure as default themes (e.g., jquery-ui.css + jquery.ui.theme.css).

4. Outdated Version:

   • The bundle ships with jQuery UI v1.10.3 (released in 2013), which may lack modern features or security updates.
   • Workaround: Override assets by copying files from a newer jQuery UI release to web/bundles/bmatznerjqueryui/ and update references.

5. Asset Installation:

   • Running assets:install without --symlink copies files, which can bloat your project. Symlinks are preferred for development.
   • Tip: Use --symlink in development and switch to copies for production if needed.

Debugging Tips

1. Check Asset Paths:

   • Verify assets are installed correctly by inspecting the generated HTML paths. Missing assets will 404.

2. Console Errors:

   • If jQuery UI widgets fail to initialize, check the browser console for errors like:
     • $ is not defined → jQuery not loaded.
     • Cannot read property 'datepicker' of undefined → jQuery UI not loaded or initialized after DOM ready.

3. Conflict Detection:

   • Use console.log($.fn.jquery) to verify jQuery version and console.log($.ui.version) to check jQuery UI version.

Extension Points

1. Custom Widgets:

   • Extend functionality by including additional jQuery UI widgets (e.g., jquery-ui.timepicker.js) in web/bundles/bmatznerjqueryui/js/.

2. Twig Extensions:

   • Create a custom Twig extension to simplify asset inclusion:

     // src/Twig/AppExtension.php
     class AppExtension extends \Twig_Extension
     {
         public function getFunctions()
         {
             return [
                 new \Twig_SimpleFunction('jquery_ui_asset', [$this, 'getAssetPath']),
             ];
         }
     
         public function getAssetPath($path)
         {
             return $this->env->getExtension('asset')->getUrl('bundles/bmatznerjqueryui/' . $path);
         }
     }
     

     Usage in Twig:

     <link rel="stylesheet" href="{{ jquery_ui_asset('css/smoothness/jquery-ui.css') }}">
     

3. Configuration:

   • Override default settings (e.g., theme) via config.yml:

     bmatzner_jquery_ui:
         theme: 'custom-theme'
     

     (Note: Requires extending the bundle or patching the template logic.)

4. Webpack Encore Integration:

   • For modern projects, replace the bundle’s assets with Webpack Encore:

     // webpack.config.js
     Encore
         .addEntry('jquery-ui', './vendor/bmatzner/jquery-ui-bundle/Resources/public/js/jquery-ui.min.js')
         .copyFiles({
             from: './vendor/bmatzner/jquery-ui-bundle/Resources/public/css/smoothness',
             to: 'css/[path][name].[ext]',
         });