SOWA-WWW Moduł prezentacji katalogu bibliotecznego w sieci WWW Dokumentacja techniczna Autor: Michał Fryska Data: 2010.03.02 Wersja: 1.42
Wymagania serwisu. 1. Serwer Apache obsługujący PHP 4.3 wzwyż - polecana wersja PHP 5. 2. Załadowana biblioteka gd do PHP (tylko dla serwisów wyświetlających obrazy JPG z katalogu). Uwaga w przyp. Windowsa: należy włączyć DLLa GD2 php_gd2.dll jako rozszerzenie w php.ini. 3. Załadowana biblioteka iconv do PHP. Trzeba mieć funkcję iconv() w standardowej bibliotece C, lub zainstalowaną bibliotekę libiconv. Biblioteka libiconv jest dostępna pod adresem» http://www.gnu.org/software/libiconv/. Uwaga w przyp. Windowsa: aby włączyć ten moduł trzeba umieścić DLLa o nazwie iconv.dll, który jest dostarczany razem z pakietem binarnym PHP/Win32 do katalogu podanego w zmiennej środowiskowej PATH tudzież w jednym z systemowych katalogów, a w konfiguracji php.ini włączyć moduł php_iconv.dll. Uwaga: w php.ini może być określony inny katalog, do którego należy wgrać moduł iconv! W przypadku PHP 5 nie ma takiej potrzeby, bo iconv jest od razu domyślnie składnikiem PHP. 4. Do działania niezbędne są także niżej wymienione moduły [zazwyczaj są one domyślnie składnikiem php-base]. a. sessions b. ctype c. xml 5. Serwer Apache musi mieć ustawioną dyrektywę AllowOverride AuthConfig dla katalogu sowwwy. Zakładając, że skrypty bramki umieszczone będą w katalogu /home/sowa/sowa.www, a adres bramki ma wyglądać np. http://adres_serwera/sowa-www/ najprostsza konfiguracja mogłaby wyglądać następująco: Alias /sowa-www "/home/sowa/sowa.www" <Directory "/home/sowa/sowa.www"> Options MultiViews AllowOverride AuthConfig Order allow,deny Allow from all </Directory> 6. Zdecydowanie najbardziej polecanym sposobem konfiguracji Apache'a jest utworzenie hosta wirtualnego, pod warunkiem posiadania nazwy domenowej. Jeśli biblioteka nie ma możliwości utworzenia takiej nazwy, firma SOKRATES oferuje utworzenie takiej nazwy w domenie sowwwa.pl. Dla przykładu konfiguracja dla domeny www.poznan-wbp.sowwwa.pl wyglądać będzie następująco: <VirtualHost *:80> DocumentRoot /home/sowa/sowa.www ServerName www.poznan-wbp.sowwwa.pl DirectoryIndex sowacgi.php <Directory /home/sowa/sowa.www> Options None
AllowOverride AuthConfig Order allow,deny Allow from all </Directory> </VirtualHost> 7. (ten punkt można zostawić na później - wariant instalacji automatycznej uwzględnia utworzenie tego pliku) Trzeba stworzyć hasło dla konfiguracji /home/sowa/htpasswd (jeśli będzie ono w innym pliku, to ścieżkę do niego trzeba wprowadzić do pliku tools/.htaccess). np. htpasswd -c /home/sowa/htpasswd sokrates Plik ten musi być do odczytu dla serwera Apache. Uwaga: punkty 4 i 5 można oczywiście skonfigurować inaczej, byle tylko zabezpieczyć hasłem podkatalog tools/ serwisu). Instalacja. A] Skonfigurować prawidłowo serwer Apache zgodnie z opisanymi wyżej wymogami. B] Wszystkie pliki wraz z podkatalogami umieścić w katalogu np. /home/sowa/sowa.www/ C] W tym katalogu wykonać instalację wg poniższego opisu. Wariant I: Instalacja szybka (tylko dla serwerów Linux) 1. [Zalecane z poziomu konta root] Uruchomić skrypt bin/sowawww-install.sh. Jeśli poziom roota jest nieosiągalny, można skrypt uruchomić jako użytkownik, przy czym wówczas uprawnienia do plików, które musi zapisywać serwer Apache będą nadawane dla wszystkich, co jest niepożądane na serwerach z wieloma użytkownikami. UWAGA: Skrypt może nie działać na niektórych serwerach [niestandardowe instalacje, brak php-cli, niedostępność drzewa procesów itp.]. Z uwagi na to w przypadku pojawienia się błędów należy wykonać instalację wg Wariantu II. Wariant II: Instalacja ręczna. 1. Skopiować pliki: a. css/sowwwa-default.css na css/sowwwa.css b. css/tabber-default.css na css/tabber.css c. static-form-default.epr na static-form.epr 2. Utworzyć pusty plik strony.dat 3. Ustawić prawa do wszystkich plików i podkatalogów na zapisywalne dla serwera Apache a. użytkownik: sowa - prawa zapisu i odczytu grupa: apache [lub nobody, http-data - w zależności od wersji systemu] - prawa zapisu i odczytu inni: brak uprawnień b. (gdy powyższe nie jest możliwe) utworzyć puste pliki sowwwa-config.xml i sowwwa-config.xml.bak użytkownik: prawa zapisu i odczytu,
grupa i inni: prawo odczytu do wszystkich plików i katalogów prawo zapisu do plików sowwwa-config.xml, sowwwa-config.xml.bak, strony.dat i katalogu tmp/ 4. W katalogu tools/ należy utworzyć plik.htaccess, w którym określona będzie ścieżka do pliku z hasłem nadanym narzędziem htpasswd. Jeśli operacji tych nie wykonano wcześniej można to zrobić w następujący sposób: htpasswd -c /home/sowa/htpasswd sokrates a plik tools/.htaccess może mieć następującą zawartość: AuthName "Konfiguracja SOWA-WWW" AuthType Basic AuthUserFile /home/sowa/htpasswd require valid-user Niezależnie sposobu instalacji prosimy nadane hasło do konfiguracji serwisu przekazać do SOKRATES-software. Uwaga dla Windows: ścieżka do AuthUserFile winna mieć postać typu: c:/sowa/htpasswd Konfiguracja. Połączyć się na adres http://adres_serwera/sowa-www/tools/configure.php, podać użytkownika i hasło stworzone w punkcie A i właściwie skonfigurować serwis. Znaczenie poszczególnych pól: USTAWIENIA PODSTAWOWE: ID serwera Automatycznie nadawany numer katalogu. Pojawia się jako KatID w URL konkretnego katalogu. Grupa Bramka może obsługiwać dowolną ilość serwerów SOWY, które można grupować, dzięki czemu odnośniki do kolejnych katalogów będą dostępne z formularza wyszukiwawczego każdego z nich [jako lista rozwijana]. W polu tym należy wpisać nazwę grupy, do której należy dany katalog. Można w bramce korzystać z wielu grup. Nazwa domenowa grupy Jeśli pole jest wypełnione nazwą domenową serwera (np. www.katalog.org) wówczas katalog ten dostępny jest tylko i wyłącznie pod warunkiem, że w przeglądarce wpisano tą nazwę domenową (bardzo przydatne dla wirtualnych hostów). Dodatkowo pierwszy z katalogów z tej grupy będzie domyślny w przypadku nie podania KatID). IP serwera Adres IP, na którym uruchomiony jest serwer Sowy Port Port, na którym działa serwer Sowy obsługujący katalog Opis serwera Krótki opis katalogu. Wyświetla się w liście rozwijanej z wyborem katalogu [p. Grupa]. Nagłówek tytuł katalogu Nagłówek katalogu, który pojawia się nad formularzem wyszukiwania. Dopuszcza się stosowanie znaczników HTML w celu właściwego sformatowania nagłówka.
USTAWIENIA LOGOWANIA I OBSŁUGA KONT CZYTELNIKÓW: Logowanie możliwe Dotyczy serwerów obsługujących wypożyczalnię. Ustawienie pola na NIE sprawi, że zamawianie przez Internet nie będzie możliwe [a także rezerwowanie i ogólnie obsługa konta przez czytelnika] Dostępne sposoby logowania Dotyczy serwerów obsługujących wypożyczalnię. Określa jaką metodą mogą się logować czytelnicy, tzn. tylko za pomocą nr karty, tylko nazwiska i imienia, albo dowolnego z nich [do wyboru]. Domyślny sposób logowania Jeśli metoda jest "do wyboru" - określa czy domyślnie ma być zaznaczony numer karty, czy nazwisko i imię. Prefiks numeru karty Jedno lub trzycyfrowy prefiks, który będzie automatycznie dodawany do numeru karty czytelnika, jeśli wprowadzi on numer siedmiocyfrowy [wprowadzenie numeru krótszego jest automatycznie uzupełniane zerami z przodu do ilości cyfr określonych w parametrze długość numeru karty ]. Jeśli prefiks jest pusty, wówczas bramka nie ingeruje we wprowadzony przez użytkownika numer. Długość numery karty Jeśli ustawiony na wartość większą od zera, wówczas numer karty wprowadzony przez użytkownika uzupełniany jest zerami z lewej strony tak, by osiągnął wymaganą długość. Rezerwowanie włączone Dotyczy serwerów obsługujących wypożyczalnię z modułem zamawiania i rezerwowania przez Internet. Określa czy rezerwacje są dopuszczalne. Logowanie z pustym hasłem Określa czy możliwe jest zalogowanie czytelnika, który nie posiada założonego hasła w systemie SOWA. Ustawienie opcji na NIE uniemożliwi stosowanie pustych haseł przez czytelników. USTAWIENIA SYSTEMOWE / TECHNICZNE Nowy system logowania Dla katalogów SOWA-1 dostarczonych przed 2006.07.12 parametr ten należy ustawić na NIE. Dla wszystkich pozostałych serwerów SOWA-1 musi on być ustawiony na TAK. Dla serwerów SOWA-2 i SOWA-SQL parametr nie ma znaczenia. Logowanie wyłącznie przez SSL Określa czy obsługa konta czytelnika [w tym logowanie] ma się odbywać w szyfrowanej sesji SSL. Uwaga: wymaga to poprawnie skonfigurowanego serwera WWW. Ścieżka bazowa skryptu Parametr techniczny używany tylko jeśli bramka nie jest w stanie samodzielnie określić tej ścieżki, lub chcemy wymusić stosowanie innej niż odczytana z parametrów serwera. USTAWIENIA POMOCY Zewnętrzny URL pomocy Adres strony WWW, do której bramka wyświetli łącze w prawym górnym rogu pod postacią linka "Pomoc". Pomoc pod formularzem wyszukiwania Opcjonalny tekst [dopuszcza znaczniki HTML], który pojawi się pod formularzem
wyszukiwania. Standardowo przewidziany jest on do umieszczenia pomocy lub odnośników do pomocy. Pomoc nad formularzem logowania Opcjonalny tekst [dopuszcza znaczniki HTML], który pojawi się ponad formularzem logowania czytelnika. USTAWIENIA WYGLĄDU BRAMKI Kryterium podstawowe Nazwa kryterium, które ma być użyte jako podstawowe dla bramek obsługujących serwer SOWA-SQL (nie podane zakłada, że ma być użyte pierwsze kryterium z listy). Dla serwerów SOWA-1 i SOWA-2 jest to nazwa pliku.epr, który zawiera definicję formularza podstawowego domyślnie jest to static-form.epr. Pozycja kryteriów zaawansowanych Określa miejsce, w którym generowane będą formatki kryteriów zaawansowanych. Wartość poniżej formularza sprawi, że będą prezentowane jako rozwijalne grupy poniżej podstawowej formatki wyszukiwawczej. Wartość jako zakładka sprawia, że są one zgrupowane w zakładce. Wartość ukryte pozwala pozbyć się w ogóle kryteriów zaawansowanych. Pozycja grupy filtrów Określa miejsce, w którym wyświetlane będą filtry wyszukiwawcze. Dopuszczalne pozycje to: jako zakładka (znajdują się w zakładce obok zakładki wyszukiwawczej, dostępne po kliknięciu w nią), poniżej formularza, powyżej formularza oraz ukryte (pozwala na wyłączenie filtrów i wymuszenie użycia ich domyślnych wartości). Ilość kolumn w tabeli filtrów Filtry wyświetlane są w tabeli, która domyślnie posiada 4 kolumny. Wartość tą można tutaj zmodyfikować. Wyświetlanie miniaturek dla multimediów Umożliwia określenie miejsca wyświetlania się miniaturek obrazków załączonych do rekordu. Wewnątrz opisu umieszcza miniaturkę w prawym górnym rogu opisu rekordu. Na zewnątrz opisu umieszcza miniaturkę w kolumnie drugiej tabeli wyników. Brak powoduje całkowite wyłączenie prezentacji multimediów. Szerokość miniaturki Szerokość generowanej miniaturki w pikselach. Panel znaków specjalnych Określa sposób prezentacji panelu znaków specjalnych na formularzu wyszukiwawczym. Wartość przełączanie wyświetlania generuje odnośnik Znaki w górnym pasku strony, którego kliknięcie przełącza wyświetlanie panelu. Pozostałe opcja umożliwiają wyświetlanie tego panelu na stałe (bez przełączania) lub jego całkowite wyłączenie. Adres URL arkusza głównego CSS Względny lub bezwzględny URL do arkusza CSS bramki (domyślnie css/sowwwa.css). Przydatne gdy pojedyncza instalacja bramki obsługuje wiele instancji katalogów, dla których chcemy ustawić różną kolorystykę. Adres URL arkusza CSS dla zakładek Względny lub bezwzględny URL do arkusza CSS używanego do wizualizacji pola zakładek (domyślnie css/tabber.css). Konfiguracja ręczna: Plik sowwwa-config.xml nie powinien być modyfikowany ręcznie, poniższy opis przedstawia znaczenie poszczególnych tagów XML pliku konfiguracyjnego.
Plik musi być zakodowany w UTF-8. Plik powinno się edytować przy użyciu edytora XML z walidacją składni [potrafiącym pobierać plik DTD z internetu]. Poniżej przykładowy plik konfiguracyjny: <?xml version="1.0" encoding="utf-8"?> <!DOCTYPE sowwwa PUBLIC "-//SOKRATES//DTD SOWWWA Config 1.0//PL" "http://firma.sokrates.pl/dtd/sowwwa-config-10.dtd"> <sowwwa> <instance id="0" group="grodzisk" domain=""> <server ip="192.168.1.18" port="8048">grodzisk</server> <logins newlog="yes" reservation="yes" ssl="no" emptypass="no" /> <header><h2>katalog Powiatowej i Miejsko-Gminnej Biblioteki Publicznej w Grodzisku:</h2> </header> <script home=""/> <account enabled="yes" method="both" default="barno" prefix="111" barnolen="7"> Proszę się zalogować </account> <help url="http://biblioteka.com/help.html"> <b>szukając można używać znaku * który zastępuje dowolny ciąg znaków</b> </help> <criteries advpos="bottom"></criteries> <filters position="tab" columns="3" /> <multimedia position="inline" width="200"/> <viewopts signs="toggle"/> <css sowwwa="css/sowwwa2.css tabber="" /> </instance> <!-- [grup instance może wystąpić dowolna liczba] --> </sowwwa> Elementów instance może występować dowolna liczba, każdy określa osobny katalog. Znaczenie poszczególnych tagów i atrybutów XML jest następujące instance Opisuje instancję obsługiwanego przez bramkę katalogu Sowy. id ID katalogu [liczba całkowita - musi być unikalny w obrębie całego pliku XML] group Grupa domain Nazwa domenowa, pod którą wyłącznie widoczny ma być katalog. server Opisuje parametry serwera SOWY. ip IP serwera port Port Zawartość Opis. Nazwa skrócona używana w liście wyboru katalogów. logins Opisuje parametry logowania. newlog Nowe logowanie. Dopuszczalne wartości: yes [TAK], no [NIE]. reservation Rezerwacje. Dopuszczalne wartości: yes [TAK], no [NIE]. ssl SSL. Dopuszczalne wartości yes [TAK], no [NIE] emptypass Dopuszczanie pustych haseł czytelników. Dopuszczalne wartości yes [TAK], no [NIE] header Zawartość Nagłówek [uwaga: należy pamiętać, że znaki specjalne HTML trzeba maskować pod &kod;] account Ustawienia związane z logowaniem się czytelników. enabled Logowanie możliwe. Dopuszczalne wartości: yes [TAK], no [NIE]. method Metoda logowania. Dopuszczalne wartości: both [do wyboru], name [nazwisko i imię], barno [numer karty]. default Domyślna metoda. Dopuszczalne wartości: name [nazwisko i imię], barno [numer karty]. prefix Prefiks numeru karty - jedna lub trzy cyfry. barnolen Wymagana długość numeru karty (0 jeśli nie ma wymogów)
Zawartość Pomoc logowania [uwaga na znaczniki i &] help Ustawienia związane z konfiguracją pomocy. url URL do pomocy Zawartość Pomoc do formularza logowania [uwaga na znaczniki i &] criteries Opisuje zachowanie kryteriów wyszukiwawczych. advpos Pozycja kryteriów zaawansowanych. Dopuszczalne wartości: tab, bottom oraz hidden. Zawartość Nazwa kryterium podstawowego / nazwa pliku.epr z definicją formatki podstawowej. filters Opisuje zachowanie filtrów. position Pozycja grupy filtrów. Dopuszczalne wartości: tab, bottom, top oraz hidden. columns Ilość kolumn w tabeli filtrów. multimedia Opisuje sposób prezentacji multimediów. position Pozycja miniaturek. Dopuszczalne wartości: inline, outline oraz none. width Szerokość miniaturki. viewopts Inne opcje wyświetlania. signs Sposób prezentacji panelu znaków specjalnych. Dopuszczalne wartości: toggle, on oraz off. css Opisuje adresy arkuszy CSS. sowwwa URL do arkusza głównego bramki (domyślnie: css/sowwwa.css). tabber URL do arkusza zakładek (domyślnie: css/tabber.css). Uruchomienie. http://adres_serwera/sowa-www/sowacgi.php Aby uniknąć konieczności podawania nazwy pliku bramki można przekopiować znajdujący się w głównym katalogu bramki plik index.php.redir na index.php Personalizacja. Dopuszcza się wyłącznie ingerencję w pliki static-form.epr, tabber.css oraz sowwwa.css. Ingerencje w pliki źródłowe spowodują utratę gwarancji na prawidłowe działanie serwisu, ponadto w trakcie instalacji aktualizacji wszelkie ewentualne zmiany zostaną nadpisane. Istnieje również możliwość dołączenia dowolnego kodu HTML lub wygenerowanego wyjścia skryptu PHP w wybrane miejsca treści wygenerowanej przez SOWA-WWW. W tym celu należy w podkatalogu includes/ umieścić plik o nazwie <sekcja>.inc.html dla treści statycznej lub <sekcja>.inc.php dla treści dynamicznej, gdzie <sekcja> to jedno z: a) header - treść dołączana do sekcji <head> każdej podstrony b) top - treść dołączana na górze strony, przed treścią generowaną przez SOWA-WWW c) bottom - treść dołączana u dołu strony, za treścią generowaną przez SOWA- WWW
d) menu-main - treść dołączana do górnego menu (po prawej stronie) e) menu-acc - treść dołączana do menu konta czytelnika (po prawej stronie) Dowolnie można modyfikować następujące pliki: static-form.epr Zawiera definicję domyślnego formularza wyszukiwania w formacie EPR (zob. dokumentacja serwera SOWA). sowwwa.css Arkusz stylów dla całego serwisu. W pliku tym poszczególne definicje posiadają dodatkowo komentarz ułatwiający zlokalizowanie poszczególnych elementów strony. tabber.css (obsolete) Arkusz stylów dla wersji prezentującej kryteria zaawansowane w postaci zakładek. Z uwagi na skomplikowanie i mniejszą intuicyjność tego rozwiązania nie jest polecane używanie tej wersji prezentacji.