Dokumentacija: Custom Modal Web Komponente

Kompletan sistem od 8 nezavisnih HTML5 Web Komponenti izgrađenih na Native Popover API-ju i Fullscreen API-ju, bez eksternih biblioteka i fontova.

0. Instalacija, Auto-load i CSS Varijable Osnova sistema

Biblioteka je dizajnirana tako da se u HTML dokument uključuje samo jednim pozivom. Skripta modals.js pomoću document.currentScript.src automatski detektuje sopstvenu putanju (čak i kada na stranici postoji <base href="/"> tag) i u <head> ubacuje modals.css iz istog direktorijuma. Sve ikonice su ugrađene kao čisti vektorski SVG-ovi unutar MODAL_ICONS objekta.

Uključivanje u projekat

<!-- Dovoljno je uključiti samo modals.js (u head sa defer ili pre zatvaranja body taga) -->
<script src="putanja/do/modals.js" defer></script>

Prilagođavanje boja (CSS Varijable)

Boje se definišu u RGB formatu (tri broja odvojena zarezom) unutar :root selektora kako bi CSS mogao dinamički da upravlja providnošću (rgba):

:root {
  --modal_backdrop: 20, 20, 20;         /* Boja zatamnjenja pozadine (backdrop) */
  --modal_box_background: 98, 98, 98;   /* Boja pozadine prozora (box, confirm, alert, wizard, toast) */
  --modal_box_color: 255, 255, 255;     /* Boja teksta i ikonica u prozorima */
}

Zajednički bezbednosni mehanizmi

1. <modal-box> — Standardni prozor Osnovni dijalog

Univerzalni prozor za prikazivanje teksta, formi, tabela ili proizvoljnog HTML sadržaja. Automatski kreira <modal-close> (dugme X) u gornjem desnom uglu.

HTML Struktura i pod-elementi

<modal-box id="moj_modal" persistent>
  <modal-header>Naslov prozora</modal-header>
  <modal-main>
    <p>Glavni sadržaj modala (automatski dobija vertikalni skrol ako pređe 90vh).</p>
  </modal-main>
  <modal-footer>
    <button class="modal-btn modal-btn-cancel" onclick="document.getElementById('moj_modal').hide()">Zatvori</button>
    <button class="modal-btn modal-btn-confirm">Sačuvaj</button>
  </modal-footer>
</modal-box>

Podržani HTML Atributi

AtributVrednostOpis ponašanja
(bez atributa) - Podrazumevani režim (popover="auto"). Zatvara se klikom na X, klikom na zatamnjenu pozadinu (backdrop) ili pritiskom na Escape.
persistent prazno ili "true" / "false" Sprečava zatvaranje klikom na pozadinu (backdrop) i tasterom Escape. Korisnik mora da klikne na X dugme ili dugme unutar modala.
locked prazno ili "true" / "false" Isto kao persistent, ali sakriva X dugme (<modal-close>). Modal se može zatvoriti isključivo kroz JavaScript.
forced prazno ili "true" / "false" Najstroži režim: isto kao locked (nema zatvaranja na pozadinu, nema X dugmeta), plus aktivira beforeunload zaštitu koja sprečava korisnika da osveži stranicu (F5) ili zatvori tab dok je modal otvoren.

JavaScript Metode i Događaji

Metoda / DogađajOpis
modal.show()Otvara modal i ažurira režim rada.
modal.hide()Zatvara modal.
modal.persistent(boolean)Dinamički uključuje (true) ili isključuje (false) persistent atribut (čak i dok je modal otvoren).
modal.locked(boolean)Dinamički uključuje ili isključuje locked režim (odmah prikazuje/sakriva X dugme).
modal.forced(boolean)Dinamički uključuje ili isključuje forced režim i zaštitu od osvežavanja stranice.
addEventListener('toggle', fn)Nativni događaj. Proverom event.newState === "open" ili "closed" pratiš otvaranje i zatvaranje.

Interaktivni primeri za <modal-box>

Standardni Modal Box

Probaj da klikneš na sivu pozadinu, na X u uglu ili pritisni ESC na tastaturi.

2. <modal-picture> — Prikaz pojedinačne slike Zoom & Pan

Komponenta za pregled slike preko celog ekrana sa ugrađenim spinerom učitavanja (<modal-loader>), sprečavanjem nativnog "ghost drag" efekta pregledača, zumiranjem u tačku kursora i Fullscreen režimom.

HTML Struktura i pod-elementi

<modal-picture id="moja_slika" zoom persistent>
  <picture>
    <img src="visoka-rezolucija.jpg" alt="Opis slike">
  </picture>
  <picture-title>Naslov slike</picture-title>
  <picture-description>Opis slike koji se automatski pakuje u donji gradijent...</picture-description>
</modal-picture>

Podržani HTML Atributi i CSS Klase

Atribut na <modal-picture>Alternativna klasa na <img>Opis ponašanja
zoom class="zoom_in" Dozvoljava uveličavanje slike od 1x do 5x. Ne dozvoljava smanjivanje ispod originalne veličine.
zoom-free class="zoom_free" Dozvoljava slobodno skaliranje slike od 0.2x (umanjenje) do 5x (uvećanje), kao i slobodno pomeranje (panovanje) pri bilo kom zumu.
persistent - Sprečava zatvaranje klikom na tamnu pozadinu i pritiskom na Escape. Dugme X ostaje vidljivo.
locked - Sprečava zatvaranje klikom na pozadinu/ESC i sakriva X dugme.
forced - Isto kao locked + blokira osvežavanje ili napuštanje stranice (beforeunload).

Ugrađene kontrole (Miš, Tastatura, Touch)

JavaScript Metode

Interaktivni primeri za <modal-picture>

Pas Standardni Zoom (1x do 5x) Koristi točkić miša, +/- na tastaturi, strelice za pomeranje ili dvoklik za reset. Kanjon Slobodni Zoom-Free (0.2x do 5x) Ovde možeš odzumirati sliku ispod 100% i slobodno je pomerati po ekranu.

4. <modal-confirm> — Potvrdni dijalog Async / Promise

Nasleđuje ModalBox i služi za asinhrono postavljanje pitanja korisniku (zamena za nativni window.confirm()). Automatski generiše <modal-header>, <modal-main> i <modal-footer> sa dugmadima za potvrdu i odustajanje ukoliko ih ne napišeš ručno.

HTML Struktura

<!-- Varijanta 1: Kraći zapis preko atributa -->
<modal-confirm id="potvrda_brisanja" title="Potvrda brisanja" ok-text="Obriši" cancel-text="Odustani" persistent>
  <modal-main>Da li ste sigurni da želite da obrišete ovog korisnika?</modal-main>
</modal-confirm>

<!-- Varijanta 2: Može biti i potpuno prazan tag koji puniš kroz JS metodu .ask() -->
<modal-confirm id="dinamicki_confirm"></modal-confirm>

Podržani HTML Atributi

AtributPodrazumevanoOpis ponašanja
title"Potvrda"Naslov modala ako unutar njega nije ručno napisan <modal-header>.
ok-text"Potvrdi"Tekst na plavom dugmetu za potvrdu akcije.
cancel-text"Odustani"Tekst na dugmetu za odustajanje.
persistent / locked / forced-Svi bezbednosni atributi nasleđeni iz ModalBox klase.

JavaScript Metode i Custom Događaji

Važno pravilo: Kada koristiš await modal.ask() unutar event listenera ili funkcije, ta funkcija mora imati ključnu reč async ispred sebe!

document.getElementById("dugme_obrisi").addEventListener("click", async () => {
  const odgovor = await document.getElementById("potvrda_brisanja").ask(
    "Da li zaista želite da obrišete fajl sa servera?", // Opciona nova poruka
    "Upozorenje pred brisanje"                          // Opcioni novi naslov
  );

  if (odgovor === true) {
    console.log("Korisnik je potvrdio!");
  } else {
    console.log("Korisnik je odustao (ili zatvorio modal na X / ESC / pozadinu).");
  }
});
Metoda / DogađajOpis
await modal.ask(message?, title?)Otvara dijalog i vraća Promise<boolean>. Vraća true ako korisnik klikne na dugme za potvrdu, a false ako klikne na Odustani, X, pozadinu ili Escape.
addEventListener('confirm', fn)Custom događaj koji se okida kada korisnik klikne na dugme za potvrdu.
addEventListener('cancel', fn)Custom događaj koji se okida kada korisnik klikne na dugme za odustajanje.
show(), hide(), persistent(), locked(), forced()Standardne metode nasleđene od ModalBox.

Interaktivni primeri za <modal-confirm>

Status: Čeka se akcija korisnika...
Da li ste sigurni da želite trajno da obrišete izabrani zapis iz baze podataka?

5. <modal-alert> — Statusno obaveštenje Info / Success / Warning / Error

Zamena za nativni window.alert(). Nasleđuje ModalBox, prikazuje odgovarajuću obojenu SVG ikonicu u zaglavlju na osnovu tipa poruke i vraća Promise koji se razrešava kada korisnik zatvori obaveštenje.

HTML Struktura

<modal-alert id="moj_alert" type="success" title="Uspešna akcija" ok-text="U redu">
  <modal-main>Podaci su uspešno sačuvani u bazi.</modal-main>
</modal-alert>

Podržani HTML Atributi

AtributPodržane vrednostiOpis ponašanja
type "info" (plava), "success" (zelena), "warning" (žuta), "error" (crvena) Automatski ubacuje odgovarajuću SVG statusnu ikonicu ispred naslova u <modal-header>.
title Tekst Naslov obaveštenja (podrazumevano "Obaveštenje" ako nema <modal-header> taga).
ok-text Tekst Tekst na dugmetu za zatvaranje (podrazumevano "U redu").
persistent / locked / forced prazno ili "true" / "false" Kontrola zaključavanja izlaska nasleđena iz ModalBox.

JavaScript Metode

// Pozivanje sa await (kod ispod čeka dok korisnik ne klikne "U redu" ili zatvori modal)
document.getElementById("dugme_sacuvaj").addEventListener("click", async () => {
  await document.getElementById("moj_alert").alert(
    "Konekcija sa uređajem je uspešno uspostavljena.", // Poruka
    "Status uređaja",                                  // Naslov
    "success"                                          // Tip: info | success | warning | error
  );
  console.log("Korisnik je pročitao i zatvorio obaveštenje!");
});

Interaktivni primeri za <modal-alert>

6. <modal-video> — Video i YouTube / Vimeo plejer 16:9 + Start sekunda

Specijalizovan modal za reprodukciju lokalnih HTML5 video fajlova (.mp4, .webm) ili ugrađenih YouTube i Vimeo plejera (<iframe>). Automatski pakuje medij u 16:9 <video-wrapper>, podržava definisanje početne sekunde i automatski prekida reprodukciju i zvuk čim se modal zatvori.

HTML Struktura (3 podržana načina pisanja)

<!-- 1. Nativni HTML5 video sa početnom sekundom i naslovom -->
<modal-video id="lokalni_video" start="15" autoplay>
  <video src="snimak.mp4" controls></video>
  <video-title>Snimak kamere — Ulaz 1</video-title>
  <video-description>Pregled detekcije od 15. sekunde.</video-description>
</modal-video>

<!-- 2. Direktno prosleđivanje YouTube / Vimeo embed linka ili MP4 putanje kroz src atribut -->
<modal-video id="yt_video" src="https://www.youtube.com/embed/aqz-KE-bpKQ" start="30" autoplay>
  <picture-title>Big Buck Bunny (YouTube)</picture-title>
</modal-video>

<!-- 3. Ručni iframe tag unutar modala -->
<modal-video id="custom_iframe" autoplay>
  <iframe src="https://www.youtube.com/embed/aqz-KE-bpKQ" allowfullscreen></iframe>
</modal-video>

Podržani HTML Atributi

AtributVrednostOpis ponašanja
src URL (MP4 ili YouTube/Vimeo embed) Ako ne napišeš <video> ili <iframe> unutar modala, komponenta će na osnovu ovog URL-a sama kreirati odgovarajući plejer.
start Broj sekundi (npr. "45") Od koje sekunde video treba da krene. Može se staviti na <modal-video start="45"> ili na <video start="45">. Kod YouTube-a automatski dodaje ?start=45, a kod Vimea #t=45s.
autoplay prazno ili "true" / "false" Automatski pokreće video čim se modal otvori.
persistent / locked / forced prazno ili "true" / "false" Kontrola zaključavanja modala (sprečavanje zatvaranja na backdrop, skrivanje X dugmeta, blokada osvežavanja stranice).

JavaScript Metode

MetodaOpis
videoModal.show(startSeconds?) Otvara modal i pokreće video. Ako proslediš broj u zagradi (npr. videoModal.show(60)), video će krenuti od 60. sekunde, bez obzira na to šta piše u HTML atributu start.
videoModal.hide() Zatvara modal, pauzira HTML5 video i vraća ga na 0, odnosno prazni src kod YouTube/Vimeo iframe-a kako zvuk ne bi nastavio da se čuje u pozadini.
persistent(state), locked(state), forced(state) Dinamička kontrola zaključavanja modala.

Interaktivni primeri za <modal-video>

HTML5 MP4 Video Primer Zatvaranjem modala video se automatski zaustavlja. YouTube Embed Primer Automatski kreće od 25. sekunde.

7. <modal-toast> i toast() — Iskačuće notifikacije Auto-stacking

Ne-blokirajuće poruke u uglu ekrana. Ne zatamnjuju pozadinu, ne zaključavaju skrol stranice i automatski se slažu jedna iznad/ispod druge kada ih se pojavi više istovremeno.

Način 1: Čist JavaScript poziv — bez pisanja HTML-a (Preporučeno)

Učitavanjem modals.js dobijaš globalnu funkciju toast(poruka, tip, trajanjeUSekundama, pozicija) koja sama kreira element, prikazuje ga, slaže u niz i briše iz DOM-a kada istekne vreme:

// Sintaksa: toast(message, type = 'info', duration = 4, position = 'bottom-right')

toast("Podaci su uspešno sačuvani!", "success", 4);
toast("Proverite mrežnu konekciju.", "warning", 6);
toast("Greška pri komunikaciji sa bazom!", "error", 5, "top-right");
toast("Stigla je nova poruka.", "info", 0, "bottom-left"); // duration = 0 znači da se ne gasi sam dok korisnik ne klikne X

Način 2: Deklarativni HTML element

<modal-toast id="moj_staticki_toast" type="success" duration="4" position="bottom-right">
  Operacija je uspešno izvršena!
</modal-toast>

<script>
  // Pokretanje postojećeg HTML toast-a (možeš mu i promeniti tekst/tip pri pozivu):
  document.getElementById('moj_staticki_toast').show("Novi tekst poruke!", "info", 5);
</script>

Podržani Atributi i Parametri

Atribut / ParametarPodržane vrednostiOpis
type (2. parametar) "info", "success", "warning", "error" Određuje ikonicu i njenu boju na levoj strani notifikacije.
duration (3. parametar) Broj sekundi (default 4) ili 0 Posle koliko sekundi obaveštenje samo nestaje. Ako se stavi 0, ostaje na ekranu dok korisnik ne klikne na X.
position (4. parametar) "bottom-right" (default), "bottom-left", "top-right", "top-left", "bottom-center", "top-center" U kom delu ekrana se pojavljuje i slaže niz notifikacija.

Interaktivni primeri za Toast notifikacije

8. <modal-wizard> — Višekoračni čarobnjak (Stepper) Koraci + Validacija

Nasleđuje ModalBox i omogućava vođenje korisnika kroz više koraka (<wizard-step>) sa vizuelnim indikatorom napretka na vrhu, prilagodljivim dugmićima i trostrukim sistemom validacije pre prelaska na naredni korak.

HTML Struktura i prilagođeni tagovi za dugmad

<modal-wizard id="moj_wizard" persistent>
  <modal-header>Konfiguracija sistema</modal-header>

  <wizard-step title="Mreža">
    <label>IP Adresa servera:</label>
    <input type="text" id="wiz_ip" required placeholder="192.168.1.10">
  </wizard-step>

  <wizard-step title="Kamere">
    <label>Broj kanala (1-16):</label>
    <input type="number" id="wiz_kanali" min="1" max="16" required value="4">
  </wizard-step>

  <wizard-step title="Potvrda">
    <p>Proverite unete podatke i kliknite na dugme ispod za slanje.</p>
  </wizard-step>

  <!-- Tvoji custom tagovi za dugmad (automatski se prebacuju u modal-footer) -->
  <wizard-previous>Prethodno</wizard-previous>
  <wizard-next>Sledeće</wizard-next>
  <wizard-finish>Pošalji konfiguraciju</wizard-finish>
</modal-wizard>

Podržani HTML Atributi

AtributNa kom elementuOpis ponašanja
title="Naziv" <wizard-step> Određuje naziv koraka koji se ispisuje u gornjoj traci indikatora (npr. 1 Mreža, 2 Kamere).
prev-text, next-text, finish-text <modal-wizard> Rezervni tekstovi za dugmad ukoliko u HTML-u ne napišeš ručno tagove <wizard-previous>, <wizard-next> i <wizard-finish>.
persistent / locked / forced <modal-wizard> Standardni atributi za zaključavanje modala.

Kako radi validacija koraka (3 nivoa zaštite)

  1. Automatska HTML5 validacija: Svaki <input>, <select> ili <textarea> unutar trenutno aktivnog <wizard-step>-a koji ima atribute required, min, max, pattern ili type="email" automatski se proverava. Ako polje nije ispravno, pregledač prikazuje balončić sa greškom i blokira prelazak na sledeći korak.
  2. Custom JS Validator funkcija (setValidator): Možeš proslediti sopstvenu funkciju koja prima indeks koraka i DOM element tog koraka, i vraća true (dozvoli) ili false (blokiraj).
  3. Događaj step-validate: Možeš slušati step-validate događaj i pozvati event.preventDefault() ako želiš da zaustaviš prelazak.

JavaScript Metode i Custom Događaji

const wizard = document.getElementById('moj_wizard');

// 1. Postavljanje sopstvene JS validacije po koracima
wizard.setValidator((stepIndex, stepEl) => {
  if (stepIndex === 0) {
    const ip = stepEl.querySelector('#wiz_ip').value.trim();
    if (!ip.startsWith('192.168.')) {
      toast('IP adresa mora počinjati sa 192.168.', 'error', 4);
      return false; // Blokira prelazak na Korak 2!
    }
  }
  return true;
});

// 2. Praćenje promene koraka
wizard.addEventListener('step-change', (e) => {
  console.log('Trenutni korak je:', e.detail.step);
});

// 3. Akcija kada korisnik klikne na završno dugme ()
wizard.addEventListener('wizard-finish', () => {
  toast('Konfiguracija je uspešno sačuvana!', 'success', 4);
});
Metoda / DogađajOpis
wizard.show() / wizard.hide()Otvara / zatvara čarobnjak.
wizard.nextStep()Validira trenutni korak i prelazi na sledeći.
wizard.prevStep()Vraća se na prethodni korak (bez pokretanja validacije).
wizard.goToStep(index, validateForward = true)Skače na zadati korak (0 je prvi). Korisnik može i mišem da klikne na prethodne korake u gornjoj navigaciji.
wizard.reset()Vraća čarobnjak na prvi korak (indeks 0).
wizard.finish()Validira poslednji korak, okida događaj wizard-finish i zatvara modal.
wizard.setValidator(fn)Registruje funkciju (stepIndex, stepElement) => boolean za proveru pre prelaska dalje.

Interaktivni primer za <modal-wizard>

Podešavanje LPR čvora

Probaj da obrišeš polje ili upišeš 10.0.0.1 pa klikni na "Sledeće" da vidiš validaciju.

Svi parametri su provereni i spremni za upis u konfiguraciju.

Klikni na Pošalji da završiš proces.

Prethodno Sledeće Pošalji