03. Budowa aplikacji czytelnika systemu dLibra

Podstawowe pojęcia związane z działaniem aplikacji czytelnika

W niniejszej instrukcji operować będziemy pewnymi pojęciami, poniżej czytelnik znajdzie ich dokładne wyjaśnienie.

Strony - aplikacja czytelnika zbudowana jest z wielu stron (widoków), np. strona opisu kolekcji, strona z wynikami wyszukiwania, są one podstawą nawigacji. Każda strona posiada swój unikalny identyfikator, jest on widoczny w adresie URL konkretnego żądania, przykładowo: http://demo.dl.psnc.pl/dlibra/collectiondescription spowoduje wyświetlenie strony collectiondescritpion. Definicję poszczególnych stron można znaleźć w pliku : pages.xml. Identyfikator strony nie jest wyświetlany w przypadku strony głównej, posiada ona identyfikator "main".

Każda strona zbudowana jest z dwóch składników: komponentów i szablonu rozmieszczenia.

Komponenty - odpowiadają poszczególnym elementom strony np. sekcja z ostatnio dodanymi publikacjami to odrębny komponent. Komponenty mogą być wyświetlane w różnych miejscach w obrębie strony. To jakie komponenty są wyświetlane na stronie należy wyspecifikować w deskryptorze danej strony w pliku pages.xml.

Szablon rozmieszczenia - jest to ogólny układ strony – to czy strona zawiera jedną czy dwie kolumny, czy posiada stopkę, jak wysoki jest nagłówek, zależy od użytego szablonu rozmieszczenia. To jakiego szablonu używa dana strona jest określane w deskryptorze strony w pliku pages.xml.

Akcje - wszystkie działania w wyniku których zmianie ulegnie stan aplikacji czytelnika (np. zmiana języka, wysłanie maila z formularza kontaktowego) realizowane jest za pomocą akcji. Również akcje posiadają swoje unikalne identyfikatory przykładowo, w żądaniu:
http://demo.dl.psnc.pl/dlibra?action=ChangeLanguageAction&language=en występuje odwołanie do akcji ChangeLanguageAction, która powoduję zmianę języka interfejsu. W ramach stron dozwolone jest wykonanie tylko niektórych akcji, to które akcję są dozwolone określamy w pliku pages.xml.

Tematy kolorystyczne - w aplikacji czytelnika istnieje możliwość zdefiniowania własnych tematów kolorystycznych. Temat taki zbudowany jest z odpowiednich grafik oraz plików css (po jednym dla każdego z szablonów rozmieszczeń). Standardowo dostępne są dwa szablony kolorystyczne: "niebieski" (theme1) i "pomarańczowy" (theme2). Domyślnie używany jest szablon "niebieski".

Kolejnym istotnym pojęciem są wersję językowe (etykiety tekstowe), zawierają one tekst jaki jest wyświetlany na stronach WWW w zależności od wybranego przez użytkownika języka. Standardowo dostępne są dwa języki interfejsu : polski i angielski. Wersja językowa zbudowana jest z wielu plików, składają się na nią etykiety tekstowe:

• komponentu,
• akcji,
• etykiety współdzielone przez wiele komponentów
• używane tylko w szablonach rozmieszczenia.

Najczęściej modyfikowane etykiety zostały wydzielone do osobnego pliku. Więcej informacji na ten temat znajdzie Czytelnik w sekcji dotyczącej struktury katalogów. Przykłady opracowań nowych wersji językowych znajdzie Czytelnik na stronie: https://dlibra.psnc.pl/community/display/TRA/Wprowadzenie.

Każdy komponent posiada n plików z etykietami tekstowymi, gdzie n to liczba wersji językowych zainstalowanych w aplikacji czytelnika. Wyświetlane wartości znajdują się w plikach NazwaKomponentu_xx.xml (gdzie "xx" skrótowi nazwy języka). Treść większości komponentów wyświetlanych na stronach aplikacji czytelnika jest poprzedzona tytułem. Tytuł ten jest zapisany się pod identyfikatorem NazwaKomponentu.Title. Wartość przypisana do tego identyfikatora może być wyrażeniem języka VTL.

Opis plików konfiguracyjnych aplikacji czytelnika systemu dLibra 5.0

Poniżej znajduję się opis najważniejszych plików konfiguracyjnych aplikacji czytelnika systemu dLibra. Zmiany dokonywane w niektórych plikach wymagają restartu aplikacji czytelnika, pliki te zostały oznaczone (bezpośrednio po nazwie umieszczono (R)). Pliki nie ujęte w poniższym zestawieniu nie powinny być modyfikowane bez uprzedniej konsultacji z twórcami oprogramowania dLibra.

• actions.xml - W pliku tym znajdują się dodatkowe parametry konfiguracyjne dla akcji. Można tu określić między innymi:
  • adres email na jaki mają być wysyłane wiadomości wysyłane przez użytkowników z formularza kontatkowego oraz format tej wiadomośći (plain/text czy html),
  • konfiguracja zabezpieczeń mechanizmu proponowania słów kluczowych przez użytkowników :
    • czy propozycje mają być domyślnie odrzucane czy akceptowane,
    • maksymalną i minimalną długość propozycji słów kluczowych,
    • maksymalną liczbę propozycji, które może wprowadzić użytkownik w ciągu zadanego czasu (domyślnie maksymalnie 5 propozycji w ciągu 30min).
  • maksymalną i minimalną długość loginu który wprowadzają użytkownicy w czasie rejestracji.

• components.xml - Dodatkowe parametry konfiguracyjne dla poszczególnych komponentów. W tym pliku zmieniamy:
  • Informację dotyczące exlibrisu dla każdej z instytucji dysponujących prawami do
    publikacji.
  • Identyfikator kolekcji "Wystawy".
  • Adres email osoby odpowiedzialnej za administrację repozytorium OAI.
  • Znaki ignorowane przy sortowaniu pozycji na listach publikacji.
  • Liczbę podpowiedzi wyświetlanych w formularzach wyszukiwania
  • Liczbę elementów wyświetlanych na stronie głównej dla: wystaw, ostatnio dodanych publikacji oraz wiadomości.

• tooltip.xml - plik konfiguracji podpowiedzi dla tytułów publikacji z sekcji "Najczęściej czytane" oraz "Ostatnio dodane". Plik jest dołączany jako encja w pliku components.xml. Plik umożliwia konfigurację atrybutów metadanych publikacji wyświetlanych w podpowiedzi. Więcej na ten temat można odnaleźć w sekcji konfiguracji Aplikacji Czytelnika.

• ignored_ips.txt i ignored_agents.txt (R) - Pliki te związane są zliczaniem statystyk odwiedzin. W pierwszym podajemy adresy IP, które nie mają być zliczane (np. komputery na których pracują redaktorzy). Każdy wpis jest traktowany jako wyrażenie regularne można więc podawać również całe zakresy adresów IP. W pliku znajduję się przykładowy wpis dla 127.0.0.1. Przed dodaniem nowego wyrażenia regularnego warto sprawdzić jego poprawność używając bezpłatnych narzędzi dostępnych online np. http://regexpal.com/.

Na podobnej zasadzie działa plik ignored_agents.txt, należy umieścić tutaj wyrażenia regularne dla wartości pola user-agents. Pole to jest częścią nagłówka żądania HTTP, jest to łańcuch znaków identyfikujący program za pomocą którego przeglądana jest strona np. przeglądarka internetowa, robot
wyszukiwarki. Jeżeli wartość łańcucha zostanie dopasowane do podanego wzorca to identyfikujące się za niego pomocą programy nie bedą zliczane do statystyk odwiedzin i wyświetleń treści publikacji. W pliku znajduję się przykład dla googlebot'a. Listę identyfikatorów user agents można znaleźć w sieci np. tu http://en.wikipedia.org/wiki/User_agent.

• pages.xml - Plik zawiera defnicję stron wyświetlanych przez aplikację czytelnika systemu dLibra. Modyfikacja tego pliku jest konieczna w przypadku:
  • zmiany kolejności komponentów wyświetlanych na danej stronie,
  • dodawania nowego komponentu do konkretnej strony,
  • tworzenia nowej strony w ramach aplikacji czytelnika.
    Zagadnienia związane z wykonywaniem zmian w tym pliku zostaną szczegółowo omowione w rozdziałach : "Dostosowywanie wyglądu aplikacji Czytelnika" oraz
    "Najczęściej zadawane pytania".

• pages_titles.xml (R) - W pliku tym określamy tytuły i pod tytuły poszczególnych stron.

• templates.properties (R) - Zawiera parametry konfiguracyjne dostępne z poziomu wszystkich szablonów.

• periodic.xml (R) - Plik ten zawiera definicje zadań okresowych wykonywanych przez aplikacje czytelnika. Można tutaj zmienić godzinę:
  • o której wysyłane są biuletyny z ostatnio dodanymi publikacjami,
  • położenie katalogu do którego zapisywane są informacje o zapytaniach wyszukiwawczych wydawanych przez użytkowników aplikacji czytelnika,
  • identyfikatory atrybutów na podstawie których generowane są statystyki wartości atrybutów,
  • konfigurację mechanizmu importu wiadomości z zewnętrznego kanału RSS.

• pliki dlibra-webapp\WEB-INF\components\resources\WEBAPP_xx.xml - Gdzie xx oznacza wersję jezykową (np. pl) w pliku tym znajdują sie najczęściej modyfikowane etykiety tekstowe dla każdej z zainstalowanych wersji językowych.

• dlibra-webapp\WEB-INF\components\templates\custom_library.vm - Zawiera dodatkowe makra języka VTL stworzone przez administratorów danej biblioteki. Informacje o tworzeniu makr jęzka VTL można znaleźć na stronach projektu Velocity.

• Pliki dlibra-webapp\WEB-INF\layout\resources\layout_xx.xml - Gdzie xx oznacza wersję jezykową (np. pl) w pliku tym znajdują się etykiety
  tekstowe używane w szablonach rozmieszczeń.

• Plik dlibra-webapp\WEB-INF\layout\templates\layout_library.vm - Makra zdefiniowane w tym pliku używane są w szablonach rozmieszczeń, które znajdują się w katalogu dlibra-webapp\WEB-INF\layout\templates\. Plik ten można modyfikować zmieniając istniejące makra jak i dodając nowe.

• Katalog dlibra-webapp\WEB-INF\formats - zawiera konfiguracje wszystkich rozszerzeń związanych z prezentacją treści publikacji. Szczegółowy jej opis znajduję się w rozdziale "Konfiguracja prezentacja treści w aplikacji czytelnika".

Pliki konfiguracyjne znajdujące się w katalogu dlibra-webapp/WEB-INF/conf

Aplikacja czytelnika korzysta ze swojej lokalnej bazy danych, jest to baza zupełnie nie związana z bazą dnaych wykorzystywaną przez serwerem dLibry. Na konfiguracje tej bazy składają się poza omówionymi poniżej dwoma plikami również pliki jcr-init.properties oraz jcr-repository.xml nie powinny być one jednak pod żadnym pozorem modyfikowane.

• jcr-init-desc.xml (R) - specyfikacja podstawowej zawartości (wartości domyślne), która jest umieszczna w bazie danych podczas pierwszego startu aplikacji czytelnika.

• jcr.properties (R) - konfiguracja podstawowych parametrów dostępowych do bazy danych aplikacji czytelnika. W przypadku gdy katalog roboczy aplikacji czytelnika zostanie przeniesiony należy uaktualnić ścieżkę do bazy danych, która znajduję się w tym pliku.

• services.properties (R) - parametry połączeniowe do serwera dLibry. W przypadku gdy serwer dLibry zostanie przeniesiony na inną maszynę należy uaktualnić znajdujący się w tym pliki adres serwer.

• smtp.properties (R) - parametry dostępowe do serwera SMTP. Parametry te wykorzystywane są przez aplikacje czytelnika do wysyłania wiadomości email.

• cache.properties (R) - zawiera ustawienia pamięci podręcznej (cache) aplikacji czytelnika. Użycie cache znacznie przyspiesza działanie aplikacji czytelnika wykorzystanie pamięci podręcznej jest niezbędne w przypadku bibliotek posiadającej powyżej 1000 publikacji.

• exlibris.xml - treść tego pliku zawiera konfigurację mechanizmu exlibris. Więcej na temat konfiguracji exlibris
  można dowiedzieć się w sekcji konfiguracji Aplikacji Czytelnika.

• pubcreator.properties - plik podstawowych parametrów konfiguracji mechanizmu Self-Archiving. Więcej na temat konfiguracji Self-Archiving można znaleźć w sekcji konfiguracji Aplikacji Czytelnika.

• pubc-metadata.xml - zawiera konfigurację formularza atrybutów dla funkcjonalności Self-Archiving. Więcej na ten temat można znaleźć w sekcji konfiguracji Aplikacji Czytelnika.

Opis struktury pod dlibra-webapp\style

W katalogu dlibra-webapp\style znajduję się większość grafik i arkuszy stylów css używanych w aplikacji czytelnika.

Katalog dlibra-webapp\style\dlibra zawiera dane dotyczące tematów kolorystycznych i dostępnych dla nich szablonów rozmieszczeń. Natomiast katalog dlibra-webapp\style\common zawiera pliki wykorzystywane przez różne komponenty oraz zadania okresowe aplikacji czytelnika.

Dodatkowe elementy

Poza standardowymi odwołaniami do stron zdefiniowanych w aplikacji czytelnika istnieją również zasoby dostępne z głównego poziomu:

• http://demo.dl.psnc.pl/Content - odpowiedzialny za dostęp do treści publikacji.
  • Wywołanie /Content/2952/ powoduje przejście do treści głównego pliku wydania o identyfikatorze 2952.
  • Wywołanie /Content/2952/directory.djvu powoduje pobranie pliku directory.djvu z wydania o identyfikatorze 2952.
• http://demo.dl.psnc.pl/zipContent - odpowiedzialny za dostęp do treści publikacji w postaci
  archiwów ZIP. Wywołanie /zipContent/2952/ powoduje pobranie treści całego wydanie o identyfikatorze 2952 jako pliku zip.
• http://demo.dl.psnc.pl/image - odpowiedzialny za dostęp do miniaturek wydań.Wywołanie /image?id=2940 powoduje pobraniu miniaturki wydania o identyfikatorze 2940.
• http://demo.dl.psnc.pl/ka - odpowiedzialny za szyfrowanie publikacji zabezpieczonych,
• http://demo.dl.psnc.pl/dlibra/dlibra-app.jnlp - wpisując ten adres do przeglądarki uruchamiamy Aplikację Redaktora/Admnistratora.
• http://demo.dl.psnc.pl/dlibra/publication/81/content - odnośnik do treści publikacji o identyfikatorze 81, jeżeli publikacja posiada więcej niż jedno wydanie wyświetlona zostanie lista wydań danej publikacji. W przypadku publikacji grupowej wyświetlona zostanie struktura publikacji grupowej.
• http://demo.dl.psnc.pl/dlibra/publication/81/ - odnośnik do opisu publikacji o identyfikatorze 81, jeżeli publikacja posiada więcej niż jedno wydanie wyświetlona zostanie lista wydań danej publikacji.