[EN] 03. The Structure of the Reader Application of the dLibra System

The Basic Concepts Related to the Functioning of the Reader Application

Pages – the reader application consists of many pages (views), for example, the home page, the object page, or the contact page. They are the basis of navigation. Every page has its own, unique identifier, for example:

Each of those pages is defined in the pages.xml file by section <page>...</page>, for example:

<page name="main" layout="home_layout" inherits="base-page">
...
</page>

<page name="publication" layout="home_layout" inherits="base-page">
...
</page>

<page name="contact" layout="home_layout" secure="true" inherits="base-page">
...
</page>

Page tags have three different fields:

name – the identifier of a page, for example: “main”, “publication”, or “contact”;

layout – the name of a layout (a graphic layout of a page) in which all components of a page will be set; and

 inherits – the identifier of a page (it can be abstract) from which the page which is being defined will take components (apart from its own components); for example: the “contact” page is defined in the “contact” section and contains the ContactComponent component, but the “inherits” field has the “base-page” value, so the contact page will also contain all the components defined for the “base-page” section;

Components – correspond to particular elements of a page; for example, the section with recently added objects on the home page is a separate component; components can be displayed in various places on a page; the components to be displayed on a page ought to be specified in the descriptor of the page, in the pages.xml file; the method of defining a component is presented below:The “component” tag is characterized with the use of the following attributes:

<component name="...">
	<place>...</place>
	<position>...</position>
</component>

The “component” tag is characterized with the use of the following attributes:

name – the full name of a component;

place – the name of the position of a component in a layout; and

position – the position in which the component should be put in a place; if there is another component in the same place, the position must have a unique value.

One example of a component is the component on the contact page. That page is defined in the page contact element. It uses the home_layout layout. It has a component which is defined in the following manner:

<components>
	<component name="pl.psnc.dlibra.web.comp.pages.components.ContactComponent">
		<place>main</place>
			<position>1</position>
	</component>
</components>

It means that the content of the ContactComponent component in the  /WEB-INF/components/templates/ContactComponent.vm file is rendered in the /WEB-INF/layouts/templates/home_layout.vm distribution template, in a loop:

#foreach( $comp in $main)
	$!{comp.RenderedTemplate}
#end

Every component consists of three elements:

• a Java class (for example, pl.psnc.dlibra.web.comp.pages.components.IndexSearchComponent),
• a template file, which is named the same as the Java class, for example, IndexSearchComponent.vm ; and
• files with various language versions, for example, IndexSearchComponent_xx.xml).

in version 6, all components are located in the dcore-webapp-components-6.x.x.jar archive, in the /WEB-INF/lib directory. The Java class is in the directory which corresponds to its package name (in this case, /pl/psnc/dlibra/web/comp/pages/components/), and the remaining files of the component – in the root directory of that archive.

The default files from the JAR archive (dcore-webapp-components-6.x.x.jar) can be “covered” with the user’s own, changed files. For that purpose, it is best to unpack the template files which are to be changed, to an appropriate directory. In the case of  .vm files, it is the  /WEB-INF/components/templates directory, and in the case of *.xml language files, it is the /WEB-INF/components/resources directory.

Files unpacked in that way can be changed, and the original content of the files left in the JAR archive will be overwritten with the new data. The changes in the *.vm files will be visible immediately after they have been saved. The changes in the *.xml files will also be taken into account immediately if they were already unpacked when the Tomcat server was being started up. Otherwise, the Tomcat server should be restarted.

Moreover, in some component templates, macros defined in the components_library.vm or layout_library.vm file are used. File componentsjibrary.vm  is in the dcore-web-components-6.x.x.jar archive. The user’s own macros and modified macros should be placed, appropriately, in files /WEB-INF/components/templates/custom_library.vm or /WEB-INF/layout/custom_templates/custom_layout_library.vm). The changes in those files will also be takes into account immediately after they have been saved if the macro edited by the user was available when the Tomcat server was being started up.

Opis plików konfiguracyjnych aplikacji czytelnika systemu dLibra 6.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 (tylko dla wdrożeń, które mają dedykowane rozwiązania w tym zakresie) :
    • 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.
  • pola metadanych, po których użytkownik ma mieć możliwośc sortowania wyników wyszukiwania.

• components.xml - Dodatkowe parametry konfiguracyjne dla poszczególnych komponentów. W tym pliku zmieniamy:
  • Identyfikator kolekcji oraz "Polecane".
  • Dla komponentu indeksów listę tokenów, które jako prefiksy wartości indeksów nie będą uwzględniane w sortowaniu.
  • Maksymalną długość zapytania wyszukiwawczego.
  • Możliwość wyświetlania formularza z zapytaniem o dostęp do publikacji chronionej.
  • Możliwość filtrowania po kolekcjach, publikacjach grupowych oraz dostępności w wynikach wyszukiwania.
  • Nazwy atrybutów, po których nie ma być możliwości przeszukiwania.
  • Liczbę elementów wyświetlanych na stronie głównej dla: polecanych, ostatnio dodanych i najpopularniejszych publikacji oraz wiadomości.
  • Identyfikatory kolekcji, których nie chcemy wyświetlać w strukturze kolekcji oraz to czy struktura kolekcji ma być pełnym drzewem.
    

  • Nazwy atrybutów, które chcemy wyświetlać w komponencie indeksów.

  • Adres email osoby odpowiedzialnej za administrację repozytorium OAI.

  • Podstawowe atrybuty w widoku informacji o obiekcie cyfrowym, możliwość wyświetlania identyfikatora OAI

• 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.

• 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. Konfigurujemy w nim:
  • czas wykonywania kopii zapasowej JCR, ścieżkę w której ma być przechowywana kopia zapasowa JCR oraz liczbę przechowywanych uprzednio stworzonych kopii,
  • mechanizmu importu wiadomości z zewnętrznego kanału RSS,
  • czas generowania i zapisu a także generowania widoków prezentacyjnych statystyk, identyfikatory atrybutów na podstawie których generowane są statystyki wartości atrybutów
    
  • czas wysyłania biuletynów z ostatnio dodanymi publikacjami,
  • położenie katalogu do którego zapisywane są informacje o zapytaniach wyszukiwawczych wydawanych przez użytkowników aplikacji czytelnika,
  • czas i mechanizm tworzenia mapy strony.

• 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 dla komponentów. Informacje o tworzeniu makr jęzka VTL można znaleźć na stronach projektu Velocity.
• dlibra-webapp\WEB-INF\layout\custom_templates\custom_layout_library.vm - Zawiera dodatkowe makra języka VTL stworzone przez administratorów danej biblioteki dla szablonów rozmieszczeń. 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ń.
• 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. Dotyczy dedykowanych wdrożeń z włączoną funkcją Self-Archiving.
• 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. Dotyczy dedykowanych wdrożeń z włączoną funkcją Self-Archiving.

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.

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.