Dokumentacja projektu Strona Warsztatów Matematycznych
-1. Skrót
Strona Warsztatow Matematycznych jest strona służąca uczestnikom i prowadzącym Warsztaty
Matematyczne oraz kółka matematyczne w XIV LO im. S. Staszica w Warszawie. Uczestnik może
przed strone ściągąć materiały z odbytych zajęć, zadawać pytania do organizatorów oraz
dowiadywać się o nowościach. Prowadzący ma prawo zamieszczać informacje o prowadzonych przez
siebie kółkach, jak i dokładac materiały do swoich zajęc.
Poniższy dokument składa sie z dwóch części: opisu działania strony WWW oraz opisu konstrukcji bazy
danych i interfejsu do bazy danych w Scheme
0. Spis treści
-1. Skrót
0. Spis treści
1. Opis działania strony WWW
1.1. Część uczestnika
1.1.1. Strona główna
1.1.2. Strona pojedynczych warsztatów
1.1.3. Strona kółek
1.1.4. Strona galeria
1.1.4.1. Strona galeria - wszystkie galerie
1.1.4.2. Strona galeria - pojedyncza galeria
1.1.5. Strona FAQ
1.2. Część prowadzącego
1.2.1. Odpowiadanie na pytania
1.2.2. Zmiana danych
1.2.3. Zarządzanie własnymi kółkami
1.2.4. Zarządzanie własnymi materiałami
1.2.5. Dodanie niusa
1.3. Funkcjonalności administratora
2. Opis konstrukcji
2.1. Model logiczny
2.2. Zmiany w stosunku do modelu logicznego
2.3. Widoki
2.4. Zachowanie spójności bazy danych
2.5. Implementacja CGI w Scheme
2.5.1. Biblioteka wm_lib.ss
2.5.2. Zewnetrzne komendy - kompilowanie TeXa
3. Obecne instalacje
4. FAQ prowadzących, w szczególności o kompilowaniu TeXów
1. Opis działania strony WWW
Strona WWW składa się z menu z lewej strony oraz z głównej części widoku po prawej. W menu można wybrać podstronę bądź zalogować się jako prowadzący.
Podstrony dzielą się na te dostępne przez zwykłego użytkownika oraz te dostępne po zalogowaniu się, tylko dla prowadzących
1.1. Część uczestnika
Przeciętny użytkownik może:
- Przeczytać niusy z strony głównej
- Obejrzeć informacje na temat warsztatów, ściągnąć ew. materiały
- Obejrzeć informacje dotyczące odbytych kółek, ściągnąć ew. materiały
- Obejrzeć zdjęcia
1.1.1. Strona główna
Strona główna jest standardową podstroną wyświetlaną na początku wejścia na stronę. Na niej widoczne są aktualne niusy (nius standardowo ma ważność
jednego miesiąca) oraz stała informacja na temat celu istnienia strony.
1.1.2. Strona pojedynczych warsztatów
Z bocznego menu można wybrać jedne z warsztatów matematycznych. Podstrona informująca o pojedynczych warsztatach zawiera:
- Listę kadry
- Ew. odnośnik do galerii zdjęć z warsztatów
- Ew. listę informacji na temat warsztatów. Informacje (np. lista zakwalifikowanych itp.) są osobnymi plikami html, które się wyświetlają w momencie
kliknięcia na link
- Ew. listę materiałów z warsztatów, w postaci plików txt bądź zTeXowanych (dvi,pdf,ps)
1.1.3. Strona kółek
Podstrona zawierająca informację o kółkach matematycznych i zawodach próbnych odbytych w szkole.
Każdy prowadzący ma prawo dodać swoje kółko do listy. Do kółek można
dołączać materiały. Podstrona składa się z listy kółek i ew. materiałów do tych kółek.
1.1.4. Strona galeria
1.1.4.1. Strona galeria - wszystkie galerie
Podstrona galeria wyświetla listę wydarzeń (kółek, warsztatów, zawodów) do których są jakieś zdjęcia. Kliknięcie na określoną galerię
przenosi użytkownika do strony z pojedynczą galerią
1.1.4.2. Strona galeria - pojedyncza galeria
Pojedyncza galeria wyświetla miniaturki zdjęć z wydarzenia, oraz linki do pełnowymiarowych zdjęć. W chwili obecnej wszystkie zdjęcia znajdują
się na serwerze duch.
1.1.5. Strona FAQ
Strona z często zadawanymi pytaniami (bądź też pytaniami wartymi odpowiedzi). Składa się ona z:
- Listy już odpowiedzianych pytań.
- Formularza służącego do zadania nowego pytania.
Warto nadmienić, iż zadane pytanie nie pojawia się w wyższej liście, gdyż nie jest jeszcze odpowiedziane - pojawi się, jeśli jakiś prowadzący na nie odpowie.
Prowadzący w ramach wolnego czasu mogą odpowiadać na pytania.
1.2. Część prowadzącego
W momencie zalogowania się przez prowadzącego, w miejsce formularza logowania, pojawia się dodatkowe menu dla prowadzących. Oprócz wylogowania się,
prowadzący może:
- Odpowiadać na pytania użytkowników
- Zmienić swoje dane
- Dodać nowe kółko, usunąć jakieś swoje kółko, dodać prowadzącego do wydarzenia które prowadzi
- Dodać bądź usunąć materiały do swoich zajęć
- Dodać niusa na stronę główną
O ile w części użytkownika ukryłem możliwe do wywołania przez laika możliwości wywołania tego, iż baza danych da nam po łapach, o tyle uznałem, że
prowadzący są zaawansowanymi uzytkownikami i nie przestraszą się komunikatu "Error: duplicate key violation".
1.2.1. Odpowiadanie na pytania
Prowadzący ma prawo, w tej podstronie:
- Przejrzeć nieodpowiedziane pytania
- Odpowiedzieć na niektóre pytanie (każde pytanie jest osobnym formularzem)
- Usunąć niektóre nieodpowiedziane pytania, które uzna za zbyt głupie
1.2.2. Zmiana danych
W tej podstronie prowadzący może zmienić swoje dane: imię, nazwisko, adres e-mail oraz hasło.
1.2.3. Zarządzanie własnymi kółkami
W tej podstronie prowadzący może:
- Obejrzeć zajęcia (zawody próbne,warsztaty,kółka) których był prowadzącym
- Usunąć niektóre swoje kółka (przycisk usuń)
- Dodać kółko (formularz na dole strony)
- Dodać prowadzącego do zajęcia, które zalogowny współprowadził
Strona składa się z listy zajęć, formularza do dodawania "prowadzeń" zajęć oraz formularza do dodawania nowych kółek. Kółko ma swoją "datę trwania",
wpisywaną ręcznie, którą wpisuje prowadzący w trybie, jaki sobie życzy (nie jest ona nijak weryfikowana, może to być np. przedział czasowy) oraz
datę początku wydarzenia, która służy do sortowań przy wypisywaniu wydarzeń.
1.2.4. Zarządzanie własnymi materiałami
W tej podstronie prowadzący ma wgląd w materiały, których jest autorem. Może on:
- Obejrzeć listę swoich materiałów
- Dodać nowy materiał do zajęć, które prowadzi
- Usunąć jakiś swój materiał
Podstrona składa się z listy materiałów oraz formularza do dodawania nowego materiału
1.2.5. Dodanie niusa
Podstrona zawiera formularz, dzięki któremu prowadzący może dodać nowego niusa na stronę główną. Nius ma standardową ważność miesiąć
1.3. Funkcjonalności administratora
Pozostałe możliwości użycia bazy danych uznałem za bardzo rzadko wykorzystywane, oraz nie powinni mieć do nich dostęp prowadzący oraz uzytkownicy.
Są to:
- Dodanie nowych zawodów i warsztatów. Odbywa się to średnio raz - dwa razy na rok, w ustalonym czasie
- Dodanie zdjęć. Nie nalezy tego robić przez formularz www, zazwyczaj zdjęć jest dużo, lądują one na innym serwerze (duch) i należy wywołać
skrypt generujący miniaturki, jest to robione dość rzadko (1-2x na rok)
- Dodanie prowadzącego. Powinien to móc robić tylko administrator i zdarza się to raz na rok, klika osób na raz
Powyższe czynności ręcznie wykonuje administrator na bazie danych.
2. Opis konstrukcji
Baza danych znajduje się w Postgresie, interfejs został napisany w Schemie.
2.1. Model logiczny
Diagram związków encji bazy danych znajduje się tu.
2.2. Zmiany w stosunku do modelu logicznego
Wprowadziłem następujące dodatki, niewidziane na diagramie logicznym:
- Zwiazek wydarzenia - prowadzacy wymaga dodania tabeli pośredniej: WM_Prowadzenia
- Brak naturalnego klucza w encji FAQ wymaga dodania klucza sztucznego; odwoływanie się przez klucz do FAQ jest konieczne w czasie odpowiadania
na pytanie
- Pozostałe encje przechodzą na analogiczne tabele w bazie danych (nazwy w liczbie mnogiej i z przedrostkiem wm_)
2.3. Widoki
W celu uczytelnienia skryptów i przerzucenia części odpowiedzialności do bazy danych wprowadziłem kilka widoków ułatwiających
wyświetlanie informacji na stronie:
- FAQsNaStrone. Widok na FAQ, które powinny znaleźć się na stronie: te, na które są odpowiedzi, posortowane po dacie zadania pytania
- Galeria. Widok na złączenie naturalne materiałów, które są zdjęciami, z wydarzeniami. Skrypt Galeria wybiera z widoku te krotki,
które należą do odpowiedniego wydarzenia, galeria wszystkich robi count(*), grupując.
- WarsztatoweMaterialy. Widok na złączenie zewnętrzne materiałów (czyli nie-zdjęć) z tymi wydarzeniami, co są warsztatami - do wypisywania
materiałów do warsztatów
- WszystkieKolkaProwadzacy. Widok na złączenie zewnętrze wydarzeń z prowadzącymi, dla wydarzeń które są kółkami, posortowane po wydarzeniach
- WszystkieKolkaMaterialy. Widok na złączenie zewnętrzne wydarzeń z materiałami, dla wydarzeń które są kółkami, posortowane po wydarzeniach
- WarsztatyDoMenu. Widok na nazwy warsztatów, aby wypisać w bocznym menu
- NiusyNaStrone. Widok na te niusy, które są aktulanie aktywne, posortowanie po dacie
- WM_WIP. Techniczny widok do wyższych widoków: złączenie zewnętrzne wydarzeń i prowadzących
2.4. Zachowanie spójności bazy danych
W celu zapewnienia spójności bazy danych dodałem:
- Trigger mozedodacniusa - sprawdza, czy dodawany nius, jeśli ma ustawione wydarzenie, może być dodany, tj czy autor prowadzi te zajęcia
- Trigger mozedodacmaterial - sprawdza, czy dodawany material, jeśli ma ustawionego autora, może być dodany, tj czy autor prowadzi wydarzenie, do którego
jest materiał
- Check na pole typ w wydarzeniach - wydarzeniem może być tylko Zawody, Warsztaty i Kółko
- Check na pole typ_pliku w materiałach - materiał to teX, Tekstowy, Html i Zdjęcie
- Check na pole pytający w FAQ - pole musi zawierać coś, co wygląda jak email - by ludzie się podpisywali pod pytaniami
2.5. Implementacja CGI w Scheme
Interfejs został napisany w Scheme, z wykorzystaniem bibliotek do cgi oraz Postgresa. Implementacja składa się z:
- Pliku index.cgi, który jest głównym cgi. Załącza on potrzebne biblioteki, wewnętrzną bibliotekę wm_lib.ss, plik wm_bocznemenu.ss, tworzący
menu boczne, oraz sprawdzający, jaką podstronę wyświetlić i załączający odpowiedni plik
- Plik wm_lib.ss - biblioteka potrzebnych funkcji, o niej niżej
- Pliki wm_bocznemenu.ss i wm_logowanie.ss - pliki tworzące boczne menu na stronie, wraz z menu dla prowadzących bądź formularzem do logowania
- Pliki wm_*.ss - pliki opisujące poszczególne podstrony dla użytkowników
- Pliki wm_sec_*.ss - pliki opisujące poszczególne podstrony dla prowadzących
- Pliki wm_.inc - pliki z kawałkami html-i, do wklejana w różne miejsca stron
- Makefile-a do kompilowania materiałów w TeXu
2.5.1. Biblioteka wm_lib.ss
Biblioteka wm_lib.ss jest zbiorem podstawowych funkcji używanych w skryptach bezpośrednio tworzących strony. Składa się ona z:
- Czytania argumentów sesji, przy pomocy biblioteki zewnętrznej
- Wielu prostych funkcji tekstowych
- Wielu prostych funkcji formatujących coś w htmlu
- Funkcje do porozumiewania się z bazą danych
- Kilku funkcji wyższego rzędu do obrabiania wyników zapytań SQL
- Funkcje do autoryzacji prowadzącego, załączenie biblioteki powoduje umieszczenie w zmiennej zalogowany loginu zalogowanego prowadzącego
Jest ona załączana raz, na początku działania index.cgi
2.5.2. Zewnetrzne komendy - kompilowanie TeXa
Strona potrzebuje móc skompilować przychodzący materiał w TeXu, do tego jest stworzony prosty Makefile, z poziomu Scheme
jest wywoływany make za pomocą funkcji system.
3. Obecne instalacje
Obecnie baza danych zainstalowana jest na:
Strona podmieniła dawną stronę warsztatów matematycznych, stworzoną przez Alka Jankowskiego.
Skopiowałem ze strony Alka wygląd oraz ogólny układ podstron, strona Alka nie korzystała z bazy danych.
4. FAQ prowadzących, w szczególności o kompilowaniu TeXów
- Moze jakies TeXy jak pisać zadania? Jak to wogóle wygląda? Zachęcam wszystkich do używania wzorcowego TeXa, który powstał na V WM. Jak się zalogujesz, masz do niego odnośnik. Należy w nim ustawić datę i tytuł kółka, a następnie pomiędzy znacznikami \kolko i \kkolko wpisywać zadania, zadanie się wpisuje komendą \zad{numer_zadania}{treść zadania}.
- U mnie w domu naciskam enter pare razy jak się LaTeX pluje, i wychodzi DVI, a na serwerze sie wysypuje. Jak mogę to zamieścić? Skrypt do TeXowania na serwerze jest tak zrobiony, by się przewracał, gdy LaTeX zgłosi jakiś błąd. Nie zamierzam tego zmienić, da się pisać TeXy bez błędu.
- Dostaje stale błąd "Command \lll defined earlier". Co z tym zrobić? Dołączać pakiety ams* przed pakietami do polskich znaków, oba pakiety definiują komendę \lll, ale tylko ten z polskimi znakami robi to cywilizowanie, tj sprawdzając, czy już przypadkiem nie jest zdefiniowana.
- Dostaje błąd "\hfil empty, treated as zero". W sumie wszystko działa, ale skrypt na serwerze się przewraca. Pewnie usuwasz numerację stron przez \pagenumbering{none}, które powoduje takie błędy. Spróbuj użyć \pagestyle{empty}.
- Dostaje błąd "package slgsdfklgjsdfjghx not found". Nie wiem po co w starych plikach Onufrego, z którego pewnie kopiowałeś nagłówki, on to includuje. Na 95% tego nie używasz. Usuń. A jeśli używasz, napisz do mnie - pomyślimy. Jak by nie było w TeXu na bossie tej biblioteki nie ma.
- A nie można by zrobić, by było okienko file upload, a nie takie głupie wklejanie? Tak, też uważam że jest głupie. Nie znalazłem jednak supportu do uploadu w bibliotece do CGI w Scheme. Poszukam jeszcze w wolnym czasie, lub sam napisze. Ale to nie od razu.