Szablon:Ramy czasowe zdarzenia: Różnice pomiędzy wersjami

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

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:

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:

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:

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:

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

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:

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:

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: