SOWA-WWW Moduł prezentacji katalogu bibliotecznego w sieci WWW Dokumentacja techniczna Autor: Michał Fryska Data: 2010.11.02 Wersja: 2.04
Wymagania serwisu. 1. Serwer Apache obsługujący PHP 5 wzwyż (wersje 4 są zupełnie nieobsługiwane). Zalecana wersja PHP 5.3. 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! 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ć plik data/static-form-default.epr na data/static-form.epr 2. Utworzyć pusty plik data/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) użytkownik: prawa zapisu i odczytu, grupa i inni: prawo odczytu do wszystkich plików i katalogów prawo zapisu do wszystkich plików i katalogów w data/ z wyjątkiem data/templates 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. Nagłówek logo lewe (prawe) Ikona z logo biblioteki, która będzie umieszczona w lewym (lub prawym) górnym rogu nagłówka. Jej maksymalny dopuszczalny wymiar to 132x132 i powinien być to plik PNG obsługujący przezroczystość. Plik najlepiej umieścić w podkatalogu site/media.
Nagłówek odnośnik URL na lewym (prawym) logo Odnośnik URL do strony informacyjnej biblioteki. Odnośnik ten będzie aktywowany na po kliknięciu w ikonę biblioteki (po lewej lub prawej stronie 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 Nazwa motywu Nazwa motywu graficznego bramki WWW. Dostępne motywy umieszczone są w podkatalogu motives/ 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. Użycie etykiet w opisowych wynikach wyszukania Określa czy etykiety wyświetlane na formularzach EPR (w tym w kryteriach zaawansowanych) są wykorzystane do generowania tekstu opisowego zapytania prezentowanego przy wyniku wyszukiwania.
Wyświetlanie treści pola blokady konta czytelnika Określa czy treść blokady, którą bibliotekarz nakłada na czytelnika, ma być prezentowana na stronie z informacjami na koncie czytelnika. Jeśli nie, wówczas prezentowana będzie tylko informacja o nałożonej blokadzie, ale bez jej treści. 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 logo="" url="" logo2="" url2=""> <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" labels="no" blockinfo="yes" /> <motif name="default" /> </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łówka góra strony WWW logo Ścieżka do pliku z logiem biblioteki (logo lewe) logo2 Ścieżka do pliku z logiem biblioteki (logo prawe) url Odnośnik URL do umieszczenia na logu biblioteki (logo lewe) url2 Odnośnik URL do umieszczenia na logu biblioteki (logo prawe) 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. labels Wyświetlanie etykiet formularza na opisie kryterium. Dopuszczalne wartości: yes [TAK], no [NIE]. motif Opisuje użyty dla katalogu motyw graficzny. name Nazwa motywu (zgodnie z nazwą w motif.ini) 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. Aby spersonalizować wygląd bramki należy utworzyć nowy motyw graficzny. Można go utworzyć na podstawie dowolnego z dostępnych w domyślnej instalacji. Motywy umieszczone są w podkatalogu motives/ - każdy podkatalog w nim jest osobnym motywem. W katalogu motywu musi znajdować się plik motif.ini zawierający następujące dane: name=<nazwa_motywu> desc=<nazwa opisowa motywu> gdzie <nazwa_motywu> to ciąg znaków bez spacji, najlepiej tożsamy z nazwą katalogu motywu, natomiast <nazwa opisowa motywu> jest używana do wyświetlania listy dostępnych motywów. 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 site/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) W obecnej wersji systemu pliki szablonów (umieszczone w katalogu data/templates) nie powinny być modyfikowane, a w razie ich modyfikacji należy pamiętać o wykonaniu ich kopii zapasowej, gdyż przy kolejnej aktualizacji zostaną zastąpione nową wersją plików szablonów. Dowolnie można modyfikować następujący plik: static-form.epr Zawiera definicję domyślnego formularza wyszukiwania w formacie EPR (zob. dokumentacja serwera SOWA).