Pomoc:Jak dodać TemplateData

{{Wikipedia:VisualEditor/Nawigacja}}Szablon:Skrót

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

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 można posłużyć się edytorem TemplateData Michała Łazowika.

Struktura TemplateData

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

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
Parametr		Opis	Typ	Status
kategoria Commons	`1`	Kategoria Commons, do której chcesz linkować Domyślne Category:CommonsRoot	Ciąg znaków	wymagany

Opis i parametry

Pierwszym znacznikiem jest `"description"`, opisujący, co szablon robi.	"description": "Szablon do linkowania kategorii w serwisie Commons powiązanej z artykułem",

Następnie jest znacznik `"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 }

W każdej podsekcji pierwszy ze znaczników odpowiada za nazwę parametru, który jest dokładnie nazwą zmiennej w samym szablonie. Jeśli parametr ma nazwę, np. `{{{kategoria-link}}}`, to znacznik mu odpowiadający powinien przyjąć nazwę `"kategoria-link"`. W przypadku braku nazwy parametru, czyli gdy przybiera on postać cyfry jak chociażby `{{{1}}}`, to znacznik tworzymy analogicznie do już istniejącego, w tym przypadku będzie to `"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 }

Kolejnym elementem jest `"label"`. Odpowiada on za nazwę 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ć.",

Ustawienie `"autovalue"` mówi VisualEditorowi i innym narzędziom, aby wypełniały ten parametr standardową wartością (w wiki-tekście); ten tekst pojawi się w pudełku 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. Zwróć uwagę, że metoda oparta o substy nie działa dla szablonów, które są użyte wewnątrz tagów <ref>, tagów galerii i innych tagów zależnych od rozszerzenia.	"autovalue": "{{subst:CURRENTMONTHNAME}} {{subst:CURRENTYEAR}}",
Ustawienie `"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 pudełku 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.	"default": "Category:CommonsRoot",

Następnie mamy `"type"`. Odpowiada on za sposób, w jaki edytor będzie interpretował parametr. Może to być: `"string"`: zestaw znaków, podobnych chociażby do tego zdania; `"number"`: zestaw cyfr; `"wiki-user-name"`: zestaw znaków, reprezentujący nazwę użytkownika; `"wiki-page-name"`: zestaw znaków, reprezentujący tytuł strony; `"wiki-file-name"`: nazwa pliku; `"boolean"`: wartość prawda/fałsz.	"type": "string",

Przedostatni jest znacznik `"required"`, który może przyjąć wartość `true` lub `false`. Odpowiada on za określenie, czy dany parametr musi zostać użyty w szablonie.	"required": true

Wreszcie jest `"suggested"`, który może mieć wartość `true` albo `false`. Jest to znacznik 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).

Aliasy parametrów

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

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

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

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

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

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.