Tutor LMS 4.x: panel instruktora rozjechany. Trzy przyczyny naraz

Logo zamienione w napis na trzy linijki i panel bez nagłówka

Klientka wchodzi do kokpitu instruktora na swojej platformie kursowej i widzi coś, co wygląda jak awaria. W miejscu logo stoi nazwa strony wielką czcionką, zawinięta na trzy linijki. Nad panelem nie ma nagłówka serwisu, pod nim stopki. Układ wygląda na połamany. Nic nie krzyczy błędem, a Site Health jest czysty.

Tak wyglądał panel instruktora Tutor LMS po aktualizacji do gałęzi 4.x. Pierwsza myśl: coś rozjechało się w CSS. Druga: aktualizacja coś zepsuła i trzeba wrócić do starej wersji. Obie były złe. Za jednym objawem stały trzy niezależne przyczyny – i każda z nich wymagała innej poprawki.

Kontekst: panel, w którym instruktorka pracuje codziennie

Platforma działa na WordPressie z Tutor LMS w wersji darmowej i Pro. Kokpit instruktora to miejsce, w którym klientka dodaje lekcje, sprawdza kursantów i odpowiada na pytania. Jeśli panel wygląda jak po wypadku, to nie jest problem estetyczny – to narzędzie pracy, którego właścicielka zaczyna się bać, i realny koszt, bo każda kolejna zmiana na platformie robiona jest „na ślepo”.

Tutor LMS 4.0 przepisał panel od zera. Nowy wygląd, nowe opcje, nowe komponenty. Aktualizacja z gałęzi 3.x na 4.x nie jest więc zwykłym podbiciem wersji, tylko przesiadką na inny panel. I tak trzeba ją traktować.

Diagnoza: gdzie szukaliśmy i dlaczego pierwszy trop był zły

Ślepa uliczka 1: CSS motywu potomnego

Pierwszy odruch: motyw potomny ma swoje style, aktualizacja zmieniła klasy, więc nasze reguły trafiają w złe miejsca. Przejrzeliśmy arkusze i nic tam nie tłumaczyło tekstu wielkości nagłówka w miejscu logo. Każda „łatka” w CSS byłaby tu przykrywaniem objawu.

Ślepa uliczka 2: „wtyczki są zgodne, bo Site Health milczy”

Tutor Pro ma stałą minimalnej wymaganej wersji wtyczki darmowej. Na stronie stały obok siebie Tutor Free 4.0.7 i Tutor Pro 3.9.9, a Pro 3.9.9 deklarował minimum 3.9.9. Formalnie warunek był spełniony, więc nic nie zgłaszało niezgodności. W praktyce para była niezgodna.

Moment odkrycia: trzy przyczyny jednego objawu

Dopiero gdy przestaliśmy szukać „jednego winnego”, obraz się złożył. Panel nie był zepsuty w jednym miejscu. Nakładały się na siebie trzy rzeczy.

Przyczyna 1: Free i Pro z różnych gałęzi

Tutor Free 4.0.7 z nowym panelem i Tutor Pro 3.9.9 ze starymi modułami. Pro wstrzykiwał elementy przygotowane pod panel, którego już nie było. Stąd część połamanych bloków.

Przyczyna 2: logo zapisane pod starym kluczem

Tutor 4.x czyta logo panelu z nowych opcji brand_logo_light i brand_logo_dark w tutor_option. Stara opcja tutor_frontend_course_page_logo_id zostaje tylko jako zapasowa. Gdy nowego klucza nie ma, komponent logo wstawia w to miejsce nazwę witryny jako tekst. Duża czcionka w wąskim slocie, zawijanie na trzy linie – i mamy wrażenie zepsutego układu, choć brakuje jednej opcji.

Osobna pułapka czekała na stronach klonowanych z szablonu: stara opcja logo wskazywała ID załącznika z szablonu, którego na nowej stronie po prostu nie ma. Przepisanie takiego ID do nowych kluczy niczego nie naprawi. Najpierw trzeba sprawdzić, czy załącznik istnieje.

Przyczyna 3: brak nagłówka i stopki to nowa norma, nie awaria

Panel 4.x domyślnie startuje w trybie pełnoekranowym, bez nagłówka i stopki motywu. To decyzja autorów, nie błąd. Przełączniki to show_dashboard_site_header i show_dashboard_site_footer w tej samej opcji tutor_option.

Jeśli Twoja platforma ma kokpit z nagłówkiem serwisu, a po aktualizacji nagle go nie ma, nie szukaj błędu w motywie. Sprawdź te dwie opcje.

Rozwiązanie: kolejność ma znaczenie

Paczka Pro wymaga wersji darmowej co najmniej równej swojej. Dlatego najpierw aktualizujemy Free, potem Pro, a dopiero na końcu opcje.

Zanim cokolwiek zmienisz, zrób kopię strony. Potem sprawdź stan przez WP-CLI:

# 1. Wersje pary Free/Pro - mają być z tej samej gałęzi (np. 4.0.x i 4.0.x)
wp plugin list --fields=name,version,status | grep -i tutor

# 2. Opcje logo i nagłówka panelu
wp eval '$o = get_option("tutor_option");
foreach (["brand_logo_light","brand_logo_dark","tutor_frontend_course_page_logo_id",
  "show_dashboard_site_header","show_dashboard_site_footer"] as $k)
  echo $k, ": ", $o[$k] ?? "BRAK", "\n";'

# 3. Czy załącznik logo w ogóle istnieje (ID podmień)
wp post get 123 --field=guid

Gdy wersje są już zgodne, a załącznik logo istnieje, ustawiamy brakujące opcje. 123 to ID załącznika z logo:

wp eval '$o = get_option("tutor_option");
$o["brand_logo_light"] = 123;
$o["brand_logo_dark"]  = 123;
$o["show_dashboard_site_header"] = 1;
$o["show_dashboard_site_footer"] = 1;
update_option("tutor_option", $o);'
wp cache flush

Prowadzisz platformę na Tutor LMS i boisz się kliknąć „Aktualizuj”? Taką przesiadkę robimy najpierw na kopii, a na żywej stronie dopiero wtedy, gdy panel wygląda dobrze. Napisz, na jakiej wersji jesteś – powiemy, co Cię czeka.

Wątek dodatkowy: polskie tłumaczenie panelu 4.x

Po naprawie panel działał, ale część napisów była po angielsku. Oficjalna paczka pl_PL z repozytorium WordPressa nie zawierała w chwili naprawy ani jednego nowego tekstu panelu 4.x – nikt ich jeszcze nie przetłumaczył. Generowanie tłumaczenia od zera dla każdej klientki to strata czasu. My utrzymujemy pełne tłumaczenie u siebie i przenosimy je na kolejne platformy, zamiast pisać je za każdym razem od nowa.

Efekt: panel wrócił, a walidator złapał to samo jeszcze dwa razy

Po sześciu krokach panel instruktorki wrócił do normalnego układu: logo w swoim miejscu, nagłówek i stopka serwisu, polskie napisy.

Ważniejsze było jednak to, co zostało po tej naprawie. Spisaliśmy wszystkie trzy przyczyny w walidator, który tylko czyta stan strony: porównuje gałęzie Free i Pro, sprawdza obecność kluczy brand_logo_* i ustawienia nagłówka panelu. Przy pierwszym uruchomieniu na innych naszych instalacjach od razu znalazł ten sam błąd na dwóch kolejnych – w tym na wersji demonstracyjnej, którą pokazujemy na spotkaniach. Bez walidatora dowiedzielibyśmy się o tym od klienta albo, co gorsza, w trakcie prezentacji.

Jak sprawdzić u siebie przed aktualizacją do 4.x

1. Sprawdź wersje Tutor Free i Tutor Pro. Mają być z tej samej gałęzi – nie wystarczy, że Site Health milczy.
2. Aktualizuj najpierw Free, potem Pro. Nigdy odwrotnie.
3. Po aktualizacji sprawdź brand_logo_light i brand_logo_dark w tutor_option.
4. Upewnij się, że ID logo wskazuje istniejący załącznik, zwłaszcza na stronie z klonu.
5. Zdecyduj świadomie, czy panel ma mieć nagłówek i stopkę serwisu – i ustaw dwa przełączniki.
6. Sprawdź, czy panel mówi po polsku. Jeśli nie, potrzebujesz pełnego tłumaczenia panelu 4.x.
7. Obejrzyj panel w przeglądarce jako instruktor i jako kursant. Kod HTTP 200 nie mówi nic o wyglądzie.

Szerzej o tym, co powinien umieć dobry panel kursanta i instruktora, piszemy w poradniku o funkcjach platformy kursowej.

Czego nauczyła nas ta historia

Przy dużej aktualizacji jeden objaw rzadko ma jedną przyczynę. Naprawianie „po kolei, aż przestanie” kończy się serią łatek, z których każda przykrywa coś innego. Dziś przed każdą aktualizacją głównej wersji uruchamiamy walidator, a dopiero potem oglądamy panel – i nie łatamy CSS, dopóki nie wiemy, czy problem w ogóle istnieje w nowej wersji.

FAQ

Dlaczego po aktualizacji Tutor LMS zamiast logo widzę nazwę strony?

Tutor 4.x czyta logo panelu z opcji brand_logo_light i brand_logo_dark. Jeśli ich nie ma albo wskazują nieistniejący załącznik, panel wstawia nazwę witryny jako tekst. Wystarczy ustawić ID istniejącego logo w obu kluczach.

Czy mogę mieć Tutor Free 4.x i Tutor Pro 3.9?

Technicznie wtyczki się włączą i nic nie zgłosi błędu, ale panel będzie składany z dwóch różnych generacji kodu. Przy przejściu na 4.x obie wtyczki powinny pochodzić z tej samej gałęzi.

Gdzie zniknął nagłówek strony w panelu instruktora?

Panel 4.x domyślnie działa w trybie pełnoekranowym. Nagłówek i stopkę motywu włączysz opcjami show_dashboard_site_header i show_dashboard_site_footer.

W jakiej kolejności aktualizować Tutor LMS i Tutor Pro?

Najpierw wersję darmową, potem Pro z tej samej gałęzi. Paczka Pro wymaga wersji darmowej co najmniej równej swojej, więc odwrotna kolejność kończy się odmową albo rozjazdem.

Dlaczego panel jest częściowo po angielsku mimo polskiego języka strony?

Oficjalne polskie tłumaczenie nie obejmowało nowych tekstów panelu 4.x. Trzeba je uzupełnić własnym tłumaczeniem albo przenieść z instalacji, która je ma.

Czy da się to sprawdzić bez klikania po panelu?

Tak. Trzy komendy WP-CLI z tego artykułu pokazują wersje wtyczek i wszystkie istotne opcje. My zebraliśmy je w jeden walidator, który uruchamiamy przed każdą aktualizacją.