Szablon:Ramy czasowe zdarzenia/opis
 |
Dany szablon musi być użyty przez podstawienie (subst:), a nie w standardowy sposób. |
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 określeniu w przypadku pewnych użytych słów zabraknie końcówki lub będzię ona nieodpowiednia, co jest błędem | |||
| <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
Poniższa sekcja ma w zasadzie zastosowanie tylko na polskiej wikipedii, ale jest fragmenty mogą być przydatne i na tej wiki.
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
- 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),
- z wartości parametru "stopU" usunąć ciąg "+7*86400", przez co stopU staje się równe startU,
- 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 |
