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
[edytuj kod]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
[edytuj kod]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:
Użycie
[edytuj kod]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
[edytuj kod]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 | }} = 1727900690 – 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
[edytuj kod]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 | |
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: --- |