VatoWiki:Brudnopisy i strony testowe szablonów
Szablony są bardzo potężnym narzędziem oprogramowania MediaWiki, ale podczas edycji błędy mogą być popełniane nawet przez doświadczonych użytkowników. Stąd też, aby uniknąć wystąpienia błędów podczas edycji, skomplikowane szablony powinny posiadać swoje brudnopisy, tzw. „piaskownice”. Obsługę tego typu podstron zapewnia szablon {{Dokumentacja}}, który w swojej stopce dołącza linki do brudnopisów i stron testowych szablonów, jeśli takie istnieją.
Dla jakiego rodzaju szablonów?
Zaleca się stosowanie stron testowych dla szablonów wykorzystujących funkcje parsera, przez które efekt wyjściowy szablonu może być bardzo różny, w zależności od podanych parametrów. Bezcelowym jest natomiast tworzenie stron testowych dla szablonów, które mają jednakowy wygląd niezależnie od sposobu ich zastosowania (np. szablony nawigacyjne, komunikaty).
Każdy szablon, który jest transkludowany na dużej ilości stron powinien być przetestowany przed naniesieniem zmian.
Jak utworzyć podstrony /brudnopis i /test?
- Założmy, że Twój szablon nosi nazwę
Szablon:X. Stwórz podstronę o nazwieSzablon:X/brudnopis. Możesz zrobić to z poziomu wyszukwiarki Wikipedii lub bezpośrednio z paska adresu przeglądarki internetowej. Zwróć uwagę że fraza „/brudnopis” pisana jest w całości małymi literami. - Skopiuj całą zawartość głównego szablonu, w tym tagi
<noinclude>i wywołanie szablonu {{Dokumentacja}} (jeśli istnieje), a następnie wklej skopiowaną treść do okna edycji podstrony /brudnopis, u góry umieść szablon {{Brudnopis szablonu}} i zapisz stronę. Opis edycji powinien krótko streścić tę zmianę, np. „utworzono brudnopis szablonu {{X}}”. - Jeśli zachodzi potrzeba utworzenia strony testowej, należy utworzyć podstronę
Szablon:X/test. Aby to zrobić, nazwę docelowej strony wpisz w wyszukwiarkę Wikipedii lub bezpośrednio do paska adresu przeglądarki internetowej. - Umieść u góry strony testowej szablon {{Strona testowa}} i dodaj przykłady wywołań opisywanego szablonu według instrukcji podanych w dalszej części tej strony.
- Aby przetestować jakąś zmianę, nanieś ją do podstrony
Szablon:X/brudnopis, zapisz ją, i porównaj oryginalny szablon z wersją z brudnopisu na testowej stronieSzablon:X/test. Często aby zobaczyć rezultat, konieczne będzie odświeżenie strony testowej. Można to zrobić przy użyciu przycisku znajdującego się w szablonie {{Strona testowa}}, podobnie jak można sprawdzić wygląd przykładów ze strony testowej w różnych skórkach, korzystając z innych linków w tym samym szablonie u góry strony. - Jeśli odświeżyłeś stronę testową, porównałeś efekt z brudnopisu z oryginalnym szablonem i wszystko wygląda dobrze, możesz nanieść zmiany do głównego szablonu. Pamiętaj jednak, że nawet gdy szablon działa poprawnie na stronie testowej, może wyglądać inaczej, np. w zależności od przestrzeni nazw.
Jak zaktualizować istniejący /brudnopis i podstronę /test?
Aby wprowadzić zmiany w już istniejących podstronach /brudnopis i /test, należy wykonać proces podobny do powyższego.
- Z czasem zawartość brudnopisu może przestać odzwierciedlać bieżącą wersję głównego szablonu, więc przed wykonaniem kolejnych eksperymentów, może zajść konieczność synchronizacji brudnopisu z bieżącym szablonem. Skopiuj całą zawartość podstrony /brudnopis i zapisz stronę z opisem zmian odzwierciedlającym zmianę (np. „synchronizacja z głównym szablonem” lub po prostu „synchr”).
- Baw się dobrze edytując brudnopis szablonu. Gdy chcesz przetestować jakiś kod, zapisz stronę.
- Jeśli dodałeś jakieś nowe funkcje lub zmieniłeś parametry szablonu, powinieneś dodać nowe przykłady na stronie testowej /test. Ponadto, należy pamiętać, że istniejące przypadki testowe mogą nie być kompletne. Dobrze jest przepisać przypadki testowe, jeśli nie są one przydatne dla tego, co próbujesz osiągnąć, ale należy również wziąć pod uwagę redaktorów, którzy mogą korzystać ze strony testowej po Tobie.
- Odśwież podstronę /test, aby zaktualizować przykłady.
- Sprawdź, czy wyniki przypadków testowych są prawidłowe. Jeśli wszystko wygląda dobrze, skopiuj kod z piaskownicy do głównego szablonu.
Tworzenie strony testowej
Na stronie testowej /test, powinien znaleźć się jeden przypadek testowy dla każdej możliwości zachowania się szablonu. Na przykład, jeśli Twój szablon wyświetla pewną wiadomość, a parametr | kursywa = tak powoduje, że komunikat wyświetlany jest pochyłą czcionką, powinieneś dodać jeden przypadek testowy dla wiadomości nieobjętej kursywą i objętej kursywą – w zależności od wartości parametru. Jeśli ten szablon posiada inny parametr, np. | data = , w którym użytkownik podaje pewną datę, powinien istnieć trzeci przypadek testowy demonstrujący działanie tego parametru. Należy zachować dokładność przy tworzeniu przypadków testowych, jako że użytkownicy mogą wykorzystywać Twój szablon na różnorakie sposoby; jednakże nie jest praktycznym dodawanie przypadków testowych dla każdej kombinacji pojedynczego parametru, należy więc mądrze wybrać najbardziej odpowiednie spośród nich.
Formatowanie automatyczne
Do formatowania stron testowych można wykorzystać szablon {{Przypadek testowy}}, który opiera się na module {{#invoke:Sprawdź}}, napisanym w Lua. Ten szablon w sposób automatyczny generuje tabelę stosowaną na stronach testowych szablonów, która zestawia obok siebie dwie wersje szablonów – szablon główny i jego wersję z brudnopisu. Szczegółowa instrukcja obsługi szablonu dostępna jest na jego stronie dokumentacji. Szablon umożliwia porównywanie wersji szablonu w różny sposób: obok siebie (rozwiązanie dobre dla szablonów infobox, mbox itp.) lub jeden pod drugim (np. dla szablonów cytowania lub jakichkolwiek generujących łańcuch tekstu). Można także ręcznie wymusić szablon, który będzie porównywany, co może być przydane przy porównywaniu brudnopisu szablonu z jego główną wersją poza stroną testową (np. podczas proponowania zmian w Kawiarence).
Formatowanie ręczne
W pewnych przypadkach koniecznym może się okazać jednak ręczne formatowanie strony testowej. Przykładowy schemat przedstawiono poniżej.
== Opisowy tytuł, np. („typ=test”, „test parametru typ” etc.) ==
* <code><nowiki>{{Szablon|param1=wart1|param2=wart2}}</nowiki></code>
'''Szablon'''
{{Szablon|param1=wart1|param2=wart2}}
'''Brudnopis szablonu'''
{{Szablon/brudnopis|param1=wart1|param2=wart2}}
Każda wartość szablonu Szablon, param1, wart1 itd. musi być identyczna dla wywołania szablonu, jak i jego brudnopisu.
Dla szablonów korzystających z artybutu „float” kaskadowych arkuszy stylów, konieczne będzie zastosowanie szablonu {{clear}} aby uniknąć błędnego wyświetlania rezultatów:
== Opisowy tytuł, np. („typ=test”, „test parametru typ” etc.) ==
* <code><nowiki>{{Szablon|param1=wart1|param2=wart2}}</nowiki></code>
'''Szablon'''
{{Szablon|param1=wart1|param2=wart2}}
{{clear}}
'''Brudnopis szablonu'''
{{Szablon/brudnopis|param1=wart1|param2=wart2}}
{{clear}}
Wikitabela
Jeśli konieczne jest formatowanie ręczne (występują problemy z wykorzystaniem szablonu {{Przypadek testowy}}), można użyć także tabeli do porównania szablonu z brudnopisem na stronie testowej. Przykładowa tabela może wyglądać tak:
{| class="wikitable"
|-
! Kod
! Szablon
! Brudnopis szablonu
Każdy nowy przypadek testowy powinien wyglądać tak:
|-
| <code><nowiki>{{Szablon|param1=wart1|param2=wart2}}</nowiki></code>
| {{Szablon|param1=wart1|param2=wart2}}
| {{Szablon/brudnopis|param1=wart1|param2=wart2}}
Tabelę należy zakończyć stosownym znakiem:
|}
Testy, których nie da się przeprowadzić na stronach testowych
Pewne funkcje szablonów nie mogą być przetestowane na podstronach /test. Przykładem może być taka funkcja szablonu, która wywołuje różny wynik w zależności od przestrzeni nazw, czy nazwy podstrony, na której szablon jest umieszczony. Dla tego rodzaju testów należy wykorzystywać funkcję „Podgląd strony z tym szablonem”, której interfejs znajduje się pod polem edycji kodu szablonu.
Jeśli uważasz, że pewne rodzaje testów nie mogą być przeprowadzone na podstronie testowej, pomocnym może być pozostawienie u góry strony testowej informacji o tych ograniczeniach – inni edytorzy będą o tym uprzedzeni i skorzystają z innych narzędzi do celów testowych.
Zobacz też
- Wikipedia:Szablony – ogólne informacje
- Wikipedia:Ograniczenia szablonów – informacje nt. ograniczeń oprogramowania MediaWiki dotyczących szablonów
- Wikipedia:Szablony wysokiego ryzyka