Szablon:Ramy czasowe zdarzenia/tabela/opis

To jest podstrona dokumentacji dla strony Szablon:Ramy czasowe zdarzenia/tabela.
Zawiera ona informacje na temat użycia tej strony, jej kategoryzację i inną zawartość niebędącą częścią oryginalnej strony.

Przeznaczenie

Dany szablon (makro) pozwala na utworzenie w miejscu jego wywołania tabliczki wskazującej ramy czasowe jakiegoś zdarzenia – przeszłego, trwającego lub przyszłego, oraz odnoszący się do tego czasu stan tego zdarzenia. W tabliczce podawane są informacje opisowe, czy zdarzenie jeszcze się nie rozpoczęło, trwa czy już się zakończyło, a także wskazywane są daty (momenty) początku i końca zdarzenia. Tabliczki takie są przydatne na stronach głosowań, dyskusji, sondaży i innych przedsięwzięć z narzuconymi ograniczeniami czasowymi, a informacja o aktualnym odniesieniu zdarzenia do czasu jest istotna dla uczestników/obserwatorów zdarzenia.

Zastosowanie niniejszego szablonu wprost jest możliwe, ale wymaga pewnej wiedzy o wyliczaniu czasu w skali uniksowej (patrz dalej w sekcji "Użycie"), i praktycznie jest on szablonem pomocniczym dla szablonu {{Ramy czasowe zdarzenia}}.

Istotne dane szablonu

Parametry:

szablon nie zawiera parametrów pozycyjnych (numerowych) i zawiera 7 parametrów kluczowych (nazwanych)
wymaganie podania parametrów pozycyjnych: n/d
wymagania szczególne dla parametrów kluczowych: nie ma
uwarunkowanie ogólne parametrów kluczowych: wszystkie są w wywołaniu szablonu opcjonalne
wykaz parametrów z dokładnym opisem jest podany w następnej sekcji

Pominięcie wszystkich parametrów nazwanych jest możliwe i nie powoduje błędu, ale ma sens tylko demonstracyjny.

Wołane szablony (wikimakra):

Dokumentacja
{{Ramy_czasowe_zdarzenia/LSnK}}

Wołane funkcje parsera:

#ifexpr
#time

Wołany przez szablon:

{{Ramy_czasowe_zdarzenia}}

Użycie

Szablon używany jest w standardowy sposób, przez wstawienie do kodu artykułu jego wywołania – tak jak jest podane w poniższych przykładach. W wywołaniu szablonu można nie podawać ani jednego parametru.

W postaci ogólnej wywołanie szablonu ma poniższą postać – kursywą wskazano miejsca, w których należy wpisać adekwatny tekst:

{{Ramy czasowe zdarzenia/tabela|zdarzenie=nazwa zdarzenia|rgz=rodzaj gramatyczny zdarzenia|start=opis daty startu|startU=data startu uniksowa|stop=opis daty końca|stopU=f|wkLS=data końca uniksowa}}

Użycie niniejszego szablonu wprost nie jest jednak zalecane, gdyż wymaga dla danych dat uprzedniego wyliczenia i podania wartości czasów w skali uniksowej. Zamiast tego należy stosować konstrukcję subst: dla szablonu "Ramy czasowe zdarzenia", wywołującego szablon niniejszy i wyliczającego ze swoich parametrów spójne wartości parametrów danego szablonu.

Parametry

Poniższa tabela podaje rozwinięty opis wszystkich parametrów makra.

W pierwszej kolumnie podano typ parametru:

K - kluczowy, identyfikowany w wywołaniu szablonu wyłącznie przez nazwę (klucz)

Druga kolumna zawiera wskazanie, czy parametr jest:

W - wymagany
o - opcjonalny

Nazwa	Typ	Rodz.	Opis, sposób nadania wartości i wynik

zdarzenie	K	o	Nazwa zdarzenia, dla którego podawane są ramy czasowe oraz stan zdarzenia wynikający z odniesienia ram do bieżącego momentu. W pierwszym wierszu tabeli podawany jest tekst składający się z niniejszej nazwy zdarzenia (w odpowiednim rodzaju gramatycznym wskazanym przez parametr rgz) oraz aktualny stan zdarzenia (zgodnie z wartościami odpowiednich pozostałych parametrów), tj. że jest planowane, trwa, lub jest zakończone. Wartości:
			zdarzenie=Festiwal	tabelka będzie odnosiła się do zdarzenia "Festiwal"
			zdarzenie=	w tabelce NIE pojawi się nazwa zdarzenia, co jest pozbawione sensu
			<brak>	zostanie podstawiona domyślna nazwa zdarzenia - "Głosowanie"

rgz	K	o	Wskazanie rodzaju gramatycznego zdarzenia – pierwszej litery określenia: męski, żeński, nijaki, co pozwoli użyć właściwych końcówek w określeniu stanu zdarzenia. Wartości:
			rgz=[m\|ż\|n]	końcówki w określeniu bądą zgodne z rodzajem określenia
			rgz=	w określeniu w pewnych słowach zabraknie końcówek, co jest błędem
			<brak>	zostanie podstawiona domyślny rodzaj – "n" czyli nijaki, zgodny z rodzajem rzeczownika (też domyślnego) "Głosowanie"

start	K	o	Wskazanie trybu planowania zdarzenia lub początkowego momentu ram czasowych opisywanego zdarzenia. Jest to parametr opisowy, w pierwszym przypadku ma postać "---", a w drugim powinien być podawany w formacie `dd mmm rrrr gg:mm:ss`, i powinien być zgodny z wartością parametru startU. W ramce tekst tego parametru jest wstawiany po tytule "Rozpoczęcie:". Wartości:
			start=12 marca 2000 13:12:12	wskazanie, że zdarzenie miało początek o godzinie 13:12:12 12 marca 2000 r.
			start=---	wskazanie, że zdarzenie jest planowane (wartość parametru to trzy znaki minus - kod ASCII dziesiętny 45)
			start=	po tytule "Rozpoczęcie:" nic się nie pojawi – nie jest to błędem, ale niepodanie niniejszego parametru nie ma sensu
			<brak>	po tytule "Rozpoczęcie:" zostanie podstawiony tekst {{{start}}}

startU	K	o	Wskazanie wartości liczbowej momentu czasowego start liczonej według skali systemu Unix, czyli jako liczba sekund od godziny 00:00:00 1 stycznia 1970 roku (np. moment wyświetlenia niniejszej strony jest wskazany czasem równym wartości funkcji parsera `{{#time: U \| }} = 1731084521` – jest to równoważne funkcji php `mktime()`). Liczbę taką można uzyskać dla dowolnej daty i godziny wykorzystując konwertery dostępne w sieci, np. http://www.epochconverter.com/. Parametr ten jest używany do wyznaczenia, czy początek zdarzenia jest przeszły czy przyszły w stosunku do momentu bieżącego, co z kolei pozwala określić, czy opisywane zdarzenie jeszcze się nie zaczęło lub czy trwa. Wartość ta powinna być zgodna z podanym parametrem start, a jego ustalenie należy do osoby chcącej użyć niniejszego szablonu – w związku z tym lepiej jest użyć podstawienia szablonu Ramy czasowe zdarzenia. Dla parametru start=--- wartość danego nie ma znaczenia, jest on pomijany. Wartości:
			startU=1172360220	wskazanie godziny 23:37:00 24 lutego 2007 roku
			startU=	taka konstrukcja spowoduje pojawienie się komunikatu o błędzie parsera
			<brak>	zostanie przyjęta wartość funkcji `{{#time: U \| }}` dla momentu wyświetlenia w przeglądarce strony z wywołaniem niniejszego szablonu

stop	K	o	Wskazanie końcowego momentu ram czasowych opisywanego zdarzenia. Jest to parametr opisowy, powinien być podawany w formacie `dd mmm rrrr gg:mm:ss`, i powinien być zgodny z wartością parametru stopU. W ramce tekst tego parametru jest wstawiany po tytule "Zakończenie:". Dla parametru start=--- nie ma znaczenia, jest on automatycznie ustawiany na "---" Wartości:
			stop=12 marca 2000 13:12:12	wskazanie, że zdarzenie miało koniec 13:12:12 12 marca 2000 r.
			stop=	po tytule "Zakończenie:" nic się nie pojawi – nie jest to błędem, ale w związku z tym niepodanie niniejszego parametru nie ma sensu
			<brak>	po tytule "Data zakończenia:" zostanie podstawiony tekst {{{stop}}}

stopU	K	o	Wskazanie wartości liczbowej momentu czasowego stop liczonej według skali systemu Unix. Parametr ten jest używany do wyznaczenia, czy koniec zdarzenia jest przeszły, czy przyszły w stosunku do momentu bieżącego, co z kolei pozwala określić, czy opisywane zdarzenie już się zakończyło. Wartość ta powinna być zgodna z podanym parametrem stop, a jego ustalenie należy do osoby chcącej użyć niniejszego szablonu – w związku z tym lepiej jest użyć podstawienia szablonu Ramy czasowe zdarzenia. Dla parametru start=--- wartość danego nie ma znaczenia, jest on pomijany. Wartości:
			stopU=1172360220	wskazanie godziny 23:37:00 24 lutego 2007 roku
			stopU=	taka konstrukcja spowoduje pojawienie się komunikatu o błędzie parsera
			<brak>	zostanie przyjęta wartość funkcji `{{#time: U \| }}` dla momentu wyświetlenia w przeglądarce strony z wywołaniem niniejszego szablonu

wkLS	K	o	Wskazanie, że będzie wyświetlony komunikat podający, ile w ogólnym przypadku dla stanu trwającego zdarzenia pozostało dni, godzin, minut i sekund do zakończenia tego zdarzenia – dla okresu dłuższego niż 30 dni podany zostanie komunikat, że zdarzenie potrwa ponad 30 dni. Dla parametru start=--- wartość danego nie ma znaczenia, jest on pomijany. Wartości:
			wkLS=TAK	wyświetlenie komunikatu (jest to działanie domyślne)
			<brak>	jw.
			wkLS=NIE lub tekst dowolny inny niż powyżej	komunikat nie będzie wyświetlony

Przykłady

Przykład ogólny wywołania ze wskazaniem wszystkich parametrów kluczowych, ale bez podania wartości dla nich. Należy pamiętać, że parametry nie muszą być w wywołaniu szablonu podawane w przytoczonej kolejności.

{{Ramy czasowe zdarzenia/tabela
| zdarzenie =
| rgz       =
| start     =
| startU    =
| stop      =
| stopU     =
| wkLS      =
}}

Przykład nr 1
Przykład ten z kodem jak poniżej:

{{Ramy czasowe zdarzenia/tabela
| zdarzenie = Wyścig
| rgz       = m
| start     = (tekst dla startu 21:30 14-12-2006 -> 1166131800)
| startU    = 1166131800
| stop      = (tekst dla końca  13:52 19-01-2009 -> 1232373120)
| stopU     = 1232373120
| wkLS      = TAK
}}

tworzy tabelę czasową dla przeszłego zdarzenia:

Wyścig zakończony
Rozpoczęcie: (tekst dla startu 21:30 14-12-2006 -> 1166131800)	Zakończenie: (tekst dla końca 13:52 19-01-2009 -> 1232373120)

przy czym teksty dla rozpoczęcia i zakończenia są świadomie bardzo opisowe, ponadto pokazane jest, że parametr wkLS w takim przypadku (zdarzenia przeszłego) nie ma znaczenia.

Przykład nr 2
Przykład ten z kodem jak poniżej:

{{Ramy czasowe zdarzenia/tabela
| zdarzenie = Dyskusja
| rgz       = ż
| start     = (data wcześniejsza niż aktualna o 10 dni minus 1000 sekund)
| startU    = {{#expr: {{#time: U}} - (60*60*24*10 - 1000) }}
| stop      = (data późniejsza niż aktualna o 10 dni plus 1000 sekund )
| stopU     = {{#expr: {{#time: U}} + (60*60*24*10 + 1000) }}
| wkLS      = TAK
}}

tworzy tabele czasową dla zdarzenia, które dla tego przykładu ma stale datę rozpoczęcia i zakończenia odległą od bieżącej o 10 dni plus/minus 1000 sekund:

Dyskusja trwa jeszcze 10 dni 0 godz. 16 min 40 s Odśwież
Rozpoczęcie: (data wcześniejsza niż aktualna o 10 dni minus 1000 sekund)	Zakończenie: (data późniejsza niż aktualna o 10 dni plus 1000 sekund )

Teksty dat są opisowe, gdyż parser Mediawiki nie oferuje funkcji przekształcającej czas uniksowy na sformatowana datę, jak to robi funkcja php date().

Przykład nr 3
Przykład ten z kodem jak poniżej:

{{Ramy czasowe zdarzenia/tabela
| zdarzenie = Spływ
| rgz       = m
| start     = ---
}}

tworzy tabelę informacyjną dla planowanego zdarzenia:

Spływ planowany
Rozpoczęcie: ---	Zakończenie: ---