Modyfikacja interfejsu Comarch ERP XL Web
W systemie Comarch ERP XL Web dostępny jest mechanizm, który pozwala Klientom samodzielnie modyfikować wygląd oraz działanie interfejsu użytkownika. Rozszerzenia Hydry pisze się w języku JavaScript i wpina do interfejsu bez ingerencji w kod źródłowy aplikacji.
Zasada działania
Każdy komponent interfejsu podczas swojego cyklu życia wywołuje dwie metody — jedną przy tworzeniu komponentu i jedną przy jego niszczeniu. Wpinając własne funkcje do tych metod, można dowolnie modyfikować dokument z wykorzystaniem modelu DOM, a w szczególności:
- tworzyć własne kontrolki,
- modyfikować kontrolki już istniejące,
- reagować na zdarzenia przeglądarki i wykonywać własne akcje.
Dostępny jest również globalny obiekt store, zawierający dane takie jak zalogowany operator czy aktualne centrum.
Do interakcji z bazą danych zalecane jest korzystanie z istniejącego RestAPI systemu lub tworzenie własnych serwisów z własnym połączeniem do bazy danych.
Miejsce wpięcia dodatków
Punktem wejścia dla rozszerzeń jest skrypt Hydra.js znajdujący się w katalogu z dystrybucją Comarch ERP XL Web. To w nim udostępnia się dwie funkcje wywoływane przez interfejs:
- CallbackOnInit(componentName) — wywoływana podczas tworzenia komponentu,
- CallbackOnDestroy(componentName) — wywoływana podczas niszczenia komponentu.
Parametr componentName zawiera nazwę komponentu, dzięki czemu można uzależnić wykonywane operacje od konkretnego okna lub widoku.
Skrypty dodatków warto podzielić na poszczególne komponenty i umieścić w podkatalogu AddOns.
Przykłady
Hydra.js
Przeciążenie metody CallbackOnInit i uruchamianie dodatków w zależności od nazwy komponentu (np. komponentu logowania oraz strony startowej): import { LoginAddOns } from “./AddOns/Login.js”; import { DashboardAddOns } from “./AddOns/Dashboard.js”; window.CallbackOnInit = CallbackOnInit; window.CallbackOnDestroy = CallbackOnDestroy; function CallbackOnInit(componentName) { switch (componentName) { case “LoginComponent”: LoginAddOns(); break; case “DashboardComponent”: DashboardAddOns(); break; } } function CallbackOnDestroy(componentName) {}
AddOns/Login.js
Przykładowe operacje na kontrolkach komponentu logowania — modyfikacja istniejącego przycisku, dodanie własnych kontrolek, obsługa zdarzeń oraz warunkowe blokowanie logowania:
export function LoginAddOns() {
// modyfikacja istniejących kontrolek
var loginBtn = window.document.getElementById(“login-login-btn”);
loginBtn.style.background = “green”;
// dodawanie kontrolki
var newButton = document.createElement(“button”);
newButton.appendChild(document.createTextNode(“Hydra”));
loginBtn.parentElement.appendChild(newButton);
newButton.classList.add(“cds-button-primary”);
newButton.setAttribute(“cdsbutton”, “”);
// dodawanie kontrolki
var newHideButton = document.createElement(“button”);
newHideButton.appendChild(document.createTextNode(“Ukryj”));
loginBtn.parentElement.appendChild(newHideButton);
newHideButton.classList.add(“cds-button-primary”);
newHideButton.setAttribute(“cdsbutton”, “”);
// zdarzenia
newButton.addEventListener(“click”, (event) => {
window.location.href = “AddOns/HydraPage.html”;
});
newHideButton.addEventListener(“click”, (event) => {
if (loginBtn.style.display == “none”) {
loginBtn.style.display = “inline-flex”;
} else {
loginBtn.style.display = “none”;
}
});
// zablokuj logowanie po anulowaniu na oknie z pytaniem
document.addEventListener(“click”, (ev) => {
if (ev.target.id == loginBtn.id) {
if (window.confirm(“Czy na pewno chcesz się zalogować?”) != true) {
ev.preventDefault();
ev.stopPropagation();
}
}
}, true);
}
Dokumentacja Comarch ERP XL Web RestAPI — jak uzyskać do niej dostęp
Wraz z wersją 2026.0 systemu Comarch ERP XL Web udostępniona została dokumentacja interfejsu RestAPI. Dokumentacja ta nie jest dystrybuowana w postaci klasycznego podręcznika (instrukcji) — jest generowana automatycznie w standardzie OpenAPI (Swagger) bezpośrednio z serwisów systemu. Dzięki temu zawsze odpowiada wersji API, z której faktycznie korzysta użytkownik. Dostęp do niej można uzyskać na dwa sposoby.
Dokumentacja online (Swagger UI)
Każdy mikroserwis RestAPI udostępnia własną, interaktywną dokumentację pod endpointem /swagger. Aby ją otworzyć, wystarczy po uruchomieniu serwisu przejść w przeglądarce pod adres:
https://<adres_serwera>:<port>/swagger
Przykład: https://localhost:61558/swagger
Port (w przykładzie 61558) wskazuje na konkretny mikroserwis — np. XL.Orders — dzięki czemu pod tym adresem wyświetli się dokumentacja odpowiadająca danemu obszarowi (np. zamówieniom). Analogicznie, uruchamiając pozostałe mikroserwisy, uzyskuje się dostęp do dokumentacji kolejnych obszarów systemu.
W widoku Swagger UI można przeglądać dostępne zasoby (endpointy), parametry, modele danych oraz kody odpowiedzi, a także testowo wywoływać poszczególne operacje.
Dokumentacja offline (plik YAML)
Dla każdego mikroserwisu dokumentacja jest dodatkowo generowana w trakcie kompilacji w postaci pliku YAML (format OpenAPI). Plik trafia do podkatalogu swagger danego serwisu, np.:
C:\Program Files\Comarch ERP XL Web 2026.0\XLRestAPI\Orders\swagger\XL_Orders,yaml
(\\<serwer>\XLRestAPI\Orders\swagger\XL.Orders.yaml)
Definicję YAML można również pobrać bezpośrednio z uruchomionego serwisu pod adresem:
https://<adres_serwera>:<port>/swagger/v2026.0/swagger.yaml
Aby wyświetlić dokumentację w czytelnej, graficznej postaci, wystarczy zaimportować pobrany plik YAML na stronie edytora Swagger: https://editor.swagger.io/
Po wczytaniu pliku (menu File → Import file) dokumentacja zostanie wyświetlona w takiej samej, interaktywnej formie jak w wariancie online.