Backend witryny (dynamiczne procedury obsługi)
Oprócz plików statycznych przesłana witryna może mieć prawdziwy backend — niewielkie procedury obsługi w języku JavaScript powiązane z poszczególnymi adresami. Każda procedura jest związana ze ścieżką i metodą HTTP; gdy odwiedzający otwiera ten adres, Qubix uruchamia procedurę i zwraca to, co ona zbuduje — stronę, odpowiedź JSON, przekierowanie lub kod stanu.
Proszę używać tej możliwości, gdy strona musi coś zrobić na serwerze, a nie tylko pokazać statyczną treść: przyjąć lead przez żądanie POST, odpowiedzieć na konkretną ścieżkę wygenerowanym HTML lub wysłać przekierowanie zależne od żądania. Do zwykłych statycznych whitepage'ów i landingów nie jest to potrzebne — proszę zostawić zakładkę Backend pustą, a witryna zostanie obsłużona jako zwykłe pliki.
Otwarcie zakładki Backend
Karta witryny ma u góry trzy zakładki: Pliki, Backend i Podgląd. Aktywna zakładka jest zapisywana w pasku adresu, więc można skopiować link bezpośrednio do konkretnej zakładki.
- Proszę otworzyć sekcję «Witryny» i kliknąć potrzebną witrynę.
- Proszę przełączyć się na zakładkę Backend.
Jeśli witryna nie ma jeszcze żadnych procedur, na liście pokazywana jest wskazówka, że «+ nowy» tworzy jedną z szablonu.
Zakładka Backend jest potrzebna tylko wtedy, gdy strona musi coś przetworzyć na serwerze. Strona czysto statyczna działa bez żadnych procedur.
Utworzenie procedury
- Na zakładce Backend proszę kliknąć «+ nowy» w lewym górnym rogu, nad listą procedur. Nowa procedura zostaje utworzona z gotowego szablonu i otwiera się w edytorze.
🎬 GIF: kliknięcie «+ nowy» i otwarcie procedury z szablonu w edytorze
- W formularzu nagłówka nad edytorem proszę ustawić ścieżka — adres, na który procedura odpowiada. Pole przyjmuje szablon z symbolami zastępczymi (na przykład
/users/:id)::name— przechwytuje jeden segment ścieżki (na przykład:idw/users/:idpasuje do/users/42);*— przechwytuje resztę ścieżki obejmującą kilka segmentów;**— pasuje do reszty ścieżki, ale jej nie przechwytuje.
- Proszę wybrać metodę —
GET,POST,PUT,DELETE,PATCH,HEAD,OPTIONSlub ANY (odpowiada na dowolną metodę). - Proszę zostawić zaznaczone pole Wł., aby procedura działała na żywej witrynie. Proszę je odznaczyć, aby procedura pozostała zapisana, lecz nieaktywna.
- W edytorze na środku proszę napisać kod procedury (zob. Kod procedury poniżej).
- Proszę kliknąć Zapisz (lub Cmd+S, w systemie Windows — Ctrl+S).
Na liście po lewej każda procedura jest pokazywana jako jej metoda i ścieżka (procedura bez ustawionej metody jest pokazywana jako ANY); wyłączona jest odpowiednio oznaczona.
Jeśli ten sam adres mogłaby obsłużyć więcej niż jedna procedura, Qubix wybiera najbardziej szczegółową — procedura z dokładną ścieżką wygrywa z tą, która ma symbol zastępczy lub wildcard. Dzięki temu można trzymać precyzyjną procedurę obok szerokiej procedury zbiorczej bez konfliktu między nimi.
Kod procedury
Procedura to funkcja JavaScript, która otrzymuje obiekt żądania — proszę nazwać go r — udostępniający żądanie (metoda, ścieżka, argumenty zapytania i formularza, nagłówki, przechwycone segmenty ścieżki) oraz odpowiedź (ustawienie nagłówków, zwrócenie stanu z treścią lub przekierowanie). Szablon, od którego zaczyna edytor, pokazuje już typowy kształt.
Edytor to pełnoprawny edytor kodu z podświetlaniem składni i autouzupełnianiem: proszę zacząć wpisywać r., a Qubix podpowie dostępne pola żądania i odpowiedzi wraz z ich opisami, dzięki czemu nie trzeba trzymać ich w pamięci.
Wewnątrz procedury ma Pan/Pani także wspólny zestaw narzędzi Qubix: zapytania do bazy danych tylko do odczytu, żądania do usług zewnętrznych oraz stan, który utrzymuje się między wywołaniami. Działają one tak samo jak w Skryptach — szczegóły znajdują się w tym artykule. Żądania wychodzące są dozwolone tylko do adresów, które administrator umieścił na liście dozwolonych. Które tabele i kolumny są dostępne w zapytaniu, opisano w artykule Tabele dla zapytań sql.
Dokumentacja obiektu r
Wszystko, co procedura odczytuje z żądania i wykorzystuje do budowania odpowiedzi.
Odczyt żądania:
| Pole | Co to jest |
|---|---|
r.method | Metoda HTTP żądania (GET, POST, …) |
r.uri | Adres, na który procedura odpowiedziała (na przykład /promo/123) |
r.rawUri | Pełny adres zewnętrzny, wraz z prefiksem serwisowym |
r.args | Parametry adresu i formularza (klucz → wartość) |
r.params | Wartości przechwycone z szablonu ścieżki (na przykład id z /users/:id) |
r.requestBuffer | Treść żądania jako ciąg znaków |
r.headersIn | Nagłówki żądania |
r.remoteAddress | Adres IP odwiedzającego |
r.variables | Kontekst kliknięcia: geo, click_id, sub1…sub5, lang |
r.session | Sesja odwiedzającego: get(key), set(key, value), delete(key) |
Budowanie odpowiedzi:
| Pole / metoda | Działanie |
|---|---|
r.headersOut | Nagłówki odpowiedzi (można je ustawiać i usuwać) |
r.return(status, body?, location?) | Wysyła odpowiedź; location to adres przekierowania |
r.log(...), r.warn(...), r.error(...) | Zapisuje do logu uruchomienia (widoczny w narzędziu do testów) |
Pomocniki kryptograficzne
Procedura ma również pomocniki kryptograficzne:
| Metoda | Co robi |
|---|---|
crypto.uuid() | Losowy identyfikator |
crypto.hmac(algo, key, data) | HMAC danych data z kluczem key, zakodowany szesnastkowo; algo to 'sha256', 'sha1' lub 'md5' |
Przydatne na przykład do podpisywania danych przed wysłaniem do zewnętrznej usługi przez fetch.
Testowanie procedury
Każda procedura ma po prawej stronie edytora wbudowane narzędzie do testów — proszę wysłać testowe żądanie i zobaczyć dokładnie, co procedura odpowiada, bez ingerencji w żywą witrynę.
- Proszę wybrać metodę i wpisać ścieżka do przetestowania (na przykład
/users/42). - (Opcjonalnie) Proszę wypełnić dane wejściowe żądania:
- Zapytanie (JSON) — parametry zapytania jako obiekt JSON;
- Treść (raw) — surowa treść żądania;
- geo i click_id — wartości przekazywane do procedury jako zmienne żądania.
- Proszę kliknąć Uruchom.
Wynik pojawia się poniżej:
- status odpowiedzi (oznaczony kolorem zielonym / niebieskim / czerwonym) oraz czas trwania uruchomienia;
- parametry — wartości przechwycone z szablonu ścieżki;
- Przekierowanie — cel przekierowania, jeśli procedura je ustawiła;
- nagłówki i treść odpowiedzi;
- konsola — wszystko, co procedura zarejestrowała podczas uruchomienia.
Jeśli żądanie sięga zapisanego stanu procedury lub go zmienia, panel oznacza także sesja jako naruszoną.
Zapytanie (JSON) musi być prawidłowym JSON-em. Jeśli nie jest, test się nie uruchomi, a pole zostanie podświetlone — proszę poprawić JSON i ponownie kliknąć Uruchom.
Edycja plików witryny
Druga połowa karty to zakładka Pliki — statyczne pliki witryny (HTML, CSS, JS, obrazy, czcionki) w drzewie po lewej oraz edytor kodu po prawej. Pliki tekstowe otwierają się z podświetlaniem składni; zapis za pomocą Zapisz lub Cmd+S (w systemie Windows — Ctrl+S). Obrazy, wideo, audio i inne pliki otrzymują podgląd lub pobieranie. Można przeciągać pliki między folderami i upuszczać nowe ze swojego komputera.
Pełne omówienie zakładki Pliki znajduje się w artykułach Witryny oraz Przesyłanie witryny.
Uwagi o polach i zachowaniu
ścieżka — szablon adresu, na który procedura odpowiada. Obsługuje :name (jeden segment), * (reszta, przechwytywana) oraz ** (reszta, nieprzechwytywana). Przechwycone segmenty są dostępne dla procedury i pokazywane jako parametry w narzędziu do testów.
metoda — która metoda HTTP wyzwala procedurę. ANY odpowiada na każdą metodę.
Wł. — czy procedura działa na żywej witrynie. Wyłączona procedura pozostaje zapisana, ale jest pomijana.
«+ nowy» — tworzy procedurę z wbudowanego szablonu, gotową do edycji.