Jquery Laravel Package

Getting Started

Minimal Setup

1. Installation Add the package via Composer:

   composer require contao-components/jquery
   

   Publish the assets (if needed) via:

   php artisan vendor:publish --tag=contao-components.jquery
   

2. Basic Usage Include jQuery in your Blade template:

   @jquery
   

   This will output the jQuery script tag with the correct version (default: latest stable).

3. First Use Case Use jQuery in a simple DOM manipulation task:

   $(document).ready(function() {
       $('#example-button').click(function() {
           alert('Button clicked!');
       });
   });
   

   Ensure your script is loaded after jQuery:

   @jquery
   @scripts
   

Implementation Patterns

Workflow Integration

1. Asset Management

   • Use @jquery in your Blade layouts to ensure jQuery is loaded globally.
   • For project-specific scripts, place them in resources/js/ and compile with Laravel Mix or Vite.

2. Version Control Override the default jQuery version in config/contao-components/jquery.php:

   'version' => '3.6.0', // Example: Pin to a specific version
   

3. Conditional Loading Load jQuery only on specific routes or views:

   @if(Request::is('admin/*'))
       @jquery
   @endif
   

4. Integration with Frontend Frameworks

   • If using Vue/React, load jQuery via @jquery in your root layout and ensure no conflicts with $ by using jQuery in no-conflict mode:

     jQuery(document).ready(function($) {
         // Use $ safely here
     });
     

5. Laravel Mix/Vite Setup

   • If using Laravel Mix, ensure jQuery is included in your webpack.mix.js:

     mix.js('resources/js/app.js', 'public/js')
         .jquery(); // Optional: If using Laravel Mix's built-in jQuery loader
     

   • For Vite, manually include jQuery in your main.js:

     import $ from 'jquery';
     

Gotchas and Tips

Pitfalls

1. Duplicate Scripts

   • Avoid loading jQuery multiple times. Use @jquery once in your layout and avoid manual <script> tags for jQuery.
   • Check for conflicts with other packages (e.g., Bootstrap JS, which depends on jQuery).

2. Version Mismatches

   • If using third-party plugins, ensure their required jQuery version matches the one loaded by this package. Debug with:

     console.log(jQuery.fn.jquery); // Check loaded version
     

3. No-Conflict Mode

   • Some frameworks (e.g., Vue) may conflict with jQuery’s $ alias. Use no-conflict mode:

     var jQuerySafe = $.noConflict();
     jQuerySafe(document).ready(function() {
         // Use jQuerySafe instead of $
     });
     

4. Asset Compilation Issues

   • If using Laravel Mix/Vite, ensure jQuery is not being bundled twice. Exclude it from your entry file if already loaded via @jquery.

Debugging Tips

1. Check Loaded Scripts Inspect the <head> or <body> of your rendered page to confirm jQuery is loaded:

   <script src="https://code.jquery.com/jquery-3.x.x.min.js"></script>
   

2. Console Errors

   • If jQuery functions fail, check the browser console for errors like:

     $ is not defined
     

     This indicates jQuery wasn’t loaded or was overridden.

3. Clear Cached Views After publishing config or assets, clear Laravel’s view cache:

   php artisan view:clear
   

Extension Points

1. Custom CDN or Local Path Override the jQuery source in config/contao-components/jquery.php:

   'source' => [
       'cdn' => 'https://your-cdn.com/jquery.min.js',
       'local' => 'path/to/local/jquery.min.js',
   ],
   

2. Add jQuery Plugins Extend the package by creating a custom Blade directive or helper:

   // In a service provider
   Blade::directive('jqueryPlugins', function ($expression) {
       return "<script src='/js/plugins/{$expression}.js'></script>";
   });
   

   Usage:

   @jquery
   @jqueryPlugins('datatables')
   

3. Dynamic Loading Use Alpine.js or Laravel Livewire to conditionally load jQuery only when needed:

   <div x-data="{ loadJQuery: false }">
       <button @click="loadJQuery = true">Load jQuery</button>
       <template x-if="loadJQuery">
           @jquery
           <script>
               // jQuery code here
           </script>
       </template>
   </div>