Jquery Ajax Enx Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require analyzer666/jquery-ajax-enx-bundle:dev-master
   

   Ensure AppKernel.php includes the bundle in the registerBundles() method:

   new Analyzer666\JQueryAjaxEnxBundle\JQueryAjaxEnxBundle(),
   

2. Client-Side Preparation:

   • Add a loading overlay (e.g., ajax-loading) and a target container (e.g., #galleries) in your Twig template.
   • Include jQuery (required by the bundle) in your base layout:

     {{ parent() }}
     {{ include('Analyzer666JQueryAjaxEnxBundle::jquery.js') }}
     

3. First Use Case: Replace a div (#photos) with AJAX response from a route (gallery_renderPhotos):

   {{ ja_link({
       'update': '#photos',
       'url': path('gallery_renderPhotos', {'id': gallery.id}),
       'text': 'Load Photos',
       'loading': 'ajax-loading'
   }) }}
   

Implementation Patterns

Core Workflows

1. Dynamic Content Loading: Use ja_link or ja_button for interactive elements (e.g., dropdowns, modals):

   {{ ja_link({
       'update': '#dynamic-content',
       'url': path('fetch_content', {'type': 'news'}),
       'text': 'Load News',
       'confirm': true
   }) }}
   

2. Form Submission: Serialize form data and submit via AJAX:

   {{ ja_button({
       'update': '#form-response',
       'url': path('submit_form'),
       'text': 'Submit',
       'data': '$(this.form).serialize()',
       'loading': 'ajax-loading'
   }) }}
   

3. Conditional Logic: Chain callbacks (before, after, complete) for side effects:

   {{ ja_request({
       'url': path('process_order'),
       'before': 'validateForm()',
       'after': 'updateCartTotal()',
       'complete': 'showToast("Order processed")'
   }) }}
   

Integration Tips

• Symfony Forms: Combine with {{ form_start(form, {'attr': {'id': 'my-form'}}) }} and use ja_button for submission.
• Twig Extensions: Extend the bundle by overriding Twig functions in a custom bundle (e.g., add method option to ja_request).
• Error Handling: Use error callback in ja_request to handle failures:

  {{ ja_request({
      'url': path('delete_item'),
      'error': 'showError("Failed to delete")'
  }) }}
  

Gotchas and Tips

Pitfalls

1. Missing jQuery: The bundle requires jQuery. Ensure it’s loaded before the bundle’s JS:

   <!-- Load jQuery first -->
   <script src="https://code.jquery.com/jquery-3.6.0.min.js"></script>
   <!-- Then load the bundle's JS -->
   {{ include('Analyzer666JQueryAjaxEnxBundle::jquery.js') }}
   

2. CSRF Tokens: For POST requests, manually include CSRF tokens in the data option:

   {{ ja_request({
       'url': path('create_item'),
       'data': '_token={{ csrf_token('create_item') }}&name=Test'
   }) }}
   

3. Route Scope: The bundle generates absolute URLs by default. For API routes, use url() with _route or path() with _route to avoid hardcoding.

4. Twig Syntax Quirks:

   • Strings: Escape single quotes in after/before callbacks:

     'after': "alert('Success!');"
     

   • Variables: Use {{ var|raw }} if passing dynamic Twig variables to data:

     'data': 'id={{ gallery.id|raw }}'
     

Debugging

• Console Logs: Add console.log(data) to success callbacks to inspect responses:

  {{ ja_request({
      'url': path('debug_route'),
      'success': 'console.log(data)'
  }) }}
  

• Network Tab: Verify AJAX requests in Chrome DevTools (F12) for failed calls (check status codes and payloads).

Extension Points

1. Custom Twig Functions: Override the bundle’s Twig functions in a custom bundle by redefining the ja_* functions in your Resources/views/ templates.

2. Ajax Options: Extend the bundle’s JQueryAjaxEnxExtension class to add new options (e.g., timeout):

   // In a custom bundle
   public function getJaRequestOptions(array $options) {
       $defaults = [
           'timeout' => 10000, // Add new option
       ];
       return array_merge($defaults, $options);
   }
   

3. Loading States: Dynamically toggle loading states with CSS classes instead of IDs for better maintainability:

   {{ ja_link({
       'loading': '.loading-overlay',
       'update': '.content-target'
   }) }}