Szablon:Ramy czasowe zdarzenia/opis

Przeznaczenie

Dany szablon (makro) pozwala na utworzenie w miejscu jego umieszczenia 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.

Szablon użyty w sposób tu opisany jest dogodny dla użytkownika, gdyż nie wymaga wiedzy o sposobie wyliczaniu czasu w skali uniksowej (patrz dalej w sekcji "Użycie"). Faktycznie użyty w taki sposób szablon powoduje wstawienie w określone miejsce kodu wybranej strony wywołanie szablonu {{Ramy czasowe zdarzenia/tabela}} z wyliczonymi parametrami wymaganymi dla tego szablonu, w tym m.in. wartości uniksowych momentów czasowych oraz odpowiadających im tekstów czytelnych dla człowieka. To ostatnie powoduje, że aczkolwiek można wpisać ręcznie wprost wywołanie szablonu {{Ramy czasowe zdarzenia/tabela}} z wyliczonymi parametrami wymaganymi dla tego szablonu, w tym m.in. wartości uniksowych momentów czasowych oraz odpowiadających im tekstów opisowych, to nie jest to sprawą trywialną. Ponadto wartości czasu oraz ich reprezentacje czytelne nie są przez szablon {{Ramy czasowe zdarzenia/tabela}} przeliczane wzajemnie, muszą być podane w wywołaniu jednocześnie, a za ich wzajemną zgodność odpowiada piszący wywołanie, a to może spowodować pomyłki. W danym szablonie wymagane dane są nieredundantne i oczywiste - liczby określające naturalną, czytelną reprezentację momentu początkowego zdarzenia oraz czas jego trwania, co następnie jest przeliczane na trzy inne dane - tekst o czasie zakończenia oraz czasy uniksowe początku i końca (czyli nie musi tego robić wstawiający tabliczkę). Sprawia to, że tylko takie użycie jest prawidłowe i praktycznie uniemożliwia błędne wywołanie.

Istotne dane szablonu

Parametry:

• szablon zawiera 7 parametrów pozycyjnych (numerowych) i 3 parametry kluczowe (nazwane)
• 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

Wołane szablony (wikimakra):

• Dokumentacja
• {{Ramy_czasowe_zdarzenia/tabela}}

Wołane funkcje parsera:

• #if
• #time

Wołany przez szablon:

• n/d

Użycie

Szablon prawidłowo używany jest w niestandardowy sposób, przez konstrukcję subst: z odpowiednim wskazaniem nazwy szablonu i parametrów (opcjonalnie).

W postaci ogólnej użycie szablonu ma poniższą postać - kursywą wskazano miejsca, w których należy wpisać adekwatny tekst (zwróć uwagę na sekcję Znane błędy dalej w treści dokumentacji):

{{subst:Ramy czasowe zdarzenia| zdarzenie=nazwa zdarzenia| rgz=rodzaj gramatyczny zdarzenia| wkLS=czy podać czas do zakończenia| liczba dni trwania zdarzenia| rok startu| mc startu| dzień startu| godz. startu:minuta startu| sekunda startu| czas startu letni/zimowy}}

Wartości parametrów pozycyjnych nie mogą mieć przed nimi ani za nimi spacji – ich obecność spowoduje błędne działanie kodu!

Wywołanie danego szablonu w standardowy sposób, czyli {{Ramy czasowe zdarzenia}} spowoduje wyświetlenie tabeli z informacjami o błędach.

Parametry

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

W pierwszej kolumnie podano typ parametru:

• P - pozycyjny, identyfikowany przez pozycję w wywołaniu szablonu lub nazwę (klucz), którą jest liczba naturalna
• 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=Lot	tabelka będzie odnosiła się do zdarzenia "Lot"
			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 z 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]	wskazanie odpowiedniego rodzaju gramatycznego opisywanego zdarzenia
			rgz=	w przypadku pewnych nazw zdarzeń spowoduje brak końcówki lub będzie ona nieodpowiednia
			<brak>	zostanie podstawiona domyślny rodzaj - "n", czyli nijaki zgodny z rodzajem rzeczownika (też domyślnego) "Głosowanie"
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. W przypadku wskazania dla pierwszego parametru pozycyjnego wartości "---" dany parametr nie ma znaczenia, jest on pomijany. Wartości:
			wkLS=TAK	wyświetlenie komunikatu (jest to działanie domyślne)
			<brak>	jw.
			wkLS=NIE lub dowolny inny niż powyżej	komunikat nie będzie wyświetlony
1	P	o	Liczba dni trwania zdarzenia lub wskazanie trybu planowania zdarzenia (dla wyświetlenia odpowiedniej tymczasowej tabeli informacyjnej). Wartości:
			100	wskazanie, że okres trwania zdarzenia to 100 dni
			<brak>	brak wartości spowoduje przyjęcie wartości domyślnej 7 dni
			---	wskazanie trybu planowania zdarzenia (wartością parametru są trzy znaki minus - kod ASCII dziesiętny 45, zostanie on wyświetlony w polu tabeli "Rozpoczęcie")
2, 3, 4, 5, 6	P	o	Rok, miesiąc, dzień godzina z minutami oraz oddzielnie sekundą początku zdarzania. W przypadku wskazania dla pierwszego parametru pozycyjnego wartości "---" dane parametry nie mają znaczenia, są one pomijane. Wartości:
			|2009 |4 |20 |19:15 |31	wskazanie, że początek zdarzenia to 20 kwietnia 2009 r. o godzinie 19:15:31
			<brak>	brak którejkolwiek z wartości spowoduje przyjęcie wartości domyślnej – odpowiedniej bieżącej dla momentu wykonania konstrukcji subst:
7	P	o	Aktualna dla początku zdarzenia strefa czasowa w Polsce. W przypadku wskazania dla pierwszego parametru pozycyjnego wartości "---" dany parametr nie ma znaczenia, jest on pomijany. Wartości:
			CET lub CEST	wskazanie odpowiednio czasu zimowego (CET) lub letniego (CEST)
			<brak>	brak wartość spowoduje przyjęcie wartości pustej
			inna wartość	podanie wartości innej niż CET, CEST lub pusta spowoduje wyświetlenie komunikatu Błąd w wyrażeniu – nieoczekiwany operator <

Przykłady

Ogólne

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, natomiast wartości parametrów pozycyjnych nie mogą mieć przed nimi ani za nimi spacji – ich obecność spowoduje błędne działanie kodu!.

{{subst:Ramy czasowe zdarzenia|zdarzenie= |rgz= |wkLS= |liczba-dni|rok|nr-miesiąca|dzień|godzina:minuty|sekundy|czas-zimowy/letni}}

Przykład nr 1
Przykładowe wypełnienie dla zdarzenia z wszystkimi wartościami domyślnymi i zapisane 5 maja 2009 o godzinie 14:32:19:

{{subst:Ramy czasowe zdarzenia}}

spowodowało podstawienie w jego miejsce poniższego kodu:

{{Ramy czasowe zdarzenia/tabela|start=5 maja 2009 14:32:19|stop=12 maja 2009 14:32:19|startU=1241526739|stopU={{#expr:1241526739+7*86400}}}}

co dało taki efekt:

Głosowanie zakończone
Rozpoczęcie: 5 maja 2009 14:32:19	Zakończenie: 12 maja 2009 14:32:19

Przykład nr 2
Przykładowe wypełnienie 30 kwietnia 2009 o godzinie 15:53:16 dla zdarzenia trwającego 12 dni i z wszystkimi pozostałymi wartościami domyślnymi:

{{subst:Ramy czasowe zdarzenia|12}}

spowodowało podstawienie w jego miejsce poniższego kodu:

{{Ramy czasowe zdarzenia/tabela|zdarzenie=Głosowanie|rgz=n|wkLS=NIE|start=30 kwietnia 2009 15:53:16|stop=12 maja 2009 15:53:16|startU=1241099596|stopU={{#expr:1241099596+12*86400}}}}

z poniższym efektem:

Głosowanie zakończone
Rozpoczęcie: 30 kwietnia 2009 15:53:16	Zakończenie: 12 maja 2009 15:53:16

Przykład nr 3
Przykładowe wypełnienie dla zdarzenia "głosowanie" trwającego 7 dni rozpoczętego 20 stycznia 2009 o godzinie 21:23:11 czasu zimowego (CET):

{{subst:Ramy czasowe zdarzenia|7|2009|1|20|21:23|11|CET}}

spowoduje podstawienie w jego miejsce poniższego kodu:

{{Ramy czasowe zdarzenia/tabela|zdarzenie=Głosowanie|rgz=n|wkLS=NIE|start=20 stycznia 2009 21:23:11|stop=27 stycznia 2009 21:23:11|startU=1232482991|stopU={{#expr:1232482991+7*86400}}}}

który da poniższy efekt:

Głosowanie zakończone
Rozpoczęcie: 20 stycznia 2009 21:23:11	Zakończenie: 27 stycznia 2009 21:23:11

Przykład nr 4
Zdarzenie "Lot" trwające 30 dni rozpoczęte 28 kwietnia 2009 o godzinie 21:23:11 z podaniem ile jeszcze zostało dni do końca - komunikat ten będzie w przykładzie widoczny tylko do 26 maja 2009 r.:

{{subst:Ramy czasowe zdarzenia|zdarzenie=Lot|rgz=m|wkLS=TAK|30|2009|4|27|21:23|11|CET}}

spowoduje podstawienie w jego miejsce poniższego kodu:

{{Ramy czasowe zdarzenia/tabela|zdarzenie=Lot|rgz=m|wkLS=TAK|start=27 kwietnia 2009 21:23:11|stop=27 maja 2009 21:23:11|startU=1240863791|stopU={{#expr:1240863791+30*86400}}}}

który da poniższy efekt:

Lot zakończony
Rozpoczęcie: 27 kwietnia 2009 21:23:11	Zakończenie: 27 maja 2009 21:23:11

5 maja 2009 roku o g. 11:58 tabela wyglądała jak poniżej:

Lot trwa jeszcze 22 dni 10 godz. 25 min 45 s
Rozpoczęcie: 27 kwietnia 2009 21:23:11	Zakończenie: 27 maja 2009 21:23:11

Przykład nr 5
Dla wstawienia tabliczki informacyjnej np. o planowanym spływie należy użyć konstrukcji::

{{subst:Ramy czasowe zdarzenia|zdarzenie=Spływ|rgz=m|---}}

co spowoduje podstawienie w jego miejsce poniższego kodu:

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

który da poniższy efekt:

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

Zastosowanie na PUA

Obsługa standardowa

Najczęściej obecnie tabliczkę tego typu stosuje się na stronie PUA. Jest ona generowana z wykorzystaniem szablonu {{Ramy czasowe zdarzenia}} (korzystającego z kolei z szablonu {{Ramy czasowe zdarzenia/tabela}}), ale używanym w konstrukcji {{subst:Ramy czasowe zdarzenia|7}} (sposób domyślny) lub {{subst:Ramy czasowe zdarzenia|7|rrrr|dd|gg:mm|ss|czL-Z}}, gdzie rrrr do czL-Z to symboliczne oznaczenie elementów czasu wyrażenia zgody - roku, miesiąca, dnia, godziny z minutami, sekundy i oznaczenia czasu (zimowego lub letniego). Pierwsza konstrukcja znajduje się w kodzie początkowym wniosku wewnątrz komentarza, a usunięcie ograniczników komentarza (czyli ciągów "<!--" i "-->") wokół niej i zapisanie edycji jest nazywane włączeniem zegara. Konstrukcja ta jest najprostsza, gdyż w momencie zapisywania edycji automatycznie pobiera z systemu wszystkie potrzebne dane o czasie i najlepiej ją zastosować, gdy osoba kandydująca chce włączyć zegar edycją, w której wyraża zgodę na kandydowanie. Gdyby tego nie zrobiła, to może zegar włączyć później, ale już z wykorzystaniem konstrukcji drugiej, po odczytaniu z historii zmian podstrony głosowania potrzebnych danych o edycji zapisującej zgodę (należy pamiętać, że czas z dokładnością do sekund jest pokazywany użytkownikowi np. na stronach historii zmian wyłącznie wtedy, gdy ma ta osoba w Preferencjach w zakładce Data i czas wybrany format daty 2001-01-15T16:12:34) i wpisaniu ich do kodu konstrukcji, a następnie zapisaniu takiej edycji. Nie jest zalecane samodzielne stosowanie szablonu {{Ramy czasowe zdarzenia/tabela}} bez posiadania umiejętności przeliczenia danych opisowych punktu czasowego na czas w skali uniksowej.

Użycie do tego celu danego szablonu jest w zasadzie proste. W kodzie podstrony konkretnego głosowania przygotowanej ze standardowego wzorca znajduje się fragment podający właściwe postaci dla dwóch typowych ww. przypadków:

<!-- KKK Poniższych 5 linii bez oznaczenia KKK przeznaczono na włączenie tzw. zegara (tabliczki czasowej) głosowania.    -->
<!-- KKK  Pierwsze trzy wiersze (komentarzowe) pozostawić (tak!), a z dwóch kolejnych pozostawić właściwy, po czym usu-  -->
<!-- KKK  nąć z niego znaczniki komentarza (więcej informacji patrz w dokumentacji szablonu "Ramy czasowe zdarzenia")    -->

<!-- Wzorce utworzenia tabliczki czasowej głosowania                                                                     -->
<!-- {{subst:Ramy czasowe zdarzenia|7}}                           postać nr 1 dla włączenia zegara edycją zgody          --> 
<!-- {{subst:Ramy czasowe zdarzenia|7|rrrr|mm|dd|gg:mm|ss|czL-Z}} postać nr 2 dla wstawienia czasu pobranego z historii  --> 

<!-- {{subst:Ramy czasowe zdarzenia|7}}                           --> 
<!-- {{subst:Ramy czasowe zdarzenia|7|rrrr|mm|dd|gg:mm|ss|czL-Z}} --> 

W pierwszym przypadku, tj. chęci włączenia zegara edycją wyrażająca zgodę na kandydowanie należy usunąć znaczniki komentarza wokół postaci {{subst:Ramy czasowe zdarzenia|7}}, usunąć postać rozwiniętą i zapisać edycję.

W przypadku drugim należy odszukać w zakładce "Historia" danej podstrony głosowania edycję wyrażająca zgodę i należy pobrać dane określające dokładnie moment zapisania ww. edycji, czyli zgody (łącznie z sekundami - patrz uwagę powyżej nt. wyświetlania sekund w historii zmian).

Następnie należy wykonać kolejną edycję, usuwającą postać {{subst:Ramy czasowe zdarzenia|7}} i znaczniki komentarza wokół postaci {{subst:Ramy czasowe zdarzenia|7|rrrr|mm|dd|gg:mm|ss|czL-Z}} oraz zamieniającą ciągi symboliczne na faktyczne wartości.

Np. jeśli edycja z wyrażeniem zgody miała miejsce 2 stycznia (czyli czasu zimowego) 2008 roku o godzinie 22:22:22, to fragment kodu strony pua powinien był wyglądać na podglądzie trybu edycji tak (jak widać, występuje w nim konstrukcja subst z dość naturalnymi wartościami parametrów):

<!-- Wzorce utworzenia tabliczki czasowej głosowania              -->
<!-- {{subst:Ramy czasowe zdarzenia|7}}                           --> 
<!-- {{subst:Ramy czasowe zdarzenia|7|rrrr|mm|dd|gg:mm|ss|czL-Z}} --> 

{{subst:Ramy czasowe zdarzenia|7|2008|1|2|22:22|22|CET}}

Oczywiście po wykonaniu (zapisaniu) strony z powyższym fragmentem kodu został by ten kod zmieniony na taki:

<!-- Wzorce utworzenia tabliczki czasowej głosowania              -->
<!-- {{subst:Ramy czasowe zdarzenia|7}}                           --> 
<!-- {{subst:Ramy czasowe zdarzenia|7|rrrr|mm|dd|gg:mm|ss|czL-Z}} --> 

{{Ramy czasowe zdarzenia/tabela|start=2 stycznia 2008 22:22:22|stop=9 stycznia 2008 22:22:22|startU=1199308942|stopU={{#expr:1199308942+7*86400}}|||}}

Jak widać, zamiast wiersza z konstrukcją subst pojawiło się automatycznie wstawione wywołanie szablonu z wyliczonymi wartościami czasu uniksowego.

Przerwane głosowanie

W przypadku przedterminowego zakończenia głosowania, przede wszystkim z powodu wycofania się kandydata, istnieje prosty przepis na ustawienie szablonu zegara tak, aby o tym informował.

Dla przykładu niech na stronie pua był zegar z takim kodem (kursywą i podkreśleniem wydzielono części tekstu do zmiany tak jak opisano dalej) i poniżej jego wynikiem:

{{Ramy czasowe zdarzenia/tabela|start=11 czerwca 2010 22:57:20|stop=18 czerwca 2010 22:57:20|startU=1276289840|stopU={{#expr:1276289840+7*86400}}|||}}

Głosowanie zakończone
Rozpoczęcie: 11 czerwca 2010 22:57:20	Zakończenie: 18 czerwca 2010 22:57:20

Aby zamienić tabelę na informującą o przerwaniu głosowania wystarczy

1. zmienić wartość (wyświetlaną) parametru "stop" na tekst podający moment zakończenia głosowania (nie ma konieczności wyliczenia wartości parametru "stopU" - patrz niżej),
2. z wartości parametru "stopU" usunąć ciąg "+7*86400", przez co stopU staje się równe startU,
3. dodać parametr "zdarzenie", np. "Wycofanie się - głosowanie" lub "Kandydat wycofał się - głosowanie" lub "Przygotowanie unieważnione - dyskusja", oraz właściwy parametr "rgz", aby całość pierwszego wiersza tabeli była spójna gramatycznie.
   

Poniżej zmieniony kod (wytłuszczeniem zaznaczono dodany tekst) oraz jego wynik:

{{Ramy czasowe zdarzenia/tabela|start=11 czerwca 2010 22:57:20|stop=12 czerwca 2010 09:49:20|startU=1276289840|stopU={{#expr:1276289840}}|zdarzenie=Wycofanie się - głosowanie|rgz=n}}

Wycofanie się - głosowanie zakończone
Rozpoczęcie: 11 czerwca 2010 22:57:20	Zakończenie: 12 czerwca 2010 09:49:20

Znane błędy

Dwa w zamierzeniu identyczne wywołania szablonu:

1. {{Ramy czasowe zdarzenia| zdarzenie=Sondaż| rgz=m | wkLS=TAK | 2 | 2008 | 7 | 2 | 20:35 | 00 | CEST }}

2. {{Ramy czasowe zdarzenia| zdarzenie=Sondaż| rgz=m | wkLS=TAK | 2 |2008|7|2|20:35|00|CEST}}

pierwsze powoduje wyświetlenie komunikatów o błędzie:

Rozpoczęcie: 20:35:00	Zakończenie: 20:35:00

a drugie pokazuje zamierzony prawidłowy wynik:

Sondaż zakończony
Rozpoczęcie: 2 lipca 2008 20:35:00	Zakończenie: 4 lipca 2008 20:35:00

Zobacz też

• {{Głosowanie/wynik}}