Pomoc:Jak dodać TemplateData

Skrót: WP:TD+
Z Wikipedii, wolnej encyklopedii
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.

Sposoby edycji TemplateData[edytuj | edytuj kod]

Aby edytować TemplateData, należy na stronie edycji dokumentacji szablonu nacisnąć przycisk Zarządzaj dokumentacją szablonu.

Można też ręcznie modyfikować lub tworzyć tag <templatedata> według instrukcji podanej poniżej, lub za pomocą wbudowanego edytora (powinien być do niego link na stronie dokumentacji szablonu). Ew. można posłużyć się edytorem TemplateData Michała Łazowika.

Struktura TemplateData[edytuj | edytuj kod]

Struktura TemplateData opiera się na standardzie JSON i jest dość prosta. Należy tylko pamiętać, że TemplateData musi być zapisywany samym tekstem (żadnego wikikodu, linków, itp.).

Pierwszym krokiem do stworzenia nowego szablonu jest zastosowanie dwóch znaczników <templatedata>, które należy wstawić w dowolnym miejscu na stronie dokumentacji szablonu. Ilustruje to poniższy przykład:

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

Znaczniki te poinformują oprogramowanie, że wszystko zawarte pomiędzy nimi należy do TemplateData i powinno się do nich odwoływać w trakcie korzystania z danego szablonu.

Przykład[edytuj | edytuj kod]

Treść zawarta między znacznikami ma zestandaryzowany zapis. Powiedzmy, że mamy szablon o nazwie „Commons”, który odwołuje się do kategorii na Commons powiązanej z danym artykułem. Szablon ten ma jeden obowiązkowy parametr: nazwę kategorii na Commons. W takim przypadku odpowiedni zapis TemplateData powinien wyglądać tak:

<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>

Taki zapis powinien na stronie dokumentacji szablonu przyjąć poniższą formę:

Szablon do linkowania kategorii w serwisie Commons powiązanej z artykułem

Parametry szablonu

ParametrOpisTypStatus
kategoria Commons1

Kategoria Commons, do której chcesz linkować

Wartość domyślna
Category:CommonsRoot
Ciąg znakówwymagany

Opis i parametry[edytuj | edytuj kod]

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 kodowe parametrów[edytuj | edytuj kod]

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.

Etykiety parametrów[edytuj | edytuj kod]

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",

Opis parametrów[edytuj | edytuj kod]

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ści wstępne parametrów[edytuj | edytuj kod]

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",
Sugerowane wartości. Dodatkowo można podać listę Sugerowanych wartości "suggestedvalues". Ta opcja jest obsługiwana razem z tekstowymi typami (content, line, string) oraz z numerycznym (number).
"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.

Typy parametrów[edytuj | edytuj kod]

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",

Wymagane i sugerowane[edytuj | edytuj kod]

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"

Problemy[edytuj | edytuj kod]

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).

Aliasy parametrów[edytuj | edytuj kod]

Niektóre szablony używają różnych nazw dla jednego parametru.

Na przykład {{Commons|kategoria=Jabłka}} może być też zapisany jako {{Commons|Jabłka}} lub {{Commons|link=Jabłka}}.

Aby dodać informację o tych nazwach do TemplataData, należy po prostu dodać poniższy zapis:

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

Wiele parametrów[edytuj | edytuj kod]

Jeśli w szablonie znajduje się wiele parametrów, to można powtarzać kolejne sekcje (zaczynając od pierwszego znacznika - "1") i wypełniać w nich potrzebne elementy. Należy natomiast zauważyć, że kolejne parametry należy oddzielać przecinkami tak, jak w przykładzie:

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

Podobne parametry[edytuj | edytuj kod]

Jeśli szablon ma wiele parametrów, może się zdarzyć, że niektóre z nich będą miały identyczne cechy. W takim przypadku należy wprowadzić wszystkie właściwości tylko dla pierwszego, a następne mogą je odziedziczyć.

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

Preferowany format szablonu[edytuj | edytuj kod]

Istnieje możliwość ustalenia, jak będzie generowany wikikod wstawiający szablon. Odpowiada za to właściwość "format", którą kreatorze ustawić go można, klikając przełączniki. Parametr ten dodawany jest w tym samym poziomie co "description" (opis szablonu) i "params" (z lista parametrów)

Może przyjmować następujące wartości:

  • block - blokowy - wypełniane parametry będą obecne w wikikodzie jeden pod drugim (np. tak jak w infoboksach)
  • inline - liniowy - kod szablonu będzie wstawiony w jednej linii
  • brak - jeżeli format nie będzie ustalony (brak obecności właściwości "format"), edytor wizualny pozostawi szablon tak, jak był wcześniej zapisany, a nowo wstawiane szablony będą wstawiane w jednej linii
  • niestandardowy - inny sposób zapisu kodu szablonu w formacie, który należy podać w polu tekstowym pod tymi opcjami (edytorem) lub jako wartość parametru "format"

Przykładowy schemat[edytuj | edytuj kod]

Poniższy przykład można skopiować, aby na jego podstawie stworzyć nowy TemplateData. Zawiera on jednak tylko najczęściej używane wartości.

<templatedata>
{
        "description": "",
        "params": {
                "1": {
                        "label": "",
                        "description": "",
                        "type": ""
                },
                "2": {
                        "label": "",
                        "description": "",
                        "type": ""
                }
        }
}
</templatedata>

Ograniczenia i pytania[edytuj | edytuj kod]

  • Brakujące funkcje — TemplateData jest przykładem narzędzia, które zostało udostępnione tylko z kilkoma funkcjami, ale kolejne mają być dodawane przy pomocy użytkowników. Jeśli chciałbyś zgłosić swoje pomysły, które pozwolą ulepszyć TemplateData, to daj nam znać.
  • Opóźnienia pokazywania w szablonach — Po udanym dodaniu TemplateData do szablonu, efekt powinien być od razu widoczny w edytorze wizualnym. Może się jednak zdarzyć, że potrwa to kilka godzin. Da się przyspieszyć to poprzez wykonanie pustej edycji w samym szablonie (nie na podstronie dokumentacji). Aby to zrobić, należy edytować stronę szablonu i zapisać ją bez dokonania żadnej zmiany.
  • Aktualne problemy — Aktualna lista błędów i uwag jest dostępna w phabricatorze.

Zobacz też[edytuj | edytuj kod]