Pomoc:Jak dodać TemplateData

Dla ekspertów

TemplateData – zapis, który pozwala przechowywać informacje o szablonach i ich parametrach w taki sposób, aby VisualEditor mógł je pobrać i wyświetlić w edytorze szablonów, ułatwiając tym samym ich edycję.

TemplateData pozwala użytkownikom na tworzenie małych struktur danych na stronie szablonu lub załączonej do niego strony (np. podstrony dokumentacji). Szablon będzie wyświetlany poprawnie w edytorze wizualnym, gdy będzie posiadał tę strukturę. Być może brzmi to skomplikowanie, ale w praktyce jest bardzo proste.

Uwaga: przeciętny użytkownik VE niekoniecznie zna techniczny język wiki, natomiast widzi „pola” (technicznie: parametry), które ma wypełnić treścią (d. wartościami). Pamiętajmy więc, by wypełniając TemplateData, używać zrozumiałych dla użytkownika nazw.

<templatedata>
{
        ...                            <-- miejsce na treść TemplateData
}
</templatedata>

<templatedata>
{
        "description": "Szablon do linkowania kategorii w serwisie Commons powiązanej z artykułem",
        "params": {
                "1": {
                        "label": "kategoria Commons",
                        "description": "Kategoria Commons, do której chcesz linkować",
                        "default": "Category:CommonsRoot",
                        "type": "string",
                        "required": true
                }
        }
}
</templatedata>

Pierwszą właściwością jest "description", opisujący, co szablon robi.

"description": "Szablon do linkowania kategorii w serwisie Commons powiązanej z artykułem",

Następnie jest właściwość "params", w którym kolejne podsekcje będą odpowiadać parametrom z szablonu.

Wszystkie parametry występujące w szablonie powinny być zawarte w tej sekcji.

"params": {
     ...            <-- miejsce na parametry
}

Nazwy właściwości (klucze) w sekcji params, muszą odpowiadać nazwą parametrów szablonu. To musi być dokładnie ta sama nazwa zmiennej co w szablonie. Aczkolwiek do powiązanych parametrów można potem dodać aliasy (synonimy), nie trzeba opisywać każdego osobno. Zwłaszcza gdy parametr ma wersję nazwaną i numeryczną.

Jeśli parametr ma nazwę, np. {{{kategoria-link}}}, to klucz mu odpowiadający powinien przyjąć formę "kategoria-link".

W przypadku parametrów numerycznych, czyli gdy przybiera on postać cyfry jak chociażby {{{1}}}, postępujemy analogicznie do nazwanych, czyli w tym przypadku kluczem będzie "1".

Wszystkie właściwości parametru są zawarte w podsekcji zaczynającej się od jego nazwy.

"1": {              <-- nazwa parametru
     ...            <-- miejsce na informacje o parametrze
},
"powód": {          <-- nazwa parametru
     aliases": ["2", "powody"],	<-- aliasy/synonimy parametru
     ...            <-- miejsce na informacje o parametrze
},
"kategoria-link": { <-- nazwa parametru
     ...            <-- miejsce na informacje o parametrze
}

Należy pamiętać o przecinkach pomiędzy parametrami. Bez przecinków podgląd pokaże błędy w JSON.

Kolejnym elementem jest "label". Odpowiada on za etykietę parametru, która będzie służyła tylko jako tytuł do wyświetlenia w edytorze szablonu.

"label": "kategoria Commons",

Ponownie natrafiamy na "description", jednak tym razem odpowiada on za opis pojedynczego parametru, a nie całego szablonu.

"description": "Kategoria Commons, do której chcesz linkować.",

Wartość automatyczna. Opcja "autovalue" mówi Edytorowi Wizualnemu i innym narzędziom, aby wypełniały ten parametr standardową wartością (w wikitekście); ten tekst pojawi się w polu wartości parametru, gdy użytkownik będzie edytować i zostanie dodany do wywołania szablonu po zapisaniu. Przydatne w szablonach sprzątania do automatycznego ustawienia daty, kiedy użytkownik dodaje szablon. Na przykład, dodaj "{{subst:CURRENTMONTHNAME}} {{subst:CURRENTYEAR}}" jako autovalue, aby mieć dodany "grudzień 2016" automatycznie (przykładowa edycja). Autowartości mogą być zmieniane przez edytującego po prostu przez usunięcie wstawionej wartości w oknie edycji szablonu. Uwaga! Substy nie działają dla szablonów, które są użyte wewnątrz tagów przypisów (<ref>), tagów galerii i innych tagów zależnych od rozszerzeń.</nowiki>

"autovalue": "{{subst:CURRENTMONTHNAME}} {{subst:CURRENTYEAR}}",

Domyślnie (pl). Opcja "default" pozwala pokazać, co szablon zrobi, kiedy parametr nie będzie ustawiony (lub ustawiony jako pusty); ten tekst pokaże się jako jasno szary w polu wartości parametru, kiedy użytkownik będzie edytować, lecz nie doda wartości do wywołania szablonu, dopóki użytkownik ręcznie go nie nadpisze.

Uwaga! Wartość wpisana jako default nie ma żadnego realnego wpływu na działanie edycji. To jest tylko dokumentacja zachowania szablonu.

Jeśli chcesz wymusić dodanie jakiegoś parametru, to użyj zamiast tego autovalue.

"default": "Category:CommonsRoot",

"suggestedvalues": [ "XS", "S", "M", "L", "XL" ]

Po dodaniu sugerowanych wartości do danych szablonu Edytor Wizualny wyświetli je w menu rozwijanym typu combobox (lista rozwijana, w której użytkownicy mogą również wprowadzić wartość niestandardową). Jeśli lista wartości jest długa, to będzie możliwość odfiltrowania jej przez rozpoczęcie wpisywanie wartości.

Właściwość "type" odpowiada za sposób, w jaki edytor będzie interpretował parametr. Domyślnym typem jest "unknown" (nieznany).

Zachowanie edytorów w praktyce można przetestować wstawiając szablon {{Przykład TemplateData}}.

Typy tekstowe:

• "string" (Ciąg znaków): raczej krótki tekst, choć może zawierać nowe linie.
• "line" (Linia): raczej krótki tekst bez wielu linii.
• "content" (Treść): zawartość strony w formie wikikodu. Można oczekiwać, że edytor takiego parametru będzie będzie dostosowany do wprowadzania długiego, wielowierszowego tekstu. Jednak na 2022 różnice między string i content są raczej subtelne.
• "unbalanced-wikitext" (Niezbalansowany wikitekst): fragment wikikodu, który może być podzielony na parę parametrów itp. Np. tag otwierający i zamykający mogłyby być w różnych parametrach szablonu:|start=<u> |koniec=</u> . To pole jest podobne do content, ale można się spodziewać innej walidacji w przyszłości.

Typy z podpowiedziami:

• "wiki-page-name" (Nazwa strony): nazwa strony na Wikipedii (nie musi istnieć w tej chwili, ale powinno być prawidłowym tytułem strony).
• "wiki-file-name" (Plik): nazwa pliku (na Wikimedia Commons lub z Wikipedii). Plik zostanie wpisany bez nazwy przestrzeni. Np. „Example.jpg”.
• "wiki-user-name" (Użytkownik): nazwa wikipedysty(-ki).
• "wiki-template-name" (Szablon): nazwa szablonu.

Pozostałe typy:

• "number" (Liczba): wartość numeryczna całkowita (bez przecinków czy kropek).
• "boolean" (Wartość logiczna): „1”, „0” lub brak wypełnienia.
• "date" (Data): data i ew. godzina w formacie ISO, np. „2022-05-29” albo „2022-05-29T16:34:56Z”.
• "url" (URL): adres strony internetowej itp. Musi zawierać protokół np. „http://www.example.org”, „https://example.org”, albo ew. „//example.org”.

Przykład:

"type": "string",

Właściwość "required", może przyjąć wartość true lub false. Domyślną wartością jest false.

Odpowiada on za określenie, czy dany parametr musi zostać użyty w szablonie. Tego określenia powinno się używać wyłączenie dla parametrów bez których szablon nie działa poprawnie lub ich podanie byłoby nielogiczne. Szablony w większości powinny automatycznie ukrywać puste parametry, więc większość parametrów nie powinna być wymagana.

VE będzie ostrzegać użytkowników o tym, że parametry nie są wypełnione i będzie utrudniać zapisanie zmian.

"required": true

Podobnie "suggested", może przyjąć wartość true albo false. Domyślną wartością jest false.

Jest to właściwość dla parametrów, które nie są wymagane, lecz zalecone jako wyjątkowo użyteczne. Spowoduje to dodanie parametru do listy parametrów przy edycji szablonu bez konieczności ich dodawania oraz do wygenerowanego wikikodu wstawiającego szablon, nawet gdy te pola będą puste. Jeżeli nie ustawisz wartości, domyślnie będzie false.

"suggested": true

Istnieje także właściwość "deprecated", określająca, że dany parametr jest zdeprecjonowany (nieaktualny), a podana tam wartość to parametr, który należy używać w zamian.

"deprecated": "informacja"

Po skończonej pracy należy wcisnąć „zapisz”. Schematu nie będzie można zapisać, jeśli w TemplateData pojawiły się jakieś błędy. Jest to uciążliwe, ale oznacza też, że nie nic nie zostanie zniszczone nieświadomie. W przypadku napotkania błędów, postaraj się wyjaśnić na tej stronie, jak do tego doszło, a my spróbujemy pomóc.

Zauważ, że każda informacja w TemplateData jest zamknięta obustronnie poprzez znak " (wyjątek stanowią true i false) i oddzielona od następnej przy użyciu przecinka (nie dotyczy to tylko ostatniej informacji).

        "params": {
                "kategoria": {
                        ...
                        "aliases": ["1", "link"]
                }

        "params": {
                "1": {
                        ...
                },                     <-- przecinek jest tutaj
                "2": {
                        ...
                },                     <-- i tutaj
                "3": {
                        ...
                }
        }

        "params": {
                "temat1": {
                        "label": "Temat",
                        "description": "Temat wymieniony na stronie ujednoznacznienia",
                        "type": "string"
                },
                "temat2": {
                        "inherits": "temat1"
                },
                "temat3": {
                        "inherits": "temat1"
                },
        }