Colorbox Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require contao-components/colorbox
   

   Ensure the package is registered in config/app.php under providers (if not auto-discovered).

2. Basic Usage Include the Colorbox CSS/JS in your Laravel app:

   @vite(['resources/css/colorbox.css', 'resources/js/colorbox.js'])
   

   Or via CDN in a blade template:

   <link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/colorbox/1.6.4/colorbox.min.css" />
   <script src="https://cdnjs.cloudflare.com/ajax/libs/colorbox/1.6.4/jquery.colorbox-min.js"></script>
   

3. First Use Case Trigger Colorbox on a link:

   <a href="path/to/image.jpg" class="colorbox" title="My Image">Open Image</a>
   

   Initialize via JavaScript:

   $(document).ready(function() {
       $(".colorbox").colorbox({maxWidth:"80%", maxHeight:"80%"});
   });
   

Implementation Patterns

Common Workflows

1. Dynamic Content Loading Use Laravel Blade + AJAX to fetch content dynamically:

   $(".dynamic-link").colorbox({
       href: "/api/content/" + id,
       onLoad: function() {
           $.get("/api/content/" + id, function(data) {
               $(".colorbox").html(data);
           });
       }
   });
   

2. Integration with Laravel Collections Loop through a collection and generate Colorbox links:

   @foreach($images as $image)
       <a href="{{ asset('storage/' . $image->path) }}"
          class="colorbox"
          title="{{ $image->title }}">
          {{ $image->thumbnail }}
       </a>
   @endforeach
   

3. Form Handling Inside Colorbox Use onClosed to process form submissions:

   $(".colorbox-form").colorbox({
       onClosed: function() {
           $.post("/submit-form", $("#form-id").serialize(), function(response) {
               alert("Submitted!");
           });
       }
   });
   

Integration Tips

• Laravel Mix/Vite: Bundle Colorbox with your assets for optimized loading.
• Service Providers: Extend functionality via a custom service provider:

  public function boot()
  {
      Colorbox::macro('laravelInit', function() {
          return $this->js('$(document).ready(function(){ $(".colorbox").colorbox({maxWidth:"90%"}); });');
      });
  }
  

• Blade Directives: Create a @colorbox directive for reusable markup.

Gotchas and Tips

Pitfalls

1. jQuery Dependency Ensure jQuery is loaded before Colorbox:

   <!-- Wrong order -->
   <script src="colorbox.js"></script>
   <script src="jquery.js"></script>
   
   <!-- Correct -->
   <script src="jquery.js"></script>
   <script src="colorbox.js"></script>
   

2. CSS Conflicts Colorbox may override Bootstrap/modal styles. Override with:

   .colorbox, #colorbox, .colorbox-loaded { z-index: 9999 !important; }
   

3. Lazy Loading Issues If using lazy-loaded images, ensure Colorbox triggers after images load:

   $(".colorbox").colorbox({
       onOpen: function() {
           $(".lazy-image").trigger("click"); // Force load
       }
   });
   

Debugging Tips

• Console Errors: Check browser console for missing jQuery or malformed HTML.
• Inspect Elements: Verify Colorbox overlays are not hidden by overflow: hidden or z-index.
• Disable Plugins: Temporarily disable other JS plugins to isolate conflicts.

Extension Points

1. Custom Templates Override default templates by extending the package’s JS:

   $.colorbox.settings.template = '<div class="my-custom-colorbox">{content}</div>';
   

2. Laravel Events Hook into colorbox.init via a custom event listener:

   Event::listen('colorbox.init', function() {
       // Post-init logic (e.g., analytics)
   });
   

3. API Integration Use Laravel’s HTTP client to fetch remote content:

   $(".remote-link").colorbox({
       href: function() {
           return "{{ route('api.colorbox.content') }}?id=" + $(this).data('id');
       }
   });