05. Zmiany w konfiguracji Aplikacji Czytelnika

Konfiguracja aplikacji czytelnika

W niniejszym rozdziale znajdują się instrukcje związane z konfiguracją niektórych mechanizmów związanych z działaniem aplikacji czytelnika.

Opis konfiguracji rozproszonej platformy uwierzytelniania

Począwszy od dLibry 4.0 dostępna jest funkcjonalność rozproszonej platformy uwierzytelniania oraz sieciowy profil uzytkownika. Domyślnie mechanizmy te są wyłączone poniżej znajduję się szczegółowa instrukcja postępowania pozwalająca na uruchomienie tej funkcjonalności. Najważniejsze pojęcia związane z ideą rozproszonej platformy uwierzytelniania oraz sieciowym profilem użytkownika nie są przedmiotem tego podręcznika

Uruchomienie rozproszonego uwierzytelniania

Aby móc uaktywnić logowanie poprzez rozproszoną platformę uwierzytelniania należy upewnić się że plik templates.properties zawiera library.id, korzystanie z rozproszonej platformy będzie możliwe tylko wtedy gdy library.id z templates.properties zostanie dodane do serwisu WAYF. Jeżeli nie wiadomo czy identyfikator został wprowadzony do rejestru WAYF należy skontaktować się z pomocą techniczną aplikacji czytelnika.

1. Należy wyłączyć serwer aplikacji w ramach którego uruchomiona jest aplikacja czytelnika.
2. Wykonać kopie zapasową katalogów : dlibra-webapp/WEB-INF/guanxi-idp, dlibra-webapp/WEB-INF/guanxi-engine, dlibra-webapp/WEB-INF/guanxi-guard
3. W pliku dlibra-webapp/WEB-INF/periodic.xml odkomentować znajdujące się na koncu definicje zadań okresowych:

<periodic-task logicClass="pl.psnc.dlibra.web.guanxi.engine.periodic.IdpMetadataDownloaderTask"
       executeOnStart="no">
  <description></description>
  <expression>0 0/5 * * * ?</expression>
</periodic-task>
<periodic-task logicClass="pl.psnc.dlibra.web.guanxi.engine.periodic.MetadataLoaderTask"
       executeOnStart="no">
  <description></description>
  <expression>15 0/5 * * * ?</expression>
</periodic-task>
<periodic-task logicClass="pl.psnc.dlibra.web.guanxi.idp.periodic.IdPConfigurationReloadingTask"
       executeOnStart="no">
  <description></description>
  <expression>30 0/5 * * * ?</expression>
</periodic-task>
<periodic-task logicClass="pl.psnc.dlibra.web.guanxi.idp.periodic.SPListDownloadingTask"
       executeOnStart="no">
  <description></description>
  <expression>45 0/5 * * * ?</expression>
</periodic-task>
<periodic-task logicClass="pl.psnc.dlibra.web.guanxi.sec.TruststoreDownloadingTask"
       executeOnStart="no">
  <description></description>
  <expression>60 0/5 * * * ?</expression>
</periodic-task>
<periodic-task logicClass="pl.psnc.dlibra.web.guanxi.idp.register.IdentityConfigurator"
       executeOnStart="no">
  <description></description>
  <expression>0 0 0 29 2 ?</expression>
</periodic-task>

4. W pliku dlibra-webapp/WEB-INF/conf/resources-managers.xml należy odkomentować sekcje znajdującą się na końcu pliku chodzi o deskryptor o identyfikatorze: guanxi.

<pl.psnc.dlibra.web.fw.resources.ResourceInfo>
  <id>guanxi</id>
  <depends>dlibra</depends>
  <data>guanxi.properties</data>
</pl.psnc.dlibra.web.fw.resources.ResourceInfo>

4a. W pliku dlibra-webapp/WEB-INF/conf/user-providers.xml odkomentować sekcje:

  <!--
  <pl.psnc.dlibra.web.guanxi.resources.GxUserInformationProvider>
    <loginPage>${homepage}gx?url=${homepage}&amp;action=RewritePodAction</loginPage>
    <logoutPage>${homepage}gxlogout?action=GuardLogoutAction</logoutPage>
    <loginPagePosition>3</loginPagePosition>
    <methodNameResourceKey>uip.gx.name</methodNameResourceKey>
  </pl.psnc.dlibra.web.guanxi.resources.GxUserInformationProvider>
  -->

Wpisy w pliku user-providers.xml opisują dostępne dla użytkowników sposoby logowania. Znacznik <loginPagePosition> określa pozycje na której dany dostawca tożsamości znajduję się na stronie z wyborem sposobu logowania. Jeżeli jest zdefiniowany tylko jeden dostawca tożsamości dLibra automatycznie przekieruje użytkownika na stronę z formularzem logowania. Jeżeli nie chcą Państwo aby dany dostawca tożsamości był wyświetlany na liście z wyborem sposobu logowania należy dla danego dostawcy usunąć zawartość znacznika <loginPage>.

Rozważmy następujący przykład, w aplikacji czytelnika zdefiniowane są dwa sposoby logowania:

• logowanie na konta lokalne - umożliwiające dostęp do panelu administracyjnego,
• sieciowego profilu użytkownika - umożliwiające dostęp do sieciowego profilu użytkownika.

Chcemy aby zwykli użytkownicy używali tylko profilu sieciowego, aby tego dokonać należy usunąć zawartość znacznika loginPage w sekcji konfigurującej DlibraUserInformationProvider. W tym momencie jedynym dostawcą strony logowania będzie GxUserInformationProvider i użytkownicy zostaną automatycznie przekierowani na stronę usługi WAYF. Administrator chcący się zalogować do panelu administracyjnego będzie musiał wpisać adres strony logowania bezpośrednio do przeglądarki np. http://www.dlibra.psnc.pl/biblioteka/dlibra/login a następnie ze strony z opisem konta przejść do panelu administracyjnego.

Jeżeli chcą Państwo zmienić sposób w jaki dany dostawca tożsamości jest nazywany należy w nadpisać (w LoginSelectionComponent_xx.xml) wartość etykiety tekstowej, której nazwa znajduje się w methodNameResourceKey.

5. W pliku dlibra-webapp/WEB-INF/web.xml należy odkomentować fragment na końcu pliku zawierające

<!--
   &guanxi_idp;
   &protectedapp;
   &samlengine;

 <servlet>
   <servlet-name>tasksServlet</servlet-name>
   <servlet-class>
      pl.psnc.dlibra.web.guanxi.resources.StartupTasksServlet
   </servlet-class>
   <load-on-startup>11</load-on-startup>
 </servlet>
 -->

Końcowe kroki

6. Uruchomić serwer aplikacji w ramach którego działa aplikacja czytelnika.

Po uruchomieniu aplikacji czytelnika po kliknięciu w odnośnik "Logowanie" powinno pojawić się okno dialogowe z wyborem sposobu logowania. Jeżeli próba logowania za pomocą systemu jednokrotnego logowania zakończy się powodzeniem oznacza, że mechanizm został poprawnie skonfigurowany i uruchomiony.

Podczas pierwszego uruchomienia usługi rozproszonego logowania inicjalizowane są pliki konfiguracyjne znajdujące się w katalogach guanxi-engine, guanxi-guard, guanxi-guard. W sytuacji gdy pierwsze uruchomienie zakończy się niepowodzeniem można przywrócić pierwotną zawartość katalagów i spróbować ponownie.

Konfiguracja usługi CAS

dLibra umożliwia wykorzystanie centralnego systemu logowania stworzonego za pomocą serwera CAS i usługi katalogowej LDAP. CAS jest dostępny jako kolejny dostawca tożsamości w pliku dlibra-webapp/WEB-INF/conf/user-providers.xml. Należy odkomentować fragment poniższy fragment:

 <pl.psnc.dlibra.web.comp.user.CasUserInformationProvider>
    <loginPage>http://dlibra.psnc.pl/cas/login?service=${prevpage}</loginPage>
    <logoutPage>${homepage}main?action=LogoutAction</logoutPage>
    <loginPagePosition>2</loginPagePosition>
    <methodNameResourceKey>uip.cas.name</methodNameResourceKey>
    <ldapConfiguration>WEB-INF/conf/ldap.properties</ldapConfiguration>
    <userAttributesDefaults>
      <property name="givenName" value="dLibra"/>
      <property name="cn" value=""/>
      <property name="mail" value=""/>
    </userAttributesDefaults>
    <emailAttributeName>mail</emailAttributeName>
  </pl.psnc.dlibra.web.comp.user.CasUserInformationProvider>

Następnie należy:

• zmienić zawartość znacznika loginPage tak aby wskazywał na stronę logowania wykorzystywanego serwera CAS.
• W znaczniku userAttributesDefaults wpisać nazwy atrybutów, które mają być wykorzystywane przy tworzeniu dynamicznych grup właściwości w aplikacji Zarządacy systemu dLibra. Wartość atrybutu value każdego znacznika property określa wartość domyślną dla danego atrybutu.
• Jeżeli w wykorzystywanym rejestrze LDAP każdy użytkownik posiada adres email wyspecyfikowany jako wartość konkretnego atrybutu, nazwę tego atrybutu można wpisać w znacznik emailAttributeName. Wówczas dLibra będzie w stanie wykorzystać informacje o adresie email użytkowników.
• Jeżeli chcą Państwo zmienić sposób w jaki dany dostawca tożsamości jest nazywany należy w nadpisać (w WEBAPP_xx.xml) wartość etykiety tekstowej, której nazwa znajduje się w methodNameResourceKey.

Następnie należy uzupełnić zawartość plik dlibra-webapp/WEB-INF/conf/ldap.properties - zawiera on parametry umożliwiające wykorzystanie usługi katalogowej LDAP.

Konfiguracja importu wiadomości

Aplikacja czytelnika pozwala na publikowanie na stronie głównej różnego rodzaju wiadomości. Wiadomości te można dodawać za pośrednictwem panelu administracyjnego aplikacji czytelnika bądź wykorzystując mechanizm importu wiadomości z kanału RSS. Poniżej omówiona został sposób w jaki import taki można przeprowadzić.

Aby zaimportować wiadomości z dostępnego w sieci kanału RSS należy w pliku periodic.xml odkomentować znacznik periodic-task zawierający konfigurację klasy
NewsImportTask.

<periodic-task logicClass="pl.psnc.dlibra.web.comp.periodic.NewsImportTask"
	 executeOnStart="yes">
 <description>Checks feed url given in configuration, and imports news from that feed.</description>
 ....
</periodic-task>

Konfiguracja tego zadania składa się z następujących parametrów:

• feed.url - adres kanału RSS/Atom zawierającego importowane wiadomości.
• add.post.link.to.blog - jeżeli wartość tego parametru zostanie ustawiona na true do każdej wiadomości zostanie dodany odnośnik do strony na której wiadomość była pierwotnie publikowana.
• full - który element wpisu w kanale RSS ma zostać użyty jako pełny tekst wiadomości. W przypadku kanałów RSS przeważnie będzie to element description, jednak dla kanałów w formacie Atom oprócz istnieją dwa znaczniki zawierające treść wpisu: content i sumarry. Dopuszczalne wartości to : feed_description, feed_content.
• short - który element kanału ma zostać zaimportowany jako skrót wiadomości. Dopuszczalne wartości to : feed_description, feed_content.
• publish.in.all.languages - jeżeli parametr ten będzie miał wartość true wiadomość zostanie zaimportowana we wszystkich zainstalowanych w aplikacji czytelnika językach interfejsu.
• blog.language - język w jakim napisane są importowane wiadomości.
• start.date - zostaną zaimportowane tylko wpisy opublikowane po wpisanej tu dacie (data w formacie dd.MM.YYYY)

Zadanie to jest domyślnie wykonywane raz na dobe. Gdy tylko aplikacja czytelnika wykryje, że w kanale RSS pojawiła się nowa wiadomość zaimportuje przy najbliższym wykonaniu tego zadania.

Dodawanie exlibrisów

Exlibrisy w aplikacji czytelnika systemu dLibra reprezentowane są jako obrazki z odnośnikiem do wybranej strony (biblioteki, instytucji itp.), które pojawiają się na stronie opisu publikacji (publication, docmetadata). Exlibrisy są dodawane wg wartości konkretnych atrybutów umieszczonych w metadanych. Np. exlibris może zostać wyświetlony w zależności od wartości atrybutu Prawa - dla wartości "Instytucja Biblioteczna X" będzie wyświetlony obrazek identyfikujący daną instytucję oraz odnośnik do strony głównej tej instytucji "www.instytucjabibliotecznax.com".

Procedura dołączania exlibrisu wygląda następująco:

1. W katalogu 5.0/exlibris należy umieścić plik graficzny z ekslibrisem biblioteki

2. Następnie w pliku 5.0/WEB-INF/conf/exlibris.xml znajdują się następujące wpisy:

   <exlibrises>
    <attribute rdfname="Rights">
     <attribute-value value="Biblioteka Uniwersytecka w Poznaniu">
      <exlibris>
       <img>bu-poznan.png</img>
       <link>http://lib.amu.edu.pl/</link>
      </exlibris>
     </attribute-value>
    </attribute>
   </exlibrises>
   

• Poprzez element XML attribute i wartość rdfname (nazwa RDF) wskazywany jest atrybut metadanych publikacji, którego wartość będzie reprezentowała exlibris; elementów "attribute" może być wiele.
• Następnie w ramach elementu attribute definiuje się elementy attribute-value, które reprezentują wartości atrybutu metadanych publikacji identyfikujące exlibrisy. Te konkretne wartości wprowadza się w polu XML value elementu attribute-value. W podanym wyżej przykładzie domyślnej konfiguracji wartością atrybutu jest "Biblioteka Uniwersytecka w Poznaniu". Rozpoznanie tej wartości w metadanych publikacji spowoduje wyświetlenie odpowiedniego exlibrisa na stronie opisu metadanych publikacji w aplikacji czytelnika (strona docmetadata lub publication). Każdy element attribute-value odpowiada za jedną wartość atrybutu, stąd jeśli chcemy aby exlibris był rozpoznawany za pomocą różnych wariantów nazw, to należy stworzyć osobny element attribute-value dla każdej nazwy.
• Ostatecznie wewnątrz elementu attribute-value określa się elementy exlibris. Element exlibris posiada dwa podrzędne elementy img oraz link, z których pierwszy jest nazwą pliku graficznego
  (dodanym w kroku pierwszym do folderu /exlibris), drugi zaś wskazuje na odnośnik do strony, na która zostanie przekierowany użytkownik po kliknięciu na obrazek exlibrisu.

Każdy z elementów: attribute, attribute-value i exlibris może być definiowany wielokrotnie, co pozwala na dodanie wielu exlibrisów w ramach każdej określonej wartości atrybutu metadanych.

Przykładowo:

<exlibrises>
 <attribute rdfname="Rights">
  <attribute-value value="Biblioteka Uniwersytecka w Poznaniu">
   <exlibris>
    <img>bu-poznan.png</img>
    <link>http://lib.amu.edu.pl/</link>
   </exlibris>
  </attribute-value>
  <attribute-value value="BUP">
   <exlibris>
    <img>bu-poznan.png</img>
    <link>http://lib.amu.edu.pl/</link>
   </exlibris>
  </attribute-value>
  <attribute-value value="Uniwersytet im. A.Mickiewicza i Politechnika Poznańska">
   <exlibris>
    <img>uam.png</img>
    <link>http://uam.edu.pl/</link>
   </exlibris>
   <exlibris>
    <img>put.png</img>
    <link>http://www.put.poznan.pl/</link>
   </exlibris>
  </attribute-value>
 </attribute>
</exlibrises>

W przypadku takiej konfiguracji, dla atrybutu Praw, exlibris Biblioteki Uniwersyteckiej w Poznaniu pojawi się zarówno, gdy w atrybucie podana będzie wartość "Biblioteka Uniwersytecka w Poznaniu" jak i "BUP". Dodatkowo jeśli w tym samym atrybucie Praw pojawi się wartość "Uniwersytet im. A. Mickiewicza i Politechnika Poznańska", wówczas wyświetlą się dwa exlibrisy (dwa obrazki z odnośnikami) odpowiednio dla UAM i PP.

Konfiguracja exlibris.xml zacznie działać dopiero po restarcie środowiska serwletów aplikacji czytelnika (Apache Tomcat). Nieprawidłowe ustawienia mogą w efekcie prowadzić do wyświetlania wyjątków i błędów w logach systemu.

Konfiguracja systemu kopii zapasowych JCR

Aby zmienić domyślne ustawienia systemu tworzenia kopii zapasowych JCR należy wyedytować plik periodic.xml znajdujący się w katalogu /WEB-INF Aplikacji Czytelnika. Wpis dotyczący odpowiedniego zadania okresowego przedstawia się następująco:

<periodic-task logicClass="pl.psnc.dlibra.web.comp.periodic.JCRBackupTask" executeOnStart="yes">
		<expression>0 0 23 * * ?</expression>
		<properties>
			<property>
				<name>jcr.backup.dir</name>
				<value>[backup directory path]</value>
				<description>Path to JCR backup destination directory. Path should end with '/'.</description>
			</property>
			<property>
				<name>copies.amount</name>
				<value>[amount of copies]</value>
				<description>Specifies how many different copies of backup can be stored at once</description>
			</property>
		</properties>
		<description>Task is responsible for backup of JCR stored data</description>
</periodic-task>

W zadaniu można zmienić dwa parametry: jcr.backup.dir oraz copies.amount.
Pierwszym parametrem administrator wskazuje katalog, do którego mają być umieszczane pliki kopii zapasowych. Każda pojedyncza kopia zapasowa to plik w formacie .xml, o nazwie jcr-backup_[data utworzenia kopii].xml, np. jcr-backup_2010.12.25.08.00.00.xml.

Drugi parametr określa maksymalną liczbę kopii zapasowych. Zadanie okresowe wykonuje się cyklicznie, domyślnie co 24 godz., i stąd po utworzeniu przez nie maksymalnej ilości plików kopii, każdy kolejno utworzony nadpisuje najstarszy plik kopii z katalogu jcr.backup.dir.

Możliwe wartości parametru copies.amount:

• dla parametru > 0, zadanie tworzy określoną liczbę plików kopii zapasowych;
• dla parametru = 0, zadanie nie tworzy żadnych plików kopii zapasowych;
• dla parametru < 0, zadanie tworzy nielimitowaną liczbę plików kopii zapasowych.

Zmiana parametrów w zadaniach okresowych wymaga restartu kontenera (np. Apache Tomcat) Aplikacji Czytelnika.

Odzyskiwanie danych z kopii zapasowych JCR

Aby odzyskać dane z utworzonego pliku .xml kopii zapasowej należy umieścić go w odpowiednim katalogu. Katalog ten jest konfigurowany w pliku /WEB-INF/conf/jcr.properties Aplikacji Czytelnika pod parametrem jcr.restore.dir.
Kopia zapasowa jest automatycznie odzyskiwana podczas ponownego uruchomienia kontenera (np. Apache Tomcat) Aplikacji Czytelnika.
Uwaga! Plik kopii zapasowej, po odzyskaniu z niego danych, jest automatycznie usuwany.

Konfiguracja miniatur

Za konfigurację miniatur wyświetlanych w Aplikacji Czytelnika odpowiedzialny jest parametr (context-param) z pliku
/WEB-INF/web.xml Aplikacji Czytelnika, który przedstawia się następująco:

<context-param>
		<description>
			...
		</description>
		<param-name>thumbnails.settings</param-name>
		<param-value>200;200;1.0;false;image/png</param-value>
</context-param>

Wartości parametru wstawia się między znacznikami <param-value></param-value>. Parametr jest czteroczęściowy i poszczególne jego części oddzielone są od siebie znakiem ';'. W przedstawionym wyżej przykładzie wartości poszczególnych części wynoszą: 200, 200, 1.0, false oraz image/png.
Każda część oznacza kolejno:

• szerokość wynikowego pliku graficznego (w przykładzie równa 200);
• wysokość wynikowego pliku graficznego (w przykładzie równa 200);
• stopień kompresji wynikowe pliku graficznego (w przykładzie równa 1.0);
• czy wejściowy plik graficzny ma być obcięty proporcjonalnie do wymiarów (w przykładzie równa 'false');
• format wynikowego pliku graficznego (w przykładzie jest to 'image/png');

Pierwsze dwie wartości określają jakie wymiary będzie miał wyjściowy plik graficzny miniatury dla Aplikacji Czytelnika, bez względu na wymiary pierwotnego pliku graficznego - wprowadzonego w Aplikacji Redaktora. Jeśli więc przykładowo plik graficzny w Aplikacji Redaktora został wprowadzony w wymiarach szerokość = 500 pikseli i wysokość = 200 pikseli, to w Aplikacji Czytelnika będzie on odpowiednio przeskalowany do wymiarów skonfigurowanych w parametrze thumbnails.settings. Może to być przydatne w przypadku, gdy wprowadzane przez redaktorów pliki miniatur są dużej szczegółowości, niepotrzebnej przy wyświetlaniu w Aplikacji Czytelnika; zmniejszenie ich wymiarów zmniejsza zarazem ilość pamięci potrzebnej do ich przesyłu, co może dodatnio wpłynąć na szybkość transferu danych.

Kolejny parametr jest powiązany z ostatnim i jest brany pod uwagę jedynie w przypadku, gdy miniatura ma ustawiony format wyjściowego pliku graficznego na 'image/jpeg'. Dzięki temu dodatkowo można zmniejszyć przesyłany plik stosując zalety kompresji stratnej formatu JPEG. Sensowną kompresje ustala się za pomocą liczby zmiennopozycyjnej w przedziale (0,1),
np. 0.1, 0.25, 0.3 itd.

Następny parametr określa sposób w jaki pierwotny obraz graficzny ma być dostosowany do wymiarów miniatury wprowadzonych w parametrze thumbnails.settings. Ustawienie flagi na 'true' spowoduje, że pierwotny plik graficzny zostanie proporcjonalnie zmniejszony i następnie obcięty do obszaru zdefiniowanego przez pierwsze dwa parametry. Ustawienie flagi na 'false' (domyślne) spowoduje, że pierwotny plik graficzny zostanie wpisany w obszar zdefiniowany przez parametry miniatury thumbnails.settings.

Ostatni z parametrów określa typ wynikowego formatu graficznego miniatury. Wspierane są dwa najpopularniejsze formaty: JPEG oraz PNG. W przypadku wybrania formatu JPEG znaczenie ma również parametr stopnia kompresji (opisany wyżej). Poszczególne formaty identyfikowane są przez typy MIME, tj. dla PNG - 'image/png' oraz dla JPEG - 'image/jpeg'.

Zmiana parametrów wyświetlanej miniatury wymaga restartu kontenera (np. Apache Tomcat) Aplikacji Czytelnika.

Konfiguracja komponentu "Polecane"

Podstawowa konfiguracja komponentu "Polecane" znajduje się w pliku /WEB-INF/components.xml Aplikacji Czytelnika.

Przykładowy wpis konfiguracyjny komponentu przedstawia się następująco:

<component name="pl.psnc.dlibra.web.comp.pages.components.RecommendedComponent">
		<properties>
			<property>
				<name>RecommendedId</name>
				<value>&recommendedId;</value>
			</property>
			<property>
				<name>RecommendedCount</name>
				<value>4</value>
			</property>
		</properties>
</component>

Konfiguracja posiada dwa podstawowe parametry:

• RecommendedId - parametr wskazujący ID kolekcji zawierającej publikacje polecane;
• RecommendedCount - parametr wskazujący ile publikacji ma być wylosowanych do wyświetlenia w komponencie.

Pierwszy parametr w swoich domyślnych wartościach wstrzykuje wartość encji recommendedId, która jest deklarowana
na początku dokumentu w linii:

<!ENTITY recommendedId "3">

Domyślnie wartością encji jest '3', która wskazuje na ID automatycznie utworzonej, przy instalacji, kolekcji.
Ze wskazanej tak kolekcji losowane są publikacje, które mają być wyświetlone w komponencie, przy czym wyświetlane są wyłącznie te, które posiadają przypisaną miniaturę. W przypadku braku w kolekcji jakichkolwiek publikacji spełniających to założenie, komponent się nie wyświetli.

Zarówno wartość przypisana encji jak i wartości parametrów mogą zostać zmienione, tak aby wskazywać na kolekcje wybrane przez administratora.

Kolejny parametr RecommendedCount odpowiada za liczbę publikacji, które mają być wylosowane i prezentowane w komponencie. Jeśli komponent nie odnajdzie we wskazanej kolekcji odpowiedniej liczby publikacji z miniaturami, wyświetli te, które udało mu się odnaleźć.

Innym parametrem, nie wskazanym w domyślnej konfiguracji, jest parametr considerHttpRequestId, który pobiera ID kolekcji z żądania HTTP. Parametr umożliwia umieszczenie komponentu na stronie z opisem kolekcji, gdzie publikacje są losowo wybierane z odwiedzanej kolekcji. Parametr przyjmuje wartość typu boolean: true|false. Jeśli parametr jest zdefiniowany nadpisuje on parametr RecommendedId; gdy parametr jest zdefiniowany i w żądaniu HTTP nie pojawia się ID kolekcji, wówczas komponent losuje publikacje z kolekcji głównej.

Dodanie komponentu na stronę

Kolejnym krokiem konfiguracji komponentu jest dodanie go na wybraną stronę. Strony definiuje się w pliku konfiguracyjnym /WEB-INF/pages.xml Aplikacji Czytelnika. Aby dodać komponent na stronę główną, należy w dokumencie pages.xml znaleźć deklarację strony (znacznik <page>) o nazwie main.
W deklaracji tej, między znacznikami <components></components> należy umieścić wpis (domyślnie powinien on już być obecny w komentarzu w pliku):

<component name="pl.psnc.dlibra.web.comp.pages.components.RecommendedComponent">
	       <place>left</place>
     	       <position>8</position>
</component>

Wprowadzanie zmian i konfiguracja zarówno w obszarze pliku components.xml jak i pages.xml nie wymaga zrestartowania kontenera Aplikacji Czytelnika.

Konfiguracja podpowiedzi z opisem publikacji

W wersji 5.0 Aplikacji Czytelnika w komponentach "Ostatnio dodane" oraz "Najczęściej czytane" długie tytuły publikacji są skracane, zaś po najechaniu na nie myszką pojawia się dodatkowa ramka prezentująca wybrane atrybuty wskazanej publikacji.
Istnieje możliwość skonfigurowania przez administratora atrybutów publikacji, które mają się pojawiać w ramce.
Odpowiedzialnym za konfigurację jest plik /WEB-INF/tooltip.xml.
Domyślnie treść pliku prezentuje się następująco:

<?xml version="1.0" encoding="UTF-8"?>
<property>
	<name>attributes</name>
	<value>Title,Creator,Date,Type</value>
</property>

Między znacznikami <value></value> znajdują się nazwy RDF atrybutów metadanych (nazwy te można podejrzeć m.in. w Aplikacji Administratora); kolejność wpisanych atrybutów ma znaczenie - atrybut Title (tytuł) będzie się znajdywał na samej górze w ramce, pod nim Creator (twórca) itd.

Aby zmiany były widoczne konieczne może być ponowne uruchomienie kontenera (np. Apache Tomcat) Aplikacji Czytelnika

Integracja z serwisem społecznościowym Facebook

W wersji 5.0 pojawiły się dwa komponenty integrujące Aplikację Czytelnika z serwisem społecznościowym Facebook.
Pierwszym komponentem jest LikeBoxComponent, którego szkielet konfiguracji w pliku /WEB-INF/components.xml przedstawia się następująco:

<component name="pl.psnc.dlibra.web.comp.pages.components.LikeBoxComponent">
		<properties>
			<property>
				<name>facebookPageUrl</name>
				<value>YOUR_PAGE_URL</value>
			</property>
		</properties>
</component>

Podstawowym atrybutem jest facebookPageUrl, w którym administrator wskazuje stronę danej instytucji/biblioteki cyfrowej utworzonej w ramach konta Facebook.

Kolejne atrybuty mapują interfejs API Facebook dla komponentu i są to:

• width - odpowiednik atrybutu "width" API Facebook;
• height - odpowiednik atrybutu "height" API Facebook;
• showStream - odpowiednik atrybutu "stream" API Facebook;
• showHeader - odpowiednik atrubutu "header" API Facebook;

Dokładne znaczenie komponentu oraz jego atrybutów można sprawdzić na stronie dokumentacji komponentu Facebook.

Drugim komponentem integrującym z Facebook jest LikeButtonComponent, który pozwala zalogowanym na Facebooka użytkownikom dodawać odwiedzaną stronę biblioteki cyfrowej do swoich ulubionych. Do prawidłowego funkcjonowania komponent nie wymaga konfiguracji, posiada jednakże zestaw dodatkowych atrybutów:

• url - jeśli ustawiony, wówczas do ulubionych dodawany jest dowolny wskazany w parametrze adres URL;
• width - szerokość komponentu;
• height - wysokość komponentu.

Dodawanie komponentów na stronę

Aby ostatecznie móc wykorzystać komponenty w swojej Aplikacji Czytelnika potrzebne jest jeszcze skonfigurowanie ich na stronach w pliku /WEB-INF/pages.xml.
Przykładowo, aby dodać komponenty na stronę główną należy w pliku pages.xml odnaleźć deklarację <page name="main"...>
i w niej między znacznikami <components></components> wstawić następujące wpisy:

1)Dla komponentu LikeBoxComponent:

<component name="pl.psnc.dlibra.web.comp.pages.components.LikeBoxComponent">
	           <place>rightbottom</place>
     	           <position>3</position>
</component>

2)Dla komponentu LikeButtonComponent:

<component name="pl.psnc.dlibra.web.comp.pages.components.LikeButtonComponent">
	           <place>left</place>
     	           <position>9</position>
</component>

Wprowadzanie zmian w konfiguracji components.xml oraz pages.xml nie powinno wymagać ponownego uruchomienia kontenera Aplikacji Czytelnika.

Konfiguracja funkcjonalności Self-Archiving

Niniejsza sekcja przedstawia konfigurację mechanizmu Self-Archiving w Aplikacji Czytelnika.

pubcreator.properties

Pierwszym plikiem konfiguracyjnym jest /WEB-INF/conf/pubcreator.properties, w którym zawarte są następujące parametry:

• class.name
• max.file.size
• upload.temp.dir
• main.files.suggesters.use
• main.files.suggesters
• default.main.files.lookup.filter.regexp(x)

Parametry class.name oraz main.files.suggesters nie podlegają zmianom.

Parametr max.file.size umożliwia administratorom wprowadzenie limitów na wielkość pliku treści tworzonych publikacji. Wielkość pliku podaje się w bajtach. Wartość 0 w tym wypadku oznacza brak limitu na wielkość.

Istotnym parametrem jest upload.temp.dir, w którym administrator ustala ścieżkę do katalogu plików tymczasowych. W katalogu tym przechowywane są pliki z treścią publikacji do momentu przesłania ich do serwera. Po zakończeniu procesu tworzenia publikacji, pliki te są automatycznie usuwane z katalogu. Jeśli użytkownik w ramach swojej sesji nie dokończy procesu tworzenia publikacji, wówczas pliki tymczasowe, przesłane przez niego do Aplikacji Czytelnika, usunie zadanie okresowe. Ustawienie tego parametru jest istotne do prawidłowego działania mechanizmu Self-Archiving.

Reszta parametrów, tj. main.files.suggesters.use, main.files.suggesters oraz default.main.files.lookup.filter.regexp(x) służy do konfiguracji opcji podpowiadania pliku głównego treści. W obecnej wersji dLibry opracowany został mechanizm podpowiadania działający w oparciu o nazwę plików. Parametry default.main.files.lookup.filter.regexp(x), gdzie x stanowią kolejne liczby ze zbioru N={0,1,...n}, określają wyrażenia regularne rozpoznające potencjalne pliki główne treści publikacji.

Konfiguracja formularza atrybutów - pubc-metadata.xml

Plik /WEB-INF/conf/pubc-metadata.xml służy do konfiguracji formularza atrybutów, który pojawia się w 2-gim kroku kreatora publikacji. W pliku tym określa się m.in. liczbę, rodzaj oraz kolejność wyświetlania atrybutów metadanych.

W podstawowej formie plik przedstawia się następująco:

<pubc-metadata>
	<attribute name="title" required="true" pname="true">
		<position>1</position>
		<rdf-name>Title</rdf-name>
	</attribute>
	<attribute name="author" required="true">
		<position>2</position>
		<rdf-name>Creator</rdf-name>
	</attribute>
	<attribute name="abstract">
		<position>3</position>
		<rdf-name>Abstract</rdf-name>
	</attribute>
	<attribute name="subject">
		<position>4</position>
		<rdf-name>Subject</rdf-name>
	</attribute>
	<attribute name="date" required="true">
		<position>5</position>
		<rdf-name>Date</rdf-name>
		<input-type name="DATE">
		</input-type>
	</attribute>
	<attribute name="licence" alias="true">
		<position>6</position>
		<rdf-name>Rights</rdf-name>
	</attribute>
	<attribute name="comments" alias="true">
		<position>7</position>
		<rdf-name>Description</rdf-name>
		<multiple>false</multiple>
		<input-type name="TEXTAREA"/>
	</attribute>
</pubc-metadata>

Głównym elementem struktury XML jest pubc-metadata, który zawiera elementy attribute reprezentujące pola w formularzu.

Każdy element attribute posiada własny zestaw elementów oraz atrybutów.

Atrybuty elementu attribute :

• name - nazwa pola w formularzu, musi być unikalna;
• required - czy pole jest wymagane;
• pname - czy pole spełnia funkcję nazwy publikacji;
• alias - czy pole jest aliasem dla atrybutu.

Elementy podrzędne elementu attribute:

• rdf-name - nazwa RDF atrybutu, na którego wartości mapowane są wartości pola;
• position - pozycja pola na wyświetlanej liście;
• multiple - czy pole może mieć przypisanych wiele wartości (domyślnie 'true');
• input-type - typ pola w formularzu.

Atrybut nazwy name elementu attribute musi być unikalny dla każdego zdefiniowanego pola. Administrator może go wykorzystać w korelacji z atrybutem alias ustawionym na 'true', domyślnie bowiem nazwa dla pola jest pobierana bezpośrednio od nazwy atrybutu metadanych dLibra, wskazanego elementem rdf-name (patrz wyżej), w tym wypadku można jednakże ustawić własną nazwę dla pola w plikach etykiet komponentu PublicationUploadComponent. Etykieta taka rozpoczyna się od prefiksu "PublicationUploadComponent" a kończy nazwą określoną w atrybucie name, np. "PublicationUploadComponent.title".
Więcej na temat etykiet można przeczytać tutaj.

Atrybut required określa czy wypełnienie pola jest wymagane do zaakceptowania tworzonej publikacji.
W sytuacji, gdy użytkownik nie wprowadzi w to pole żadnej wartości wyświetlony zostanie w kreatorze odpowiedni komunikat.
Atrybut pname określa czy dane brane z pola będą spełniały rolę nazwy dla publikacji; pole tak oznaczone tym atrybutem powinno być jednocześnie polem wymaganym. Jeśli nie istnieje żadne pole z atrybutem pname ustawionym na 'true', wówczas w trakcie tworzenia publikacji jego nazwa zostanie wzięta z pierwszego w kolejności pola wymaganego.

Pierwszym istotnym elementem podrzędnym elementu attribute jest rdf-name, który łączy wskazane pole formularza z atrybutem w schemacie metadanych biblioteki cyfrowej. Wszystkie wpisywane w pole wartości są kojarzone z konkretnym atrybutem metadanych poprzez nazwę RDF atrybutu. Przykładowymi nazwami RDF są: Title, Cretor, Abstract itp.

Element podrzędny position określa pozycję pola na liście pól formularza. Dwa dodatkowe podrzędne elementy, tj. multiple oraz input-type nie są wymagane. Pierwszy określa czy do danego pola można dodać wiele wartości (domyślnie 'true'), drugi określa jakiego typu jest pole formularza. Można wybrać spośród trzech typów: TEXT (standardowe pole tekstowe), TEXTAREA (duże pole tekstowe) oraz DATE (pole wyboru daty), które wpisuje się w atrybucie name elementu. Domyślnie dla każdego pola wybierany jest element typu TEXT.

Przykładowo:

<input-type name="DATE">
</input-type>

Jeśli zdefiniowane pole jest typu DATE wówczas można między znacznikami <input-type ...></input-type> umieścić podrzędne elementy:

• startYear - najwcześniejszy możliwy rok do wyboru (domyślnie 1945);
• endYear - najpóźniejszy możliwy rok do wyboru (domyślnie rok aktualny);
• separator - separator, który pojawia się po między poszczególnymi częściami daty (dniem, miesiącem, rokiem) w wartości atrybutu metadanych stworzonej publikacji.

Przykład konfiguracji pola daty:

<input-type name="DATE">
  <startYear>1990</startYear>
  <endYear>2010</endYear>
  <separator>:</separator>
</input-type>

Ostatnią kwestią wartą zaznaczenia jest obsługa kontrolowanych atrybutów metadanych. Pola, które w nazwie RDF odwołują się do atrybutów kontrolowanych prezentują się jako listy rozwijalne, w których użytkownik może wybrać jedną z proponowanych pozycji. Atrybuty ustawia się jako kontrolowane w Aplikacji Administratora. Więcej na ten temat można znaleźć tutaj.

Konfiguracja regulaminu

Przed przystąpieniem do dodawania publikacji każdy użytkownik jest zobowiązany do zaakceptowania regulaminu, którego treść można zmienić na potrzeby własnej biblioteki cyfrowej. Treść regulaminu znajduje się na stronie pomocy regulations i może ona zostać zmieniona w panelu administracyjnym Aplikacji Czytelnika.
Istnieje również możliwość całkowitego wyłączenia regulaminu z kreatora publikacji, wystarczy w tym celu do pliku components.xml dodać wpis dotyczący komponentu PublicationUploadComponent:

<component name="pl.psnc.dlibra.web.comp.pages.components.PublicationUploadComponent">
		<properties>
			<property>
				<name>regulationsAcceptRequired</name>
				<value>false</value>
			</property>
		</properties>
</component>

Wprowadzenie zmiany w pliku components.xml nie powinno wymagać restartu kontenera Aplikacji Czytelnika.

Inne etapy konfiguracji

Do prawidłowego działania funkcjonalności Self-Archiving potrzebne są jeszcze ustawienia w serwerze dLibra.
Konfigurację Self-Archiving w serwerze dLibra można sprawdzić tutaj.

Konfiguracja mechanizmu dodawania tagów publicznych

Istnieje możliwość konfigurowania podstawowych parametrów akcji dodawania tagów publicznych. Aby to zrobić należy otworzyć plik /WEB-INF/actions.xml konfiguracji akcji. W pliku tym można odnaleźć wpis:

       <action name="pl.psnc.dlibra.web.comp.pages.actions.AddBookmarkTagAction">
		<properties>
			<property>
				<name>accept.all.tags</name>
				<value>false</value>
			</property>
			<property>
				<name>max.tag.length</name>
				<value>100</value>
			</property>
			<property>
				<name>min.tag.length</name>
				<value>3</value>
			</property>
		</properties>
	</action>

W procesie moderacji tagów publicznych są one przetrzymywane pewien okres czasu, w którym moderator może ustawić ich stan na "zaakceptowany" bądź "niezaakceptowany". Tylko zaakceptowane tagi publiczne są dodawane do atrybutu "Tagi" wybranej publikacji. Parametr accept.all.tags ustala czy przesyłana propozycja tagu publicznego ma być automatycznie ustawiana na stan "zaakceptowany", który może zostać ewentualnie zmieniony przed moderatora. Standardowo parametr accept.all.tags ustawiony jest na false co oznacza, iż dodawane tagi publiczne są domyślnie w stanie "niezaakceptowane".

Dwa kolejne parametry określają minimalną (min.tag.length) oraz maksymalną (max.tag.length) liczbę znaków przeznaczonych na tag publiczny. W przypadku, gdy tag nie spełnia wyznaczonego limitu, nie zostanie on dodany do propozycji słów kluczowych. Ustawienie któregokolwiek z tych parametrów na wartość 0 spowoduje, iż nie będzie on brany pod uwagę przy sprawdzaniu liczby znaków tagu.

Konfiguracja wyświetlania zabezpieczonych plików PDF

Omawiana konfiguracja umożliwia precyzyjniejsze określenie zabezpieczenia w wyświetlanym przez Aplikację Czytelnika dokumencie PDF.
Aby rozpocząć modyfikację parametrów zabezpieczania plików PDF należy wyświetlić do edycji plik settings.xml z katalogu /WEB-INF/formats/pdf.
Plik ten powinien zawierać wpisy:

<properties>
<!--
 In case of any problems with securing PDF files you may try to use alternative format writer based on iText.
-->
<!--
 <entry key="secured.format.writer.class">pl.psnc.dlibra.web.comp.formats.writers.ItextSecuredPdfFormatWriter</entry>
-->
<entry key="secured.format.writer.class">pl.psnc.dlibra.web.comp.formats.writers.SecuredPdfFormatWriter</entry>
<entry key="handler.id">pdf:secured</entry>
<entry key="handled.mime.types">application/pdf</entry>
<entry key="handles.secured">true</entry>
<entry key="handles.normal">false</entry>
<entry key="owner.pass"></entry>
<entry key="user.pass"></entry>
<entry key="print.degraded">true</entry>
<entry key="print">false</entry>
<entry key="modify.annotations">false</entry>
<entry key="fill.in.form">false</entry>
<entry key="extract.for.accessibility">false</entry>
<entry key="assemble.document">false</entry>
<entry key="extract.content">false</entry>
</properties>

Podstawowymi parametrami są owner.pass oraz user.pass, które określają kolejno: hasło właściciela dokumentu PDF oraz hasło użytkownika dokumentu PDF, które będzie zobowiązany wprowadzić, jeśli dokument można w jakiś sposób modyfikować.
Z pozostałych parametrów można wymienić (pomijając ogólne parametry konfiguracji mechanizmu wyświetlania):

• assemble.document - parametr określa czy użytkownik może w zabezpieczonym pliku modyfikować strony, tj. obracać, usuwać i dodawać nowe
• print.degraded - określa czy użytkownik może drukować dokument w zubożonej jakości
• print - określa czy użytkownik może drukować dokument
• modify.annotations - określa czy użytkownik może modyfikować adnotacje w tekście lub wypełniać danymi interaktywne formularze
• fill.in.form - określa czy użytkownik może wypełniać danymi interaktywne formularze.
• extract.for.accessibility - określa czy można pobierać treść w dokumencie na potrzeby dostępności dla osób niewidomych
• extract.content - określa czy użytkownik może zaznaczać i kopiować treść dokumentu
• modify - określa czy użytkownik może modyfikować pobrany dokument

Wszystkie wymienione w liście parametry przyjmują wartości typu boolean (true|false).

Zmiana parametrów wymaga restartu kontenera Aplikacji Czytelnika (tj. Apache Tomcat).

Konfiguracja kolekcji głównej dla Aplikacji Czytelnika

Wersja 5.0 umożliwia administratorom wskazanie dowolnej kolekcji, spośród istniejących w bibliotece cyfrowej, która będzie spełniała rolę kolekcji głównej. Opcja ta idzie w parze z możliwością podłączenia wielu Aplikacji Czytelnika pod pojedynczy Serwer dLibra.
Aby skonfigurować dla danej Aplikacji Czytelnika jej kolekcję główną wystarczy otworzyć do edycji plik /WEB-INF/web.xml, w którym
znajduje się następujący wpis (domyślnie w komentarzu XML):

<context-param>
		<description>
			Configurable main dLibra collection id
		</description>
		<param-name>main.collection.id</param-name>
		<param-value>[id of collection]</param-value>
	</context-param>

Wpis należy "odkomentować" zaś w miejsce [id of collection] należy wrzucić numeryczne ID kolekcji (unikalne ID ustawiane w bazie danych kolekcji). Po wszystkim należy zrestartować środowisko serwletów (np. Tomcat).

Zmiany w formularzu "Kontakt"

Aby zmienić domyślne wartości kontaktowe w formularzu należy otworzyć do edycji pliki WEBAPP_en.xml (dla języka angielskiego) oraz WEBAPP_pl.xml (dla języka polskiego), z katalogu /WEB-INF/components/resources. W plikach tych można znaleźć wpisy w postaci:

<entry key="ContactComponent.Name">Instytucja partnerska BC</entry>
<entry key="ContactComponent.Address">ul. Nieznana 16, 61-895 Poznań, POLSKA</entry>
<entry key="ContactComponent.URL">http://institution.com/</entry>
<entry key="ContactComponent.Mail">mail@institution.com</entry>
<entry key="ContactComponent.Phone">telefon: (+48) 61-333-33-32, faks: (+48) 61-333-33-33</entry>

Łatwo zauważyć, iż poszczególne wartości dla elementów XML odpowiadają wartościom z formularza. Zmiany w tych plikach nie wymagają
ponownego uruchomienia kontenera serwletów.

Inną rzeczą, o której warto pamiętać w kontekście formularza kontaktu, jest adres mail, na który wysyłane są wpisane przez użytkownika wiadomości. Adres ten można skonfigurować w pliku /WEB-INF/actions.xml, zmieniając wartość dla deklarowanej akcji SendMailAction:

	<action name="pl.psnc.dlibra.web.comp.pages.actions.SendMailAction">
		<properties>
		    <property>
		      <name>to.web.mail</name>
		      <value>[adresy mail, na ktory maja byc wysylane zgloszenia]</value>
		    </property>
		    ...
		</properties>
	</action>

Między znacznikami value można umieścić dowolną liczbę adresów mail oddzielonych średnikami lub przecinkami.

Dodatkowa pomoc w formularzu logowania

Istnieje możliwość łatwego udostępnienia czytelnikom dodatkowych informacji z poziomu formularza logowania (np. o prawnych ograniczeniach w sposobie udostępniania treści). Należy w tym celu otworzyć Panel Administracyjny i dodać stronę pomocy o identyfikatorze login-help. Jeśli taka strona istnieje (w zależności od aktualnie wybranego języka strony), na formularzu logowania pojawi się dodatkowy przycisk "Pomoc", który powoduje wyświetlenie treści tej strony pomocy.

Ustawienia obsługi znaków wodnych

Znaki wodne wyświetlane są dla zabezpieczonych prezentacji JPG (specjalny typ publikacji w dLibrze, który tworzy się poprzez wskazanie jako plik główny katalogu zawierającego pliki JPG). Odbywa się to za pomocą specjalnego appletu Java.

Znak wodny to obrazek, który jest nakładany na wyświetlaną treść prezentacji z efektem przezroczystości. Zalecamy wykorzystać grafikę w formacie PNG, który pozwala zapisać obraz z przezroczystym tłem. Obrazek ten jest zawsze powiększany tak, aby zajmował maksymalną powierzchnię. Nie jest jednak rozciągany do proporcji głównego obrazu, tylko wyśrodkowany. Można jednak uzyskać efekt znaku wodnego mniejszego niż główny obraz, poprzez dodanie przezroczystego obramowania o wybranej szerokości w grafice znaku wodnego.

Oprócz obrazka, w znaku wodnym może być automatycznie wstawiona nazwa zalogowanego użytkownika. Konfiguracja znaków wodnych znajduje się w pliku WEB-INF/web.xml, w sekcji poświęconej servletowi watermarkServlet. Można tam zdefiniować następujące parametry:

• image.path - sadaścieżka do obrazka, który ma być wyświetlany jako znak wodny
• opacity - siła efektu przezroczystości, musi być liczbą z przedziału (0, 1). 0 - znak niewidoczny, zupełnie przezroczysty, 1 - znak zupełnie przesłania treść
• text.userName.position - pozycja wskazuje lewy górny róg prostokąta, w którym będzie wpisana nazwa użytkownika. Pozycja jest podawana jako współrzędne w ramach obrazka znaku wodnego, przy czym punkt 0,0 to lewy górny róg obrazka.
• text.userName.size - wielkość prostokąta, w który będzie wpisana nazwa użytkownika, również w stosunku do rozmiaru znaku wodnego. Jeśli wielkość czcionki nie jest zdefiniowana, zostanie automatycznie ustawiona maksymalna wielkość, która pozwoli zmieścić nazwę w tym prostokącie.
• text.userName.align - położenie nazwy użytkownika w ramach zdefiniowanego prostokąta. Możliwe wartości: left (na lewo), center (na środku), right (na prawo).
• text.userName.wordwrap - wartość true/false, pozwala włączyć zawijanie tekstu w przypadku długich nazw użytkownika.
• text.userName.font - czcionka nazwy użytkownika. Dostępne czcionki są zależne od czcionek zainstalowanych na komputerze użytkownika, ale zwykle można wykorzystać czcionki Arial, Courier New, Monospaced, Verdana, Tahoma.
• text.userName.font.style - pozwala włączyć pogrubienie i pochylenie w nazwie użytkownika.
• text.userName.font.color - kolor nazwy użytkownika, w formacie szesnastkowym.
• text.userName.font.size - wielość czcionki. Jeśli nie jest zdefiniowana, zostanie wybrana maksymalna wielkość, przy której zmieści się cała nazwa.

Udostępnianie mapy witryny robotom indeksującym