DynamicJS – Dokumentacja

Wymagania i inicjalizacja

💡 Ważne: W produkcji dodaj pliki z https://dynamicjs.krzysztofzylka.pl/cdn/: jquery.min.js, dynamicjs.iife.js oraz opcjonalnie dynamicjs.es.js dla bundlerów. DynamicJS nie jest dostępny w npm – możesz korzystać z hostowanych zasobów lub pobrać je i serwować lokalnie.

Minimalny setup

<script src="https://dynamicjs.krzysztofzylka.pl/cdn/jquery.min.js"></script>
<script src="https://dynamicjs.krzysztofzylka.pl/cdn/dynamicjs.iife.js"></script>
<script>
  document.addEventListener('DOMContentLoaded', () => {
    window.DynamicJS.init();
  });
</script>

Gdzie wywołać init?

Po załadowaniu dokumentu (zalecane: DOMContentLoaded)
Na stronach single-page po każdej zmianie widoku – wywołaj window.DynamicJS.init(true), aby ponownie zeskanować DOM
Jeśli korzystasz z bundlera, importuj moduł z dynamicjs.es.js i udostępnij jQuery jako window.$

Integracja modułowa

import $ from 'jquery';
import DynamicJS from 'https://dynamicjs.krzysztofzylka.pl/cdn/dynamicjs.es.js';

window.$ = $;
DynamicJS.init();

Atrybuty danych

Kontenery treści

Atrybut	Opis	Przykład
`data-dyn-load`	Automatycznie ładuje treść pod wskazany URL przy starcie lub na żądanie	`<div data-dyn-load="/news/latest">`
`data-dyn-target`	Wskazuje, który element ma zostać nadpisany wynikiem (ID lub selektor)	`<form data-dyn-target="#result">`
`data-dyn-transition`	Aktywuje efekt przejścia (`fade`, `slide`, `replace`)	`<div data-dyn-transition="fade">`
`data-dyn-cache`	Cacheuje odpowiedź na określony czas (np. `30s`, `5m`)	`<div data-dyn-cache="2m">`
`data-dyn-reload`	Lista selektorów, które powinny się przeładować po sukcesie	`<div data-dyn-reload="#cart,#summary">`

Interakcje użytkownika

Atrybut	Co robi	Kiedy używać
`data-dyn-link`	Zastępuje zwykły link, wykonuje AJAX i podstawia wynik do celu	Nawigacja w obrębie widoku bez przeładowania strony
`data-dyn-load` + `data-dyn-url`	Przycisk lub dowolny element może wskazać ręczny adres do pobrania treści	CTA, filtry, zakładki
`data-dyn-submit`	Przechwytuje formularz i wysyła go AJAX-em	Logowanie, newslettery, wyszukiwarki
`data-dyn-change`	Wywołuje ładowanie przy zmianie wartości input/select	Panele filtrów, konfiguratory
`data-dyn-input`	Łączy się z debounce (domyślnie 600ms) dla inputów tekstowych	Live-search, sugestie

Pooling i lazy loading

Atrybut	Opis	Wartości
`data-dyn-poll`	Włącza cykliczne odpytywanie endpointu	np. `10s`, `1m`
`data-dyn-poll-stop`	Warunek zatrzymujący polling (po otrzymaniu statusu)	`selector` lub `jsonPath`
`data-dyn-lazy`	Ładuje treść dopiero, gdy element znajdzie się w viewport	`true` / `offset:200`

Zdarzenia i hooki

DynamicJS emituje customowe zdarzenia na dokumencie oraz na konkretnych elementach docelowych.

Zdarzenie	Kiedy jest wywołane	Przykładowe użycie
`dyn:beforeSend`	Tuż przed wysłaniem requestu	`document.addEventListener('dyn:beforeSend', (e) => ...);`
`dyn:afterLoad`	Po udanym wczytaniu odpowiedzi	Aktualizacja modułów UI, odświeżenie komponentów
`dyn:transition:start`	Gdy rozpoczyna się animacja przejścia	Blokowanie interakcji, start spinnerów
`dyn:transition:end`	Po zakończeniu animacji	Reaktywacja przycisków, emisja eventów analitycznych
`dyn:error`	Gdy request zakończy się niepowodzeniem	Obsługa powiadomień lub logowanie błędów

💡 Tip: Większość zdarzeń przekazuje w event.detail referencję do elementu źródłowego, celu oraz odpowiedzi AJAX. Wykorzystaj to do rozbudowanych integracji.

API JavaScript

Po załadowaniu pliku IIFE moduł udostępnia globalny obiekt window.DynamicJS. W wersji modułowej eksportowane są te same metody.

Najważniejsze metody

`DynamicJS.init(force?)`

Skanuje DOM i podpina zdarzenia. Jeśli force to true, usuwa wcześniejsze cache selectorów

`DynamicJS.loadContent(element, options?)`

Ręczne przeładowanie elementu z atrybutem data-dyn-load

`DynamicJS.submitForm(formElement)`

Manualna obsługa formularza

`DynamicJS.startPoll(element)`

Rozpoczyna cykliczne odpytywanie

`DynamicJS.stopPoll(element)`

Zatrzymuje polling dla danego elementu

`DynamicJS.clearCache(selector?)`

Czyści cache dla selektora lub całkowicie

Konfiguracja globalna

Możesz ustawić opcje globalne przez DynamicJS.configure({...}). Dostępne klucze to m.in. loadingClass, defaultTransition, cacheTtl.

window.DynamicJS.configure({
  loadingClass: 'is-loading',
  defaultTransition: 'fade',
  cacheTtl: '30s'
});

Diagnoza problemów

🔍 Brak reakcji na kliknięcie

Upewnij się, że element ma poprawny data-dyn-target albo znajduje się wewnątrz kontenera z data-dyn-load

🔗 Historia przeglądarki

Dodaj data-dyn-history="true", aby włączyć aktualizację adresu URL

💾 Cache się nie odświeża

Dodaj data-dyn-cache="0" lub wywołaj DynamicJS.clearCache(selector)

⚠️ Błędy 500

Wykorzystaj dyn:error, aby wyświetlać komunikaty w dedykowanym komponencie