Migracja aplikacji czytelnika

Przed przystąpieniem do aktualizacji systemu należy zabezpieczyć : istniejącą aplikacje czytelnika, katalog roboczy aplikacji czytelnika.

W dalszej części tej instrukcji będziemy posługiwać się następującymi nazwami katalogów:

1. 4.0- katalog główny aplikacji czytelnika w wersji 4.0,
2. 5.0- katalog główny aplikacji czytelnika w wersji 5.0.

Proces migracji praktycznie sprowadza się do porównywania zawartości plików oraz katalogów między wersją 4.0 a 5.0 Aplikacji Czytelnika, stąd przydatnym w tej sytuacji może być odpowiednie narzędzie wspomagające ten proces. Jednym z takich narzędzi jest oprogramowanie
Total Commander.

Przenoszenie konfiguracji z wersji 4.0 do 5.0

Jeśli jakiś plik konfiguracyjny nie został uwzględniony w tej instrukcji, oznacza to, iż jego struktura nie uległa zmianie w stosunku do wersji 4.0. Jeśli administrator wprowadzał w nim własne zmiany, powinny one być przeniesione do pliku w wersji 5.0 Aplikacji Czytelnika.

Katalog główny:

• Zawartość katalogu 4.0/exlibris skopiować do katalogu 5.0/exlibris.
• Katalog 4.0/stats skopiować w całości do katalogu 5.0.
• Plik 4.0/robots.txt skopiować do katalogu 5.0.

Katalog /styles:

Jeśli w ramach danej biblioteki cyfrowej zmieniane były pliki graficzne specjalnie na jej potrzeby, wówczas można przekopiować te pliki graficzne i nadpisać istniejące. Pozostałe pliki graficzne, tj. te które były dostarczone z wersją 4.0 nie powinny być kopiowane do wersji 5.0.

Podmiana tematów graficznych Istniejące w wersji 5.0 tematy graficzne zostały zmienione i uzupełnione o nowe pliki .css, nowe wartości w plikach .css, nowe pliki graficzne. Jeśli administratorzy systemu utworzyli własny temat graficzny bądź zmienili istniejący wówczas wymagane będzie porównanie plików z wersji 4.0 i 5.0 z uwzględnieniem zmian dodanych w nowej wersji. Wprowadzenie tego może być niezbędne do prawidłowego funkcjonowania aplikacji czytelnika. Pomocne mogą okazać się następujące narzędzia: Firebug wtyczka dla przeglądarki Firefox, Firefox developer toolbar Internet Explorer Developer Toolbar (dla IE w wersji 6 i 7), Firebug Lite okrojona wersja wtyczki Firebug, można ją zastosować również w innych przeglądarkach.

Katalog /WEB-INF:

• ignored_agents.txt – w najnowszej wersji Aplikacji Czytelnika konfiguracja pobierana jest ze zdalnego adresu (domyślnie: http://dlibra.psnc.pl/ignored_agents.txt), za pomocą zadania okresowego IgnoredAgentsUpdatingTask. W przypadku, gdyby pobranie pliku ze wspomnianego adresu było niemożliwe, zadanie okresowe wczyta dane z pliku umieszczonego w danej aplikacji czytelnika. Jeśli administrator preferuje użycie własnego pliku ignored_agents.txt wówczas może nadpisać plik w wersji 5.0 tym z wersji 4.0 i usunąć deklarację zadania okresowego IgnoredAgentsUpdatingTask z pliku periodic.xml.

• ignored_ips.txt – nadpisać nowy plik z wersji 5.0 plikiem z wersji 4.0.
• templates.properties – porównać zawartość plików z wersji 4.0 oraz 5.0 i wartości parametrów istniejących w wersji 4.0 wstawić jako wartości tych samych parametrów w wersji 5.0.
• components.xml – dla linii:
  wstawić w miejsce 'xxx' oraz 'yyy' odpowiadające im wartości z wersji 4.0 pliku. W przypadku braku wartości parametru recommendedId w wersji 4.0 należy wstawić tutaj wartość -1. Znaczenie tego parametru opisane zostało w końcowej części tej instrukcji, w sekcji "Na co warto zwrócić uwagę po migracji?". Poza tym dla tych parametrów komponentów, których wartości domyślne w wersji 4.0 były zmieniane w celu dostosowania interfejsu danej biblioteki cyfrowej, należy stosowne zmiany wprowadzić ponownie w wartościach tych parametrów w wersji 5.0. UWAGA: Wyjątkiem jest tutaj wartość parametru ?main.app.jar.name" komponentu JnlpComponent, dla którego powinno się pozostawić wartość z wersji 5.0.
• pages.xml - Zalecane jest zachowanie pliku pochodzącego z wersji 5.0 i ewentualne ponowne wprowadzenie zmian wykonanych w wersji 4.0 np. w celu dostosowania wyglądu interfejsu Aplikacji Czytelnika. Przy wprowadzaniu zmian w pliku pages.xml w wersji 5.0 na podstawie pliku z wersji 4.0 należy mieć na uwadze następujące zmiany:
  • W wersji 5.0 usunięte zostały elementy XML (oznaczone znacznikami <page>) odpowiadające stronom: doccontent, doccontent2, content-top, content-sidebar, admin-doctype-edit oraz admin-doctype-list oraz account-moderation.
  • Usunięte zostały również następujące komponenty (oznaczone znacznikami <component>) występujące w definicjach stron zawartych w pliku pages.xml: DocTypesListComponent, SingleDoctypePageComponent, AddPublicTagComponent, AccountTagsComponent.
• periodic.xml - W zadaniu okresowym JCRBackupTask, w pliku z wersji 5.0, upewnić się, że w parametrze ?jcr.backup.dir" podana jest ścieżka do istniejącego katalogu, który ma być wykorzystywany do składowania kopii zapasowych JCR. Więcej na temat mechanizmu kopii zapasowych JCR tutaj.
• web.xml - Wszystkie nowe wpisy z wersji 5.0 powinny zostać nienaruszone. Manualne zmiany wprowadzone przez administratorów do wersji 4.0 pliku powinny być przeniesione do wersji 5.0, przy czym poza wyjątkowymi przypadkami nie powinny być edytowane inne elementy pliku web.xml, niż wartości wewnątrz znacznika <param-value> znajdującego się w znaczniku <context-param>.

Katalog /WEB-INF/components/templates

Jeśli katalog ten zawiera pliki nadpisujące domyślne szablony komponentów lub makra systemu dLibra, wówczas koniecznym może się okazać ponowne porównanie tych plików z pierwowzorami z wersji 5.0. W najnowszej wersji aplikacji czytelnika część szablonów komponentów oraz makr uległa bowiem istotnym zmianom. Szczególną uwagę należy zwrócić na plik custom_library.vm. Jeśli plik ten zawiera deklaracje nadpisujące makra istniejące w pliku makr domyślnych component_library.vm, wówczas koniecznym może się okazać przerobienie kodów makr nadpisujących. W najnowszej wersji aplikacji czytelnika wiele makr domyślnych uległo zmianie.

Katalog /WEB-INF/components/resources/

Jeśli katalog ten zawiera pliki .xml etykiet, nadpisujące domyślne pliki etykiet komponentów, wówczas koniecznym może się okazać ponowne porównanie tych plików z pierwowzorami z wersji 5.0 – w najnowszej wersji aplikacji czytelnika część plików etykiet uległa bowiem istotnym zmianom.

Jeśli w katalogu z wersji 4.0 zostały zdefiniowane pliki w innych wersjach językowych (prócz angielskiej i polskiej), wówczas należy przenieść te pliki do katalogu wersji 5.0. Powinno się również uwzględnić w tych plikach tłumaczenia nowych kluczy etykiet z wersji 5.0 aplikacji.

Katalog /WEB-INF/conf/

• cache.properties - w wersji 5.0 pliku zmianie uległ parametr ?class.name", pozostałe wartości mogą zostać zastąpione wartościami z wersji 4.0 pliku.
• contentHandlers.properties – w pliku w wersji 5.0 uległa zmianie wartość ?class.name", dodany został parametr ?mimetype.icons.path"; pozostałe parametry: ?format.handlers.conf" oraz ?show.browser.plugin.as.first" można zastąpić wartościami z wersji 4.0;
• jcr.properties – dodane zostały dwa nowe parametry ?jcr.backup.restorer.class" oraz ?jcr.restore.dir", z których ten ostatni powinien wskazywać na konkretny katalog, z którego odczytywane będą pliki kopii zapasowych. Więcej na temat kopii zapasowych JCR tutaj. Parametr ?jcr.working.dir" zastąpić wartością z wersji 4.0 pliku.
• users.properties – w wersji 5.0 zmianie uległa wartość atrybutu ?class.name", dla pozostałych atrybutów można przyjąć wartości z 4.0.
• resource-managers.xml – należy uwzględnić fakt, iż w wersji 5.0 pliku usunięty został wpis dotyczący multipleManager. Jeśli wpis dotyczący guanxi był odkomentowany w wersji 4.0 pliku, należy to uwzględnić w wersji 5.0 pliku.

Katalog /WEB-INF/layout/resources/

Należy porównać pliki z wersji 4.0 z wersją z 5.0 i dla wszystkich jednakowych kluczy uwzględnić etykiety z wersji 4.0. W przypadku istnienia plików w innych wersjach językowych, niż tylko w języku angielskim i polskim, należy przekopiować je do katalogu w wersji 5.0. Powinno się również uwzględnić w tych plikach tłumaczenia nowych kluczy etykiet.

Katalog /WEB-INF/layout/templates/

Jeśli pliki w wersji 4.0 były zmieniane przez administratora (np. w celu wstawienia kodu Google Analytics w stopce każdej ze stron WWW), może on je porównać z tymi z wersji 5.0 i przenieść ewentualne zmiany, mając na uwadze nowe wpisy.

Czynności do wykonania po przeniesieniu konfiguracji z wersji 4.0 do 5.0

Po wykonaniu opisanych powyżej kroków powinno być możliwe uruchomienie Aplikacji Czytelnika. Po uruchomieniu należy sprawdzić, czy wygląd i funkcjonalność stron biblioteki cyfrowej są zgodne z oczekiwaniami. Ponadto należy wykonać następujące czynności:

• W panelu administracyjnym (dostępnym pod adresem <główny adres biblioteki cyfrowej>/dlibra/admin), w sekcji "Strony pomocy" należy kliknąć w znajdujący się u góry strony link "Importuj z XML". Następnie należy wskazać plik migrate-help-pages.xml znajdujący się w katalogu 5.0/WEB-INF/defaults, zaznaczyć opcję ?zastąp istniejące strony nowymi" i kliknąć ?Zatwierdź". Operacja ta spowoduje dodanie nowych, nie dostępnych wcześniej stron informacyjnych oraz uaktualnienie informacji o oprogramowaniu dLibra.

TODO: CZY TO CO PONIŻEJ MA BYĆ POŁĄCZONE DLA WSZYSTKICH KOMPONENTÓW SYSTEMU? CHYBA TAK.

Na co warto zwrócić uwagę po migracji?

• Konfiguracja miniatur – inna niż domyślna. Miniatury pojawiające się w Aplikacji Czytelnika, w wersji systemu dLibra 4.0, przekazywane były przez serwer w formie niezmienionej w stosunku do tych wprowadzonych przez redaktorów. W wersji 5.0 systemu miniatury zwracane są przez serwer w postaci przeskalowanej, tak aby przy jednocześnie optymalnej jakości miniatur, zwiększyć prędkość ich przesyłania. Istnieje możliwość konfigurowania pewnych atrybutów automatycznego przetwarzania miniatury przed udostępnieniem, tj. rozdzielczości, formatu pliku, sposobu kadrowania miniatury oraz jakości kompresji. Warto na to zwrócić uwagę, gdy po migracji do wersji 5.0 jakość miniatury prezentowanej na stronie z opisem publikacji będzie niezadowalająca.
  Więcej na ten temat można znaleźć w dokumentacji.
• Konfiguracja podpowiedzi z opisem publikacji. Na głównej stronie w sekcjach ?Ostatnio dodane" oraz ?Najczęściej czytane" po najechaniu myszką na wybrany tytuł publikacji pojawia się podpowiedź przedstawiająca dodatkowe metadane publikacji. Administratorzy mają możliwość skonfigurowania przedstawianych w ramce elementów opisu. Więcej na ten tematu w sekcji dokumentacji.
• Integracja z serwisem społecznościowym Facebook. W najnowszej dLibrze zostały dodany komponent, który umożliwia rejestrowanie fanów danej instytucji czy biblioteki cyfrowej. Więcej na ten temat można znaleźć w dokumentacji.
• Komponent - Polecane. Niejednokrotnie w zbiorach naszej biblioteki cyfrowej pojawiają się publikacje, których obecność chcielibyśmy wyróżnić naszym czytelnikom. Ciekawym w tym wypadku rozwiązaniem może być komponent "Polecane", który w losowy sposób, z domyślnej lub wskazanej przez administratora kolekcji, wybiera publikacje i prezentuje je w formie pokazu slajdów.
  Więcej na temat konfiguracji komponentu można się dowiedzieć z sekcji dokumentacji.