Drupal: Zamena Colorbox‑a sa GLightbox‑om

1 Uvod

Lightbox dodaci su već više od jedne decenije sastavni deo Drupal sajtova. Omogućavaju urednicima da prikažu slike, video‑zapise i druge medije u preklopnom sloju bez napuštanja trenutne stranice — obrazac koji posetioci očekuju na modernim, sadržajno bogatim sajtovima.

Colorbox je istorijski bio podrazumevano rešenje u Drupal ekosistemu. Doprinosni modul colorbox je čvrsto povezan sa Drupal formatima polja za slike, ima zrelu API strukturu i široku prepoznatljivost u zajednici. Međutim, kako se veb razvijao, Colorbox je pokazao svoje godine: zavisi od jQuery‑ja, isporučuje teži payload i zaostaje za savremenim očekivanjima pristupačnosti.

Tu nastupa GLightbox — lightbox biblioteka pisana u čistom vanilla JavaScript‑u (bez zavisnosti), sa uglađenim UI‑jem, robusnom podrškom za pristupačnost i malim otiskom. Odgovarajući Drupal modul se čisto integriše sa istim poljima za slike i media entitetima koje je Colorbox ranije pokrivao.

Ovaj članak vas vodi kroz kompletnu migraciju: od provere postojećeg Colorbox podešavanja, preko instalacije GLightbox‑a, mapiranja formatera polja, bezbednog uklanjanja starog modula, do finog podešavanja novog iskustva u okviru vaše teme.

2 Colorbox vs GLightbox: Zašto migrirati?

2.1 Ograničenja Colorbox‑a

Colorbox je nastao u drugačijoj eri veba. Njegova arhitektura odražava pretpostavke koje više ne važe u savremenom Drupal razvoju:

• Zavisnost od jQuery‑ja. Colorbox je jQuery dodatak — ne može da radi bez njega. Drupal core postepeno smanjuje sopstveno oslanjanje na jQuery, a mnoge teme fokusirane na performanse učitavaju jQuery lenjo ili ga uopšte ne učitavaju. Fiksna zavisnost od jQuery‑ja ide protiv tog cilja.
• Zastareo UI i animacije. Podrazumevani Colorbox stilovi deluju zastarelo u poređenju sa dizajnerskim normama iz perioda 2024–2026. Često je potrebno ozbiljno prilagođavanje CSS‑a samo da bi se dostigao osnovni moderan izgled.
• Nedostaci u pristupačnosti. Iako je Colorbox tokom godina dobio određene zakrpe za pristupačnost, nije projektovan sa WCAG 2.1 AA standardom kao primarnim ciljem. Zadržavanje fokusa, ARIA uloge i najave za čitače ekrana često zahtevaju dodatni rad.
• Tempo održavanja. Izvorna jQuery Colorbox biblioteka se retko ažurira. Za dugoročne Drupal projekte, oslanjanje na sporo održavanu zavisnost predstavlja rizik.

2.2 Prednosti GLightbox‑a

GLightbox direktno rešava svaku od navedenih tačaka:

• Bez zavisnosti. Čisti ES6+ JavaScript; nije potreban jQuery.
• Moderan UX. Glatke CSS tranzicije, swipe gestovi, navigacija tastaturom i čista podrazumevana tema koja se dobro uklapa u savremene dizajne.
• Pristupačnost prve klase. Fokus je zadržan unutar lightbox‑a, navigacija strelicama radi odmah, a pravilna ARIA role="dialog" semantika se automatski primenjuje.
• Lagan. Minifikovani i gzipovani bundle je manji od 15 KB — približno 3× lakši od tipične Colorbox postavke.
• Grupisanje galerija. Izvorna podrška za grupisane galerije preko atributa data-gallery, bez dodatnih dodataka.
• Aktivan razvoj. GLightbox projekat na GitHub‑u ima redovna izdanja i ispravke grešaka.

3 Pregled Drupal ekosistema

Drupal core je tokom više godina sprovodio strategiju smanjenja upotrebe jQuery‑ja, prelazeći na čisti JavaScript i moderne API‑je pregledača. Ovo se ogleda u depreciranju mnogih jQuery‑baziranih ponašanja u Drupalu 10+ i podsticanju tema da usvoje lakše JavaScript strategije.

Sa strane doprinosa zajednice, i Colorbox i GLightbox imaju namenski Drupal module na Drupal.org‑u:

• colorbox — klasičan izbor, sa dubokom integracijom u formatere Image polja, Views i media sistem. I dalje široko instaliran, ali sa ređim ažuriranjima.
• glightbox — noviji doprinosni modul koji obavija GLightbox JS biblioteku. Obezbeđuje formatere za Image i Media polja, podršku za Views i stranicu sa podešavanjima za najčešće GLightbox opcije.

4 Priprema za migraciju

4.1 Provera trenutne upotrebe Colorbox‑a

Pre nego što promenite bilo kakvu konfiguraciju, napravite potpunu sliku gde i kako se Colorbox koristi na vašem sajtu:

1. Polja sa slikama. Posetite Structure → Content Types → [Tip] → Manage display za svaki tip sadržaja i proverite da li neko polje sa slikom koristi Colorbox formater. Zabeležite image stilove i podešavanja natpisa.
2. Media entiteti. Proverite prikazne režime media tipova u okviru Structure → Media types. Ponovite za svaki media tip koji uključuje slike ili video.
3. Views. Pronađite Views koji uključuju polja sa slikama i proverite koji se formater koristi. Colorbox može biti primenjen i putem Views „Colorbox“ format plugina.
4. Prilagođeni kod. Pretražite custom module i teme za reference na colorbox, .colorbox, Drupal.behaviors.colorbox i ključ biblioteke colorbox/colorbox.

# Brza pretraga kroz ceo kod (pokrenuti iz Drupal root direktorijuma)
grep -r "colorbox" web/modules/custom web/themes/custom \
  --include="*.php" --include="*.js" --include="*.twig" \
  --include="*.yml" -l

Vodite beleške o svakoj pronađenoj lokaciji. Svaku ćete ponovo proveriti tokom faze zamene.

4.2 Backup i razmatranje okruženja

• Izvezite aktivnu konfiguraciju: drush config:export
• Sačuvajte export u sistem za verzionisanje pre početka
• Isključite CSS/JS agregaciju tokom migracije (Admin → Performance)
• Napravite dump baze podataka: drush sql:dump > pre-migration.sql
• Proverite da li deployment pipeline može da isporuči izmene konfiguracije na staging/production

5 Instalacija i omogućavanje GLightbox‑a u Drupalu

5.1 Instalacija GLightbox JavaScript biblioteke

Drupal GLightbox modul zavisi od izvorne GLightbox JS biblioteke. Postoje dva podržana načina za njeno obezbeđivanje.

Opcija A — Composer + Asset Packagist (Preporučeno)

# Dodavanje Asset Packagist repozitorijuma (jednom po projektu)
composer config repositories.asset-packagist \
  composer https://asset-packagist.org

# Dodavanje biblioteke
composer require oomphinc/composer-installers-extender
composer require npm-asset/glightbox

Dodajte ili proverite putanju instalacije za npm-asset u sekciji extra.installer-paths u fajlu composer.json:

"extra": {
  "installer-types": ["npm-asset", "bower-asset"],
  "installer-paths": {
    "web/libraries/{$name}": [
      "type:drupal-library",
      "type:npm-asset",
      "type:bower-asset"
    ]
  }
}

Nakon pokretanja composer install, biblioteka će se nalaziti na lokaciji web/libraries/glightbox/.

Opcija B — Ručno postavljanje

Preuzmite najnovije izdanje sa GLightbox GitHub releases stranice i postavite fajlove tako da sledeće putanje postoje:

web/libraries/glightbox/dist/js/glightbox.min.js
web/libraries/glightbox/dist/css/glightbox.min.css

5.2 Instalacija i omogućavanje GLightbox Drupal modula

# Preuzimanje modula
composer require drupal/glightbox

# Omogućavanje
drush en glightbox -y

# Čišćenje keša
drush cr

Idite na Admin → Configuration → Media → GLightbox kako biste proverili da li je biblioteka prepoznata i istražili globalne opcije konfiguracije.

6 Zamena Colorbox funkcionalnosti

6.1 Polja sa slikama

Ovo je najčešći slučaj upotrebe Colorbox‑a: polje sa slikom na tipu sadržaja koje prikazuje thumbnail, a klik otvara sliku u punoj veličini u lightbox‑u.

1. Idite na Structure → Content Types → [Vaš tip] → Manage display.
2. Pronađite polje sa slikom. U padajućem meniju Format promenite vrednost sa Colorbox na GLightbox.
3. Kliknite na ikonu podešavanja (⚙) da biste konfigurisali formater. Podesite Image style (thumbnail prikazan na stranici) i Linked image style (slika učitana unutar lightbox‑a). Po potrebi omogućite natpise.
4. Sačuvajte konfiguraciju prikaza i očistite keš: drush cr.

Ovu konfiguraciju možete i izvesti i primeniti putem YAML‑a. Primer konfiguracije formatera polja u YAML‑u prikaza tipa sadržaja:

# core.entity_view_display.node.article.default.yml (izvod)
dependencies:
  module:
    - glightbox
    - image
content:
  field_image:
    type: glightbox
    label: hidden
    settings:
      image_style: medium
      image_link: ''
      glightbox_image_style: large
      glightbox_gallery: ''
      glightbox_caption: title
      glightbox_caption_custom: ''
    third_party_settings: {  }

6.2 Media i galerije

Za sajtove koji koriste Drupal Media sistem, koraci migracije su slični, ali se primenjuju na prikazne režime Media tipova.

• Posetite Structure → Media types → [Tip] → Manage display.
• Promenite formater polja koje je izvor slike sa Colorbox na GLightbox.
• Za grupisanje galerija, podesite polje Gallery ID u GLightbox podešavanjima formatera. Sve stavke sa istim Gallery ID‑jem biće dostupne kao grupa unutar lightbox‑a. Ovo se direktno mapira na izvorni GLightbox atribut data-gallery.

Mapiranje natpisa je jednostavno: GLightbox čita atribut data-description. Drupal modul omogućava mapiranje ovog atributa na title ili alt atribut slike, ili na vrednost prilagođenog polja.

6.3 Integracija sa Views‑ima

Ako Views prikazuju slike koristeći Colorbox formatiranje, ažurirajte svaki View na sledeći način:

1. Otvorite View u Structure → Views → [Naziv View‑a] → Edit.
2. Pod Fields kliknite na polje sa slikom. U padajućem meniju Formatter promenite Colorbox u GLightbox.
3. Ako je Colorbox bio primenjen na nivou Format‑a (npr. „Colorbox“ format plugin), pređite na standardni format kao što je Unformatted list ili Grid i primenite GLightbox formater na nivou polja.
4. Sačuvajte izmene i očistite keš.

7 Bezbedno uklanjanje Colorbox‑a

Kada su svi formateri i prilagođeni delovi koda migrirani, možete bezbedno ukloniti Colorbox. Pratite ovaj redosled kako biste izbegli greške u zavisnostima:

1. Isključite Colorbox modul. Isključivanje pre deinstalacije omogućava Drupalu da izvrši čišćenje kroz hook_uninstall().

   drush pm:uninstall colorbox -y

2. Uklonite iz composer.json.

   composer remove drupal/colorbox

3. Uklonite Colorbox JS biblioteku iz web/libraries/colorbox/ ako je bila ručno postavljena.
4. Očistite prilagođeni kod. Pronađite i uklonite sve preostale reference na Colorbox CSS klase (.colorbox, .colorbox-load), JavaScript ponašanja (Drupal.behaviors.colorbox) ili priključivanje biblioteka (colorbox/colorbox).

5. Očistite sav keš i izvezite konfiguraciju.

   drush cr
   drush config:export

8 Prilagođavanje i unapređenja

8.1 Opcije konfiguracije GLightbox‑a

Globalna stranica sa GLightbox podešavanjima (Admin → Configuration → Media → GLightbox) izlaže najčešće korišćene opcije. One direktno odgovaraju JavaScript API‑ju GLightbox‑a:

8.2 Tema i stilizovanje

GLightbox dolazi sa podrazumevanim stilom (glightbox.min.css) koji pruža čist dizajn sa tamnim overlay‑em. Prepišite ga u svojoj temi bez izmene fajla biblioteke:

/* mytheme/css/glightbox-overrides.css */

/* Promena pozadine overlay‑a */
.glightbox-clean .goverlay {
  background: rgba(0, 0, 0, 0.92);
}

/* Stilizovanje dela za natpis */
.glightbox-clean .gdesc-inner {
  font-family: inherit;
  font-size: 0.9rem;
  color: #f0f0f0;
  padding: 12px 16px;
}

/* Uvećavanje navigacionih strelica */
.glightbox-clean .gnext,
.glightbox-clean .gprev {
  width: 48px;
  height: 48px;
}

/* Svetla varijanta */
@media (prefers-color-scheme: light) {
  .glightbox-clean .goverlay {
    background: rgba(255, 255, 255, 0.95);
  }
  .glightbox-clean .gdesc-inner {
    color: #1a1a1a;
  }
}

Priključite override stylesheet u .libraries.yml fajlu svoje teme:

# mytheme.libraries.yml
glightbox-overrides:
  version: VERSION
  css:
    theme:
      css/glightbox-overrides.css: {}
  dependencies:
    - glightbox/glightbox

Zatim ga globalno prikačite u mytheme.info.yml:

# mytheme.info.yml (izvod)
libraries:
  - mytheme/glightbox-overrides

8.3 Napredni scenariji upotrebe

Programatsko priključivanje putem #attached

GLightbox biblioteku možete priključiti na bilo koji render niz u custom modulu ili preprocess hook‑u:

// U preprocess funkciji ili build() metode custom bloka
$build['#attached']['library'][] = 'glightbox/glightbox';

// Prosleđivanje override opcija kroz JS settings
$build['#attached']['drupalSettings']['glightbox'] = [
  'animation'  => 'fade',
  'loop'       => TRUE,
  'touchNavigation' => TRUE,
];

Prilagođeni okidači u Twig šablonima

Da biste ručno kreirali GLightbox okidač u Twig šablonu, dodajte odgovarajuće atribute. GLightbox prepoznaje svaki element sa class="glightbox" (ili vašim konfigurisanom selector-om):

{# Otvaranje pojedinačne slike #}
<a href="{{ file_url(node.field_hero_image.entity.uri.value) }}"
   class="glightbox"
   data-title="{{ node.label }}"
   data-description="{{ node.field_caption.value }}">
  {{ content.field_hero_image }}
</a>

{# Grupna galerija — sve stavke sa istim data-gallery se otvaraju zajedno #}
{% for item in node.field_gallery %}
  <a href="{{ file_url(item.entity.uri.value) }}"
     class="glightbox"
     data-gallery="gallery-{{ node.id }}"
     data-description="{{ item.alt }}">
    <img src="{{ file_url(item.entity.uri.value) | image_style('thumbnail') }}"
         alt="{{ item.alt }}" />
  </a>
{% endfor %}

Drupal ponašanje za prilagođenu inicijalizaciju

Ako vam je potrebno da inicijalizujete GLightbox sa opcijama koje nisu izložene kroz UI modula, koristite prilagođeno Drupal ponašanje:

// mytheme/js/glightbox-init.js
(function (Drupal, drupalSettings) {
  'use strict';

  Drupal.behaviors.mythemeGlightbox = {
    attach(context, settings) {
      // Inicijalizuj samo jednom po kontekstu
      const elements = context.querySelectorAll('.glightbox-custom:not(.glightbox-processed)');
      if (!elements.length) return;

      elements.forEach(el => el.classList.add('glightbox-processed'));

      const lightbox = GLightbox({
        selector: '.glightbox-custom',
        touchNavigation: true,
        loop: true,
        animation: 'fade',
        autoplayVideos: settings.glightbox?.autoplayVideos ?? true,
      });
    },
  };

}(Drupal, drupalSettings));

9 Testiranje i kontrola kvaliteta

Nakon završetka migracije, prođite kroz sledeću QA kontrolnu listu pre isporuke na produkciju:

Funkcionalno testiranje

• Slike se otvaraju u lightbox‑u klikom na svim pogođenim tipovima sadržaja
• Navigacija galerijom (prethodna/sledeća strelica, strelice na tastaturi) radi ispravno
• Natpisi se prikazuju i odgovaraju očekivanoj vrednosti polja
• Video stavke (YouTube, Vimeo, lokalni video) se automatski pokreću i pravilno zatvaraju
• Zatvaranje lightbox‑a (✕ dugme, Escape taster, klik van sadržaja) vraća fokus

Testiranje u različitim pregledačima

• Chrome/Edge (Chromium), Firefox, Safari (macOS i iOS)
• Proverite da li se CSS tranzicije ispravno renderuju u svim testiranim pregledačima

Mobilno i touch testiranje

• Swipe levo/desno za navigaciju kroz galeriju
• Pinch‑to‑zoom na slikama (ako je omogućeno)
• Overlay ispravno pokriva viewport na malim ekranima

Provera pristupačnosti

• Tab taster kruži kroz kontrole lightbox‑a (zatvori, prethodna, sledeća)
• Fokus se vraća na okidač nakon zatvaranja
• Čitač ekrana najavljuje dijalog i njegov sadržaj (testirati sa NVDA ili VoiceOver‑om)
• Pokrenite axe DevTools ili Lighthouse audit pristupačnosti — cilj je nula kritičnih grešaka

Performanse

• Ponovo omogućite CSS/JS agregaciju i proverite da li se GLightbox i dalje inicijalizuje
• Pokrenite Lighthouse audit performansi i uporedite sa Colorbox osnovom
• Proverite da ne postoje JavaScript greške u konzoli ni na jednoj testiranoj stranici

10 Česti problemi i rešavanje poteškoća

Slike se ne otvaraju u lightbox‑u

Simptom: Klik na sliku vodi na povezani URL umesto da otvori GLightbox.

• Proverite da li se GLightbox biblioteka učitava: otvorite DevTools u pregledaču → Network tab, filtrirajte po glightbox. Ako je nema, proverite da li fajlovi postoje na web/libraries/glightbox/dist/.
• Uverite se da CSS/JS agregacija radi ispravno; privremeno je isključite kako biste izolovali probleme vezane za agregaciju.
• Proverite renderovani HTML i potvrdite da okidački element ima atribut class="glightbox" (ili prilagođeni selector koji ste konfigurisali).

Nedostajući natpisi ili neispravne galerije

Simptom: Natpisi su prazni ili navigacija galerijom preskače stavke.

• Pregledajte renderovane <a> tagove: proverite da li je data-description popunjen i da li se data-gallery vrednosti poklapaju u okviru grupe.
• Proverite da li podešavanje Caption source u formateru pokazuje na neprazno polje.
• Za grupisanje galerija proverite doslednost Gallery ID‑ja; token‑generisani ID‑jevi mogu se razrešiti u prazne vrednosti ako Token modul nije instaliran.

Sukobi sa drugim JS bibliotekama

Simptom: GLightbox se delimično inicijalizuje ili baca greške u konzoli.

• Proverite da li se GLightbox biblioteka učitava duplirano (modul + ručno priključivanje u temi).
• Proverite da li neka druga biblioteka ne prepisuje window.GLightbox.
• Ako tema koristi JS bundler, uverite se da GLightbox nije dodatno bundlovan pored priključivanja kroz Drupal asset sistem.

Problemi sa keširanjem i agregacijom

Simptom: GLightbox radi u development okruženju, ali ne i na produkciji.

• Pokrenite drush cr na produkciji nakon deploy‑a konfiguracionih izmena.
• Proverite da li je web/libraries/glightbox/ pravilno commit‑ovan ili deploy‑ovan — često ga .gitignore pravila izostavljaju. Razmotrite korišćenje composer install --no-dev u CI/CD pipeline‑u kako bi biblioteka bila postavljena.
• Ako CSS agregacija kompresuje GLightbox stylesheet na način koji remeti specifičnost selektora, dodajte override fajl kasnije u redosledu učitavanja asset‑a.

# Čišćenje celokupnog keša na produkciji (ako je Drush dostupan)
drush @prod cr

# Provera da li je fajl biblioteke na mestu
ls web/libraries/glightbox/dist/js/glightbox.min.js

11 Zaključak

Migracija sa Colorbox‑a na GLightbox predstavlja značajan korak modernizacije frontend‑a za svaki Drupal projekat. Prednosti su jasne:

• Uklanjanje jQuery runtime zavisnosti iz lightbox toka
• Brže i lakše iskustvo za posetioce
• Pristupačnost „out‑of‑the‑box“ bez prilagođenih zakrpa
• Usklađivanje sa smernicama Drupal core‑a ka čistom JavaScript‑u
• Smanjenje dugoročnog troška održavanja zahvaljujući aktivno razvijanoj biblioteci

Sama migracija je niskorizična ako se sprovodi metodično: prvo audit, zatim migracija formatera polja jedan po jedan, čišćenje nasleđenog koda i temeljno testiranje pre deploy‑a. Drupal modul glightbox većinu ovoga čini deklarativnim — kroz konfiguraciju u admin UI‑ju, umesto prilagođenog koda.

Za sajtove koji prolaze kroz širu frontend modernizaciju — prelazak na decoupled ili headless arhitekturu, usvajanje moderne teme (Olivero, Gin ili prilagođeni design system), ili smanjenje JavaScript težine — zamena Colorbox‑a sa GLightbox‑om je odlična, kontrolisana početna tačka koja donosi vidljive rezultate uz minimalan rizik.